Generate Edit Schema

Use POST /edit_schemas/generate to detect fields in a PDF form and return an EditRootJSON schema you can use with /edit or /edit_runs.

This endpoint is synchronous. It returns the generated schema directly, so there are no schema generation run objects, polling endpoints, or delete endpoints.

In the SDKs, this endpoint is exposed as client.editSchemas.generate() in TypeScript, client.edit_schemas.generate() in Python, and client.editSchemas().generate() in Java.

This is useful when you:

Need a starter schema for a new PDF form
Want to map an existing schema onto a vendor-specific layout
Need annotated field locations before running edit at scale
Want to add conditional form logic on top of detected fields

Quick Start

The endpoint path is the same in both versions, but the raw request body differs:

2026-02-09 uses file.url / file.id
2025-04-21 uses file.fileUrl / file.fileId

API Version `2026-02-09`

$ curl -X POST https://api.extend.ai/edit_schemas/generate \
>   -H "Authorization: Bearer <API_TOKEN>" \
>   -H "Content-Type: application/json" \
>   -H "x-extend-api-version: 2026-02-09" \
>   -d '{
>     "file": {
>       "url": "https://example.com/form.pdf"
>     },
>     "config": {
>       "instructions": "Detect the form fields and use human-readable field names.",
>       "advancedOptions": {
>         "radioEnumsEnabled": true
>       }
>     }
>   }'

API Version `2025-04-21`

$ curl -X POST https://api.extend.ai/edit_schemas/generate \
>   -H "Authorization: Bearer <API_TOKEN>" \
>   -H "Content-Type: application/json" \
>   -H "x-extend-api-version: 2025-04-21" \
>   -d '{
>     "file": {
>       "fileUrl": "https://example.com/form.pdf"
>     },
>     "config": {
>       "instructions": "Detect the form fields and use human-readable field names.",
>       "advancedOptions": {
>         "radioEnumsEnabled": true
>       }
>     }
>   }'

The response body contains:

schema: the final generated schema after mapping; if no inputSchema was provided, this will be the same as annotatedSchema
annotatedSchema: the original schema detected from the file, annotated with field locations
mappingResult: matches and unmatched fields if you provided inputSchema

Request Configuration

Field	API Version	Type	Required	Description
`file`	Both	object	Yes	File to analyze
`file.url`	`2026-02-09`	string	Yes*	URL to download the file
`file.id`	`2026-02-09`	string	Yes*	Existing Extend file ID
`file.fileUrl`	`2025-04-21`	string	Yes*	URL to download the file
`file.fileId`	`2025-04-21`	string	Yes*	Existing Extend file ID
`config.inputSchema`	Both	object	No	Existing edit schema to map onto detected form fields
`config.instructions`	Both	string	No	Additional instructions for field detection and naming
`config.advancedOptions.tableParsingEnabled`	Both	boolean	No	Parse table regions as arrays of objects
`config.advancedOptions.radioEnumsEnabled`	Both	boolean	No	Model radio groups as enum fields
`config.advancedOptions.nativeFieldsOnly`	Both	boolean	No	Only use native AcroForm fields and skip object detection

*Provide one file locator for your API version: url or id in 2026-02-09, or fileUrl or fileId in 2025-04-21.

Conditional Form Editing

The generated schema uses the same EditRootJSON format as edit runs, including support for root-level JSON Schema conditionals like if / then / else, dependentRequired, allOf, oneOf, anyOf, and not.

That means a common workflow is:

Generate a base schema from the PDF form.
Add conditional requirements for follow-up fields.
Use the refined schema with /edit or /edit_runs.

Endpoints

POST /edit_schemas/generate

Generate an edit schema and return the schema payload directly.

This endpoint is available in both API versions 2026-02-09 and 2025-04-21, but the request body field names differ between those versions.

For exact request and response schemas, see the API Reference endpoint for POST /edit_schemas/generate.