> ## 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. # Editing Configuration > Configure the Edit API: natural-language instructions, the edit schema and its extend_edit:* field properties, conditional logic, and advanced options. The Edit API accepts a `config` object that controls how a PDF is filled. You can pin the Edit pipeline with `engineVersion` and drive a run two ways: with natural-language `instructions`, or with an explicit `schema` that pins each field's type, value, and position using `extend_edit:*` keywords. Beyond those, `schemaGenerationInstructions` biases automatic field detection, the schema supports root-level conditional logic to validate fields based on other values, and `advancedOptions` controls flattening, table parsing, field detection, and conditional generation. For default values and the full schema, see the [Create Edit Run API reference](/api-reference/endpoints/edit/create-edit-run). > **Prefer a UI?** [Extend Studio](https://dashboard.extend.ai/studio) lets you configure an editor visually and export the config JSON. --- ## Engine version #### `engineVersion` **Type:** `string` (default: `"0.0.1"`) Pins the Edit engine version used to detect, understand, and fill form fields. Pass an exact version for reproducible results, or `"latest"` to use the latest stable version. The default stable version is `"0.0.1"`; `"1.0.0-beta"` is also available. See the [Edit version changelog](/model-versioning/edit/edit) for details. ```json { "config": { "engineVersion": "0.0.1" } } ``` When you pass `"latest"`, Extend resolves it before starting the run. The run's returned `config.engineVersion` contains the resolved exact version. An unsupported exact version returns a `400` error. --- ## Instructions #### `instructions` **Type:** `string` Natural-language guidance for the edit. Use it to describe the values to fill and any special handling. With instructions only, Extend detects the form's fields and fills the ones you describe. ```json { "config": { "instructions": "Fill out all fields on the form. For the signature field, use 'John Doe'. Leave optional fields blank if no data is provided." } } ``` #### `schemaGenerationInstructions` **Type:** `string` Additional instructions used when Extend generates a schema from the document (when you don't supply one). Useful to bias field detection or naming without writing a full schema yourself. ```json { "config": { "schemaGenerationInstructions": "Detect signature fields, preserve table structure, and use customer-friendly field names." } } ``` --- ## Schema #### `schema` **Type:** `object` A JSON Schema defining the fields to edit. Each property uses `extend_edit:*` keywords to specify the PDF field type, position, value, and styling. If you don't have a schema yet, [Detect Form](/editing/detect-form) detects the fields and returns one with positions annotated. ### Schema types The PDF field type allowed for a property depends on its JSON `type`: | Type | PDF field types | | ------------------------- | --------------------------------- | | `["string", "null"]` | `text`, `signature` | | `["number", "null"]` | `text` | | `["integer", "null"]` | `text` | | `["boolean", "null"]` | `checkbox`, `radio` | | `"array"` | `text`, `table` | | `"object"` | `signature` | | *(no `type`, use `enum`)* | `radio`, `optionList`, `dropdown` | ### Field properties Each field in the schema can include: | Property | Type | Description | | ------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------- | | `type` | string or array | JSON type (see table above). Omit for enum fields. | | `description` | string | Description of the field. | | `extend_edit:field_type` | string | PDF field type: `text`, `checkbox`, `radio`, `dropdown`, `optionList`, `signature`, or `table`. | | `extend_edit:value` | any | The value to fill into this field. If omitted, Extend infers one from the instructions. | | `extend_edit:bbox` | object | Bounding box (`left`, `top`, `right`, `bottom`) for the field location in PDF pixel coordinates. | | `extend_edit:bboxes` | array | Array of bounding boxes for radio enums; the enum at index *i* corresponds to the bbox at index *i*. | | `extend_edit:page_index` | integer | Zero-based page index where the field is placed. | | `extend_edit:image` | object | Image fill for signature fields: `{ "image_url": "https://..." }` (PNG or JPEG only). | | `extend_edit:text_edit_options` | object | Text styling: `combing`, `maxLength`, `multiLine`, `fontSize`, `fontColor` (RGB 0–255), `font`. | | `extend_edit:column_width` | number | Column width as a percentage (table fields). | | `extend_edit:row_heights` | array | Row height percentages for array/table fields. | | `items` | object | Schema for array items (when `type` is `"array"`). | | `properties` | object | Nested field definitions (for `object` types). | | `enum` | array | Allowed values for enum/dropdown/radio fields. | | `maxItems` | integer | Maximum number of rows for array/table fields. | Field positions are in **PDF pixel coordinates**. You rarely write `extend_edit:bbox` by hand β€” [Detect Form](/editing/detect-form) detects a form's fields and returns a schema with positions already annotated. ### Example schema The simplest schema gives each field a `type`, an `extend_edit:field_type`, and an `extend_edit:value`; Extend places it on the detected form field: ```json { "config": { "schema": { "type": "object", "required": ["first_name"], "properties": { "first_name": { "type": ["string", "null"], "description": "The taxpayer's first name and middle initial.", "extend_edit:field_type": "text", "extend_edit:value": "Jordan" }, "last_name": { "type": ["string", "null"], "description": "The taxpayer's last name.", "extend_edit:field_type": "text", "extend_edit:value": "Avery" }, "filing_status_single": { "type": ["boolean", "null"], "description": "Check this box for the Single filing status.", "extend_edit:field_type": "checkbox", "extend_edit:value": true } }, "additionalProperties": false } } } ``` ### Signature image fills For signature fields, provide an image instead of a text value: ```json { "type": "object", "extend_edit:field_type": "signature", "extend_edit:image": { "image_url": "https://example.com/signature.png" } } ``` ### Combed fields For fields that require character-by-character input (SSN, phone numbers, policy numbers), use `combing: true` with a `maxLength`: ```json { "extend_edit:text_edit_options": { "combing": true, "maxLength": 9 } } ``` For fields that should wrap across multiple lines, set `multiLine: true`: ```json { "extend_edit:text_edit_options": { "multiLine": true } } ``` --- ## Conditional form editing Edit schemas support root-level JSON Schema conditionals, so you can make fields required or optional based on other values. Supported keywords include `dependentRequired`, `if` / `then` / `else`, `allOf`, `oneOf`, `anyOf`, and `not`. Conditional clauses do not accept `extend_edit:*` keys. For an introduction to these keywords and additional examples, see [Conditional schema validation](https://json-schema.org/understanding-json-schema/reference/conditionals) in the JSON Schema documentation. ```json { "config": { "schema": { "type": "object", "properties": { "employmentType": { "enum": ["FULL_TIME", "CONTRACTOR"], "extend_edit:field_type": "dropdown" }, "contractEndDate": { "type": ["string", "null"], "extend_edit:field_type": "text" } }, "if": { "properties": { "employmentType": { "enum": ["CONTRACTOR"] } } }, "then": { "required": ["contractEndDate"] } } } } ``` This is useful for forms where follow-up fields only apply to a subset of users. You can write these rules yourself, or [detect a form and generate them from requirements in the form content](/editing/detect-form#generate-conditional-validation-rules). --- ## Advanced options #### `advancedOptions.flattenPdf` **Type:** `boolean` (default: `true`) Flatten PDF forms after editing, making the form fields non-editable. Use when generating final documents. ```json { "config": { "advancedOptions": { "flattenPdf": true } } } ``` #### `advancedOptions.tableParsingEnabled` **Type:** `boolean` (default: `false`) Parse table regions as arrays of objects. Enable for forms with large table regions you want filled. ```json { "config": { "advancedOptions": { "tableParsingEnabled": true } } } ``` #### `advancedOptions.radioEnumsEnabled` **Type:** `boolean` (default: `false`) Model radio fields as enums, ensuring only one radio widget in a group is filled. ```json { "config": { "advancedOptions": { "radioEnumsEnabled": true } } } ``` #### `advancedOptions.nativeFieldsOnly` **Type:** `boolean` (default: `false`) Only import native AcroForm fields from the PDF and skip object detection. ```json { "config": { "advancedOptions": { "nativeFieldsOnly": true } } } ``` #### `advancedOptions.conditionalGenerationEnabled` **Type:** `boolean` (default: `false`) When Extend generates an edit schema, it reads requirements stated in the form and adds supported root-level JSON Schema conditionals that validate the generated field values. For example, a form instruction that requires an explanation after a β€œYes” answer can become an `if` / `then` rule. If an Edit run cannot generate values that satisfy the generated conditionals, the run fails with `SCHEMA_VALIDATION_ERROR`. A synchronous `/edit` request returns that value in the error body's `code`; an asynchronous `/edit_runs` run returns it in `failureReason`. See [Editing Error Handling](/editing/error-handling#failure-reasons). This option applies only when the schema is generated. If you provide `config.schema`, Extend uses that schema as-is; include any conditional validation rules directly in it. ```json { "config": { "advancedOptions": { "conditionalGenerationEnabled": true } } } ``` For the exact request and response schemas, see the [Create Edit Run API reference](/api-reference/endpoints/edit/create-edit-run).