> This page is for version v2025-04-21. > For other versions, use one of these documentation indexes: > - v2026-02-09 (default): https://docs.extend.ai/2026-02-09/llms.txt > - v2025-04-21: https://docs.extend.ai/2025-04-21/llms.txt > - v2024-12-23: https://docs.extend.ai/2024-12-23/llms.txt > ## Documentation Index > Fetch the complete documentation index at: https://docs.extend.ai/llms.txt > Use this file to discover all available pages before exploring further. > > ## API version > The current API version is `2026-02-09`, served at the site root (no version prefix in URLs). > If this page URL contains `/2025-04-21/` or `/2024-12-23/`, you are reading an older API version. > Prefer the current docs at https://docs.extend.ai/llms.txt unless the user explicitly needs that older version. > Do not treat older-version pages as the source of truth for new integrations. # Generate Edit Schema POST https://api.extend.ai/edit_schemas/generate Content-Type: application/json Detect fields in a PDF form and synchronously return an edit schema payload. Use this endpoint when you want Extend to bootstrap an `EditRootJSONSchema` from an existing form, optionally mapping an existing schema onto the detected fields. This endpoint returns the generated schema directly. There are no schema generation run resources to poll or delete. Reference: https://docs.extend.ai/api-reference/endpoints/edit/generate-edit-schema ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Request ### Headers - `x-extend-api-version` ("2025-04-21", optional, default: 2025-04-21) — API version to use for the request. If you do not specify a version, you will either receive a `400 Bad Request` or be set to a previous legacy version. See [API Versioning](https://docs.extend.ai/2025-04-21/developers/api-versioning) for more details. ### Body (application/json) This endpoint expects an object. - `file` (EditSchemasGeneratePostRequestBodyContentApplicationJsonSchemaFile, required) — A file object containing either a URL or a fileId. - `config` (EditSchemaGenerationConfig, optional) — Configuration options for edit schema generation. ## Response ### 200 Successfully generated edit schema - `schema` (EditRootJSONSchema, required) — The final generated schema after mapping. If no input schema was provided this will be the same as the annotatedSchema. - `annotatedSchema` (EditRootJSONSchema, required, nullable) — The original schema that was detected and annotated from the file. - `mappingResult` (EditSchemaGenerationMappingResult, required, nullable) — Mapping information between `inputSchema` paths and detected form fields when an input schema was provided. ## Errors ### 400 Bad Request Error Bad Request - `success` (boolean, optional) - `error` (string, optional) — Error message ### 401 Unauthorized Error Unauthorized - `success` (boolean, optional) - `error` (string, optional) — Error message ### 402 Payment Required Error Payment Required Error - `code` (string, required) — Error code identifying the type of error - `message` (string, required) — Human-readable error message - `requestId` (string, required) — Unique request identifier for support purposes - `retryable` (boolean, required) — Whether the request can be retried ### 404 Not Found Error Not Found Error - `code` (string, required) — Error code identifying the type of error - `message` (string, required) — Human-readable error message - `requestId` (string, required) — Unique request identifier for support purposes - `retryable` (boolean, required) — Whether the request can be retried ### 422 Unprocessable Entity Error Unprocessable Entity - `code` (string, required) — Error code identifying the type of error - `message` (string, required) — Human-readable error message - `requestId` (string, required) — Unique request identifier for support purposes - `retryable` (boolean, required) — Whether the request can be retried ### 500 Internal Server Error Internal Server Error - `code` (string, required) — Error code identifying the type of error - `message` (string, required) — Human-readable error message - `requestId` (string, required) — Unique request identifier for support purposes - `retryable` (boolean, required) — Whether the request can be retried ## Types ### EditSchemasGeneratePostRequestBodyContentApplicationJsonSchemaFile A file object containing either a URL or a fileId. - `fileName` (string, optional) — The name of the file. If not set, the file name is taken from the url. - `fileUrl` (string, optional) — A URL to download the file. For production use cases, we recommend using presigned URLs with a 5-15 minute expiration time. One of `fileUrl` or `fileId` must be provided. - `fileId` (string, optional) — If you already have an Extend file id (for instance from running a workflow or a previous file upload) then you can use that file id when generating an edit schema. The file id will start with "file_". One of `fileUrl` or `fileId` must be provided. Example: `"file_xK9mLPqRtN3vS8wF5hB2cQ"` ### EditSchemaGenerationConfig Configuration options for edit schema generation. - `engineVersion` (string, optional, default: 1.0.0) — The Edit engine version to use for form detection. Use an exact version for reproducible results, or `latest` to use the latest stable version. Defaults to `1.0.0` when omitted. Responses contain the resolved exact version. - `inputSchema` (EditRootJSONSchema, optional) — Optional existing edit schema to map onto the detected form fields. When provided, the response may include a `mappingResult` that shows which input schema paths matched the generated form fields. - `instructions` (string, optional) — Custom instructions provided for schema generation. - `advancedOptions` (EditSchemaGenerationConfigAdvancedOptions, optional) — Advanced options for schema generation. ### EditRootJSONSchema JSON Schema definition for editing PDF documents. The schema defines the structure and placement of fields to edit. It also supports JSON Schema conditional keywords at the root level, including `dependentRequired`, `if` / `then` / `else`, and logical combinators such as `allOf`, `oneOf`, `anyOf`, and `not`. Conditional property constraints do not accept `extend_edit:*` keys, and nested conditional clauses are supported up to 8 levels to match the Studio editor. - `type` (enum, required) — Must be "object" for the root schema - Allowed values: `object` - `properties` (map from string to EditJSONSchema, required) — Map of field names to their schema definitions - `required` (list of string, optional) — List of required field names - `additionalProperties` (boolean, optional) — Whether additional properties are allowed - `dependentRequired` (map from string to list of string, optional) — Map of field names to additional fields that become required when the key field is present. - `if` (EditConditionalClause, optional) — Recursive conditional clause for edit schemas. Use these clauses with root-level `if` / `then` / `else`, `dependentRequired`, and logical combinators to model conditional field requirements. Nested clauses are supported up to 8 levels. - `then` (EditConditionalClause, optional) — Recursive conditional clause for edit schemas. Use these clauses with root-level `if` / `then` / `else`, `dependentRequired`, and logical combinators to model conditional field requirements. Nested clauses are supported up to 8 levels. - `else` (EditConditionalClause, optional) — Recursive conditional clause for edit schemas. Use these clauses with root-level `if` / `then` / `else`, `dependentRequired`, and logical combinators to model conditional field requirements. Nested clauses are supported up to 8 levels. - `allOf` (list of EditConditionalClause, optional) — List of conditional clauses that must all match. - `oneOf` (list of EditConditionalClause, optional) — List of conditional clauses where exactly one must match. - `anyOf` (list of EditConditionalClause, optional) — List of conditional clauses where at least one must match. - `not` (EditConditionalClause, optional) — Recursive conditional clause for edit schemas. Use these clauses with root-level `if` / `then` / `else`, `dependentRequired`, and logical combinators to model conditional field requirements. Nested clauses are supported up to 8 levels. ### EditSchemaGenerationMappingResult Mapping information between an input schema and the detected form fields. - `matches` (list of EditSchemaGenerationMappingMatch, required) — Fields from the input schema that were successfully mapped to detected form fields. - `unmatchedInputPaths` (list of string, required) — Input schema field paths that could not be matched to the form. - `unusedFormFieldKeys` (list of string, required) — Detected form field keys that were not used by the input schema mapping. ### EditSchemaGenerationConfigAdvancedOptions Advanced options for schema generation. - `tableParsingEnabled` (boolean, optional) — Whether to parse table regions as arrays. Defaults to false. - `radioEnumsEnabled` (boolean, optional) — Whether to represent radio groups as enums so only one option can be selected. Defaults to `true` for Edit `1.0.0` and `1.0.0-beta`, and `false` for `0.0.1`. - `nativeFieldsOnly` (boolean, optional) — If enabled, only native AcroForm fields from the PDF will be imported and used in the schema. Defaults to false. - `conditionalGenerationEnabled` (boolean, optional) — When enabled, reads requirements explicitly stated in the form and adds supported root-level JSON Schema conditional validation rules to the generated schema. These rules validate form data when the schema is used for an edit; they do not add interactive UI behavior. If generated edit values do not satisfy the rules, the Edit run fails with `SCHEMA_VALIDATION_ERROR`. Defaults to false. ### EditJSONSchema Schema definition for a field to edit in a PDF. This is a union type that supports: * `EditStringJSONSchema` - type: ["string", "null"], field_type: "text" | "signature" * `EditNumberJSONSchema` - type: ["number", "null"], field_type: "text" * `EditIntegerJSONSchema` - type: ["integer", "null"], field_type: "text" * `EditBooleanJSONSchema` - type: ["boolean", "null"], field_type: "checkbox" | "radio" * `EditArrayJSONSchema` - type: "array", field_type: "text" | "table" * `EditEnumJSONSchema` - has enum property (no type field), field_type: "radio" | "optionList" | "dropdown" * `EditObjectJSONSchema` - type: "object", field_type: "signature" All variants share common `extend_edit:*` properties for positioning and styling. - `type` (any, optional) — The JSON schema type of the field. Can be: * A string: "array" or "object" * A nullable tuple array: ["string", "null"], ["number", "null"], ["integer", "null"], ["boolean", "null"] * Omitted for enum fields (use enum property instead) - `description` (string, optional) — Description of the field - `extend_edit:field_type` (enum, optional) — The PDF field type to edit. Allowed values depend on the schema type: * `["string", "null"]` → `text`, `signature` * `["number", "null"]` → `text` * `["integer", "null"]` → `text` * `["boolean", "null"]` → `checkbox`, `radio` * `"array"` → `text`, `table` * `"object"` → `signature` * enum fields (no type) → `radio`, `optionList`, `dropdown` - Allowed values: `text`, `checkbox`, `radio`, `dropdown`, `optionList`, `signature`, `table`, `unknown` - `extend_edit:bbox` (EditBoundingBox, optional) — Bounding box coordinates for the field location in the PDF (pixel coordinates) - `extend_edit:bboxes` (list of EditBoundingBox, optional) — Array of bounding boxes for radio enums. Enum at index i corresponds to bbox at index i. - `extend_edit:page_index` (integer, optional) — Zero-based page index where the field should be placed - `extend_edit:text_edit_options` (EditTextOptions, optional) — Text styling options for text fields - `extend_edit:column_width` (double, optional) — Width of the column as a percentage (for table fields) - `extend_edit:source_acroform` (EditSourceAcroForm, optional) — Details about the original PDF form field. When Detect Form returns this property, include it unchanged in Edit requests. - `extend_edit:value` (any, optional) — The value to fill into this field. Can be any type. This will force the value at this field to be filled with this value. If a value is not provided, we will attempt to generate or infer one based on the instructions. - `extend_edit:image` (EditJsonSchemaExtendEditImage, optional) — Image fill for signature fields. Only PNG and JPEG image URLs are supported. - `extend_edit:row_heights` (list of double, optional) — Array of row height percentages for array/table fields (e.g. [0.25, 0.50, 0.25]) - `items` (EditObjectJSONSchema, optional) — Schema for array items (when type is "array"). Must be an EditObjectJSONSchema. - `properties` (map from string to EditJSONSchema, optional) — Nested properties for object types. Each property follows the EditJSONSchema structure. - `enum` (list of string, optional) — Allowed values for enum/dropdown/radio fields - `extend:descriptions` (list of string, optional) — Human-readable labels for the values in `enum`, in the same order. Include this property when using a schema returned by Detect Form. - `maxItems` (integer, optional) — Maximum number of rows for array/table fields - `required` (list of string, optional) — List of required property names (for object types) - `additionalProperties` (boolean, optional) — Whether additional properties are allowed (for object types) ### EditConditionalClause Recursive conditional clause for edit schemas. Use these clauses with root-level `if` / `then` / `else`, `dependentRequired`, and logical combinators to model conditional field requirements. Nested clauses are supported up to 8 levels. - `properties` (map from string to EditConditionalPropertySchema, optional) — Conditional field constraints keyed by top-level property name. - `required` (list of string, optional) — List of fields that must be present when this clause applies. - `dependentRequired` (map from string to list of string, optional) — Map of field names to additional fields that become required when the key field is present. - `if` (EditConditionalClause, optional) — Recursive conditional clause for edit schemas. Use these clauses with root-level `if` / `then` / `else`, `dependentRequired`, and logical combinators to model conditional field requirements. Nested clauses are supported up to 8 levels. - `then` (EditConditionalClause, optional) — Recursive conditional clause for edit schemas. Use these clauses with root-level `if` / `then` / `else`, `dependentRequired`, and logical combinators to model conditional field requirements. Nested clauses are supported up to 8 levels. - `else` (EditConditionalClause, optional) — Recursive conditional clause for edit schemas. Use these clauses with root-level `if` / `then` / `else`, `dependentRequired`, and logical combinators to model conditional field requirements. Nested clauses are supported up to 8 levels. - `allOf` (list of EditConditionalClause, optional) — List of nested conditional clauses that must all match. - `oneOf` (list of EditConditionalClause, optional) — List of nested conditional clauses where exactly one must match. - `anyOf` (list of EditConditionalClause, optional) — List of nested conditional clauses where at least one must match. - `not` (EditConditionalClause, optional) — Recursive conditional clause for edit schemas. Use these clauses with root-level `if` / `then` / `else`, `dependentRequired`, and logical combinators to model conditional field requirements. Nested clauses are supported up to 8 levels. ### EditSchemaGenerationMappingMatch A successful mapping between an input schema path and a detected form field. - `inputPath` (string, required) — The path from the provided `inputSchema`. - `formFieldKey` (string, required) — The detected form field key matched to the input path. ### EditBoundingBox Bounding box coordinates for the field location in the PDF (pixel coordinates) - `left` (double, required) — The left coordinate of the bounding box (pixels) - `top` (double, required) — The top coordinate of the bounding box (pixels) - `right` (double, required) — The right coordinate of the bounding box (pixels) - `bottom` (double, required) — The bottom coordinate of the bounding box (pixels) ### EditTextOptions Text styling options for text fields - `fontSize` (double, optional) — Font size in points - `color` (list of integer, optional) — RGB color values from 0 to 255 for text color. - `opacity` (double, optional) — Text opacity from 0 to 1. Defaults to 1. - `font` (string, optional) — Font family name - `combing` (boolean, optional) — Whether this is a combed field (like SSN fields with individual character boxes) - `maxLength` (integer, optional) — Maximum number of characters allowed - `multiLine` (boolean, optional) — Whether text can wrap across multiple lines - `fontColor` (list of integer, optional, deprecated) — Deprecated alias for `color`. RGB color values from 0 to 255. ### EditSourceAcroForm Details about the original PDF form field. When Detect Form returns this property, include it unchanged in Edit requests. - `fieldName` (string, required) — Name of the PDF form field. - `fieldType` (enum, required) — Type of the original native PDF field. - Allowed values: `text`, `checkbox`, `radio`, `dropdown`, `optionList`, `signature` - `optionMap` (list of EditSourceAcroFormOption, optional) — Supported choices for radio, dropdown, and option-list fields. - `optionValue` (string, optional) — Value used when this option is selected. ### EditJsonSchemaExtendEditImage Image fill for signature fields. Only PNG and JPEG image URLs are supported. - `image_url` (string, required) — URL of the image to place in the signature field. ### EditObjectJSONSchema Schema definition for an object field in a PDF edit schema. Used for signature fields and as items schema for arrays/tables. - `type` (enum, optional) — Must be "object" for object schemas - Allowed values: `object` - `description` (string, optional) — Description of the field - `extend_edit:field_type` (enum, optional) — The PDF field type. For object schemas, must be "signature". - Allowed values: `signature` - `properties` (map from string to EditJSONSchema, optional) — Nested properties. Each property follows the EditJSONSchema structure. - `required` (list of string, optional) — List of required property names - `additionalProperties` (boolean, optional) — Whether additional properties are allowed ### EditConditionalPropertySchema Field-level schema fragment used inside conditional clauses. These condition objects support nested JSON Schema structure such as `type`, `enum`, `items`, `properties`, `required`, and `contains`, but do not allow any `extend_edit:*` placement or styling keys. - `type` (any, optional) — JSON Schema type for the conditional property. Can be a simple type such as `"object"` or `"array"`, a nullable tuple like `["string", "null"]`, or omitted for enum-only constraints. - `description` (string, optional) — Description of the field constraint. - `enum` (list of EditConditionalPropertySchemaEnumItems, optional) — Allowed values for enum-based conditional constraints. - `items` (EditConditionalPropertySchema, optional) — Nested array item schema for conditional array constraints. - `properties` (map from string to EditConditionalPropertySchema, optional) — Nested object property constraints. - `required` (list of string, optional) — Required nested object properties. - `additionalProperties` (boolean, optional) — Whether additional nested object properties are allowed. - `const` (any, optional) — Exact value that the property must match. - `pattern` (string, optional) — Regular expression that string values must match. - `contains` (EditConditionalPropertySchema, optional) — Conditional schema that at least one array item must satisfy. - `minimum` (double, optional) — Inclusive lower bound for numeric values. - `maximum` (double, optional) — Inclusive upper bound for numeric values. - `exclusiveMinimum` (double, optional) — Exclusive lower bound for numeric values. - `exclusiveMaximum` (double, optional) — Exclusive upper bound for numeric values. - `minLength` (integer, optional) — Minimum string length. - `maxLength` (integer, optional) — Maximum string length. - `minItems` (integer, optional) — Minimum number of array items. - `maxItems` (integer, optional) — Maximum number of array items. - `minContains` (integer, optional) — Minimum number of matching items for `contains`. - `maxContains` (integer, optional) — Maximum number of matching items for `contains`. ### EditSourceAcroFormOption A supported choice for a PDF form field. - `schemaValue` (string, required) — Value used in the Edit schema. - `exportValue` (string, required) — Value used by the PDF form field. - `displayValue` (string, required) — Label shown in the PDF form. ### EditConditionalPropertySchemaEnumItems ## Examples **Request** ```json { "file": { "fileUrl": "https://example.com/form.pdf" }, "config": { "instructions": "Detect the form fields and use human-readable field names.", "advancedOptions": { "radioEnumsEnabled": true } } } ``` **Response** ```json { "schema": { "type": "object", "properties": {}, "required": [ "string" ], "additionalProperties": true, "dependentRequired": {}, "if": { "properties": {}, "required": [ "string" ], "dependentRequired": {}, "allOf": [ null ], "oneOf": [ null ], "anyOf": [ null ] }, "then": { "properties": {}, "required": [ "string" ], "dependentRequired": {}, "allOf": [ null ], "oneOf": [ null ], "anyOf": [ null ] }, "else": { "properties": {}, "required": [ "string" ], "dependentRequired": {}, "allOf": [ null ], "oneOf": [ null ], "anyOf": [ null ] }, "allOf": [ { "properties": {}, "required": [ "string" ], "dependentRequired": {}, "allOf": [ null ], "oneOf": [ null ], "anyOf": [ null ] } ], "oneOf": [ { "properties": {}, "required": [ "string" ], "dependentRequired": {}, "allOf": [ null ], "oneOf": [ null ], "anyOf": [ null ] } ], "anyOf": [ { "properties": {}, "required": [ "string" ], "dependentRequired": {}, "allOf": [ null ], "oneOf": [ null ], "anyOf": [ null ] } ], "not": { "properties": {}, "required": [ "string" ], "dependentRequired": {}, "allOf": [ null ], "oneOf": [ null ], "anyOf": [ null ] } }, "annotatedSchema": { "type": "object", "properties": {}, "required": [ "string" ], "additionalProperties": true, "dependentRequired": {}, "if": { "properties": {}, "required": [ "string" ], "dependentRequired": {}, "allOf": [ null ], "oneOf": [ null ], "anyOf": [ null ] }, "then": { "properties": {}, "required": [ "string" ], "dependentRequired": {}, "allOf": [ null ], "oneOf": [ null ], "anyOf": [ null ] }, "else": { "properties": {}, "required": [ "string" ], "dependentRequired": {}, "allOf": [ null ], "oneOf": [ null ], "anyOf": [ null ] }, "allOf": [ { "properties": {}, "required": [ "string" ], "dependentRequired": {}, "allOf": [ null ], "oneOf": [ null ], "anyOf": [ null ] } ], "oneOf": [ { "properties": {}, "required": [ "string" ], "dependentRequired": {}, "allOf": [ null ], "oneOf": [ null ], "anyOf": [ null ] } ], "anyOf": [ { "properties": {}, "required": [ "string" ], "dependentRequired": {}, "allOf": [ null ], "oneOf": [ null ], "anyOf": [ null ] } ], "not": { "properties": {}, "required": [ "string" ], "dependentRequired": {}, "allOf": [ null ], "oneOf": [ null ], "anyOf": [ null ] } }, "mappingResult": { "matches": [ { "inputPath": "applicant.address.street", "formFieldKey": "applicant_address_street" } ], "unmatchedInputPaths": [ "string" ], "unusedFormFieldKeys": [ "string" ] } } ```