Extend Edit Schemas API

openapi: 3.2.0
info:
  title: Reference Edit Schemas API
  version: 1.0.0
servers:
- url: https://api.extend.ai
  description: Production
- url: https://api.us2.extend.app
  description: Production US2
- url: https://api.eu1.extend.ai
  description: Production EU1
tags:
- name: editSchemas
paths:
  /edit_schemas/generate:
    post:
      operationId: editSchemas_generate
      summary: Generate Edit Schema
      description: '**Deprecated:** Use `POST /detect_form` for synchronous form detection or `POST /form_detection_runs` for asynchronous processing.


        Detect fields in a PDF form and synchronously return an edit schema payload.


        Use this endpoint when you want Extend to bootstrap an `EditRootJSON` schema 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.


        For more details, see the Detect Form guide and the Edit File guide.'
      tags:
      - editSchemas
      parameters:
      - name: x-extend-api-version
        in: header
        description: API version to use for the request. If you're using an SDK, you can ignore this parameter. If you are not using an SDK and 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/2026-02-09/api-reference/api-versioning) for more details.
        required: false
        schema:
          type: string
          enum:
          - '2026-02-09'
          default: '2026-02-09'
      responses:
        '200':
          description: Successfully generated edit schema
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EditSchemaGenerationResponse'
        '400':
          description: 'Standard error response format for all Extend API errors.


            See the [Error Codes documentation](https://docs.extend.ai/2026-02-09/api-reference/error-handling) for error handling recommendations.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: 'Standard error response format for all Extend API errors.


            See the [Error Codes documentation](https://docs.extend.ai/2026-02-09/api-reference/error-handling) for error handling recommendations.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '402':
          description: 'Standard error response format for all Extend API errors.


            See the [Error Codes documentation](https://docs.extend.ai/2026-02-09/api-reference/error-handling) for error handling recommendations.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: 'Standard error response format for all Extend API errors.


            See the [Error Codes documentation](https://docs.extend.ai/2026-02-09/api-reference/error-handling) for error handling recommendations.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: 'Standard error response format for all Extend API errors.


            See the [Error Codes documentation](https://docs.extend.ai/2026-02-09/api-reference/error-handling) for error handling recommendations.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '422':
          description: 'Standard error response format for all Extend API errors.


            See the [Error Codes documentation](https://docs.extend.ai/2026-02-09/api-reference/error-handling) for error handling recommendations.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: 'Standard error response format for all Extend API errors.


            See the [Error Codes documentation](https://docs.extend.ai/2026-02-09/api-reference/error-handling) for error handling recommendations.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: 'Standard error response format for all Extend API errors.


            See the [Error Codes documentation](https://docs.extend.ai/2026-02-09/api-reference/error-handling) for error handling recommendations.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      deprecated: true
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                file:
                  $ref: '#/components/schemas/EditSchemasGeneratePostRequestBodyContentApplicationJsonSchemaFile'
                  description: The file to analyze. Files can be provided as a URL or an Extend file ID.
                config:
                  $ref: '#/components/schemas/EditSchemaGenerationConfig'
              required:
              - file
      security:
      - BearerAuth: []
components:
  schemas:
    EditSchemaGenerationMappingResult:
      type: object
      properties:
        matches:
          type: array
          items:
            $ref: '#/components/schemas/EditSchemaGenerationMappingMatch'
          description: Fields from the input schema that were successfully mapped to detected form fields.
        unmatchedInputPaths:
          type: array
          items:
            type: string
          description: Input schema field paths that could not be matched to the form.
        unusedFormFieldKeys:
          type: array
          items:
            type: string
          description: Detected form field keys that were not used by the input schema mapping.
      required:
      - matches
      - unmatchedInputPaths
      - unusedFormFieldKeys
      description: Mapping information between an input schema and the detected form fields.
      title: EditSchemaGenerationMappingResult
    EditRootJsonType:
      type: string
      enum:
      - object
      description: Must be "object" for the root schema
      title: EditRootJsonType
    EditObjectJsonExtendEditFieldType:
      type: string
      enum:
      - signature
      description: The PDF field type. For object schemas, must be "signature".
      title: EditObjectJsonExtendEditFieldType
    EditObjectJSON:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/EditObjectJsonType'
          description: Must be "object" for object schemas
        description:
          type: string
          description: Description of the field
        extend_edit:field_type:
          $ref: '#/components/schemas/EditObjectJsonExtendEditFieldType'
          description: The PDF field type. For object schemas, must be "signature".
        properties:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/EditJSON'
          description: Nested properties. Each property follows the EditJSON structure.
        required:
          type: array
          items:
            type: string
          description: List of required property names
        additionalProperties:
          type: boolean
          description: Whether additional properties are allowed
      description: 'Schema definition for an object field in a PDF edit schema. Used for signature fields and as items schema for arrays/tables.

        '
      title: EditObjectJSON
    EditObjectJsonType:
      type: string
      enum:
      - object
      description: Must be "object" for object schemas
      title: EditObjectJsonType
    EditDependentRequired:
      type: object
      additionalProperties:
        type: array
        items:
          type: string
      description: Map of field names to additional fields that become required when the key field is present.
      title: EditDependentRequired
    EditConditionalClause:
      type: object
      properties:
        properties:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/EditConditionalProperty'
          description: Conditional field constraints keyed by top-level property name.
        required:
          type: array
          items:
            type: string
          description: List of fields that must be present when this clause applies.
        dependentRequired:
          $ref: '#/components/schemas/EditDependentRequired'
        if:
          $ref: '#/components/schemas/EditConditionalClause'
        then:
          $ref: '#/components/schemas/EditConditionalClause'
        else:
          $ref: '#/components/schemas/EditConditionalClause'
        allOf:
          type: array
          items:
            $ref: '#/components/schemas/EditConditionalClause'
          description: List of nested conditional clauses that must all match.
        oneOf:
          type: array
          items:
            $ref: '#/components/schemas/EditConditionalClause'
          description: List of nested conditional clauses where exactly one must match.
        anyOf:
          type: array
          items:
            $ref: '#/components/schemas/EditConditionalClause'
          description: List of nested conditional clauses where at least one must match.
        not:
          $ref: '#/components/schemas/EditConditionalClause'
      description: 'Recursive conditional clause for edit schemas. Use these clauses with root-level `if` / `then` / `else`,

        `dependentRequired`, and logical combinators to model conditional field requirements.

        '
      title: EditConditionalClause
    EditJSON:
      type: object
      properties:
        type:
          description: '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:
          type: string
          description: Description of the field
        extend_edit:field_type:
          $ref: '#/components/schemas/EditJsonExtendEditFieldType'
          description: '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`

            '
        extend_edit:bbox:
          $ref: '#/components/schemas/EditBoundingBox'
        extend_edit:bboxes:
          type: array
          items:
            $ref: '#/components/schemas/EditBoundingBox'
          description: Array of bounding boxes for radio enums. Enum at index i corresponds to bbox at index i.
        extend_edit:page_index:
          type: integer
          description: Zero-based page index where the field should be placed
        extend_edit:text_edit_options:
          $ref: '#/components/schemas/EditTextOptions'
        extend_edit:column_width:
          type: number
          format: double
          description: Width of the column as a percentage (for table fields)
        extend_edit:source_acroform:
          $ref: '#/components/schemas/EditSourceAcroForm'
        extend_edit:value:
          description: 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:
          $ref: '#/components/schemas/EditJsonExtendEditImage'
          description: Image fill for signature fields. Only PNG and JPEG image URLs are supported.
        extend_edit:row_heights:
          type: array
          items:
            type: number
            format: double
          description: Array of row height percentages for array/table fields (e.g. [0.25, 0.50, 0.25])
        items:
          $ref: '#/components/schemas/EditObjectJSON'
          description: Schema for array items (when type is "array"). Must be an EditObjectJSON.
        properties:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/EditJSON'
          description: Nested properties for object types. Each property follows the EditJSON structure.
        enum:
          type: array
          items:
            type: string
          description: Allowed values for enum/dropdown/radio fields
        extend:descriptions:
          type: array
          items:
            type: string
          description: Human-readable labels for the values in `enum`, in the same order. Include this property when using a schema returned by Detect Form.
        maxItems:
          type: integer
          description: Maximum number of rows for array/table fields
        required:
          type: array
          items:
            type: string
          description: List of required property names (for object types)
        additionalProperties:
          type: boolean
          description: Whether additional properties are allowed (for object types)
      description: '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"

        * `EditObjectJSON` - type: "object", field_type: "signature"


        All variants share common `extend_edit:*` properties for positioning and styling.

        '
      title: EditJSON
    EditConditionalProperty:
      type: object
      properties:
        type:
          description: '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:
          type: string
          description: Description of the field constraint.
        enum:
          type: array
          items:
            oneOf:
            - $ref: '#/components/schemas/EditConditionalPropertyEnumItems'
            - type: 'null'
          description: Allowed values for enum-based conditional constraints.
        items:
          $ref: '#/components/schemas/EditConditionalProperty'
          description: Nested array item schema for conditional array constraints.
        properties:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/EditConditionalProperty'
          description: Nested object property constraints.
        required:
          type: array
          items:
            type: string
          description: Required nested object properties.
        additionalProperties:
          type: boolean
          description: Whether additional nested object properties are allowed.
        const:
          description: Exact value that the property must match.
        pattern:
          type: string
          description: Regular expression that string values must match.
        contains:
          $ref: '#/components/schemas/EditConditionalProperty'
          description: Conditional schema that at least one array item must satisfy.
        minimum:
          type: number
          format: double
          description: Inclusive lower bound for numeric values.
        maximum:
          type: number
          format: double
          description: Inclusive upper bound for numeric values.
        exclusiveMinimum:
          type: number
          format: double
          description: Exclusive lower bound for numeric values.
        exclusiveMaximum:
          type: number
          format: double
          description: Exclusive upper bound for numeric values.
        minLength:
          type: integer
          description: Minimum string length.
        maxLength:
          type: integer
          description: Maximum string length.
        minItems:
          type: integer
          description: Minimum number of array items.
        maxItems:
          type: integer
          description: Maximum number of array items.
        minContains:
          type: integer
          description: Minimum number of matching items for `contains`.
        maxContains:
          type: integer
          description: Maximum number of matching items for `contains`.
      description: '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.

        '
      title: EditConditionalProperty
    EditJsonExtendEditImage:
      type: object
      properties:
        image_url:
          type: string
          description: URL of the image to place in the signature field.
      required:
      - image_url
      description: Image fill for signature fields. Only PNG and JPEG image URLs are supported.
      title: EditJsonExtendEditImage
    EditConditionalPropertyEnumItems:
      oneOf:
      - type: string
      - type: number
        format: double
      - type: boolean
      title: EditConditionalPropertyEnumItems
    EditSourceAcroFormFieldType:
      type: string
      enum:
      - text
      - checkbox
      - radio
      - dropdown
      - optionList
      - signature
      description: Type of the original native PDF field.
      title: EditSourceAcroFormFieldType
    EditSchemasGeneratePostRequestBodyContentApplicationJsonSchemaFile:
      oneOf:
      - $ref: '#/components/schemas/FileFromUrl'
      - $ref: '#/components/schemas/FileFromId'
      description: The file to analyze. Files can be provided as a URL or an Extend file ID.
      title: EditSchemasGeneratePostRequestBodyContentApplicationJsonSchemaFile
    EditSchemaGenerationMappingMatch:
      type: object
      properties:
        inputPath:
          type: string
          description: The path from the provided `inputSchema`.
        formFieldKey:
          type: string
          description: The detected form field key matched to the input path.
      required:
      - inputPath
      - formFieldKey
      description: A successful mapping between an input schema path and a detected form field.
      title: EditSchemaGenerationMappingMatch
    FileFromId:
      type: object
      properties:
        id:
          type: string
          description: 'An Extend file ID.


            Example: `"file_xK9mLPqRtN3vS8wF5hB2cQ"`

            '
      required:
      - id
      description: 'An Extend file ID (for instance from another run or a previous file upload).

        '
      title: FileFromId
    EditJsonExtendEditFieldType:
      type: string
      enum:
      - text
      - checkbox
      - radio
      - dropdown
      - optionList
      - signature
      - table
      - unknown
      description: '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`

        '
      title: EditJsonExtendEditFieldType
    EditSourceAcroForm:
      type: object
      properties:
        fieldName:
          type: string
          minLength: 1
          description: Name of the PDF form field.
        fieldType:
          $ref: '#/components/schemas/EditSourceAcroFormFieldType'
          description: Type of the original native PDF field.
        optionMap:
          type: array
          items:
            $ref: '#/components/schemas/EditSourceAcroFormOption'
          description: Supported choices for radio, dropdown, and option-list fields.
        optionValue:
          type: string
          description: Value used when this option is selected.
      required:
      - fieldName
      - fieldType
      description: Details about the original PDF form field. When Detect Form returns this property, include it unchanged in Edit requests.
      title: EditSourceAcroForm
    FileFromUrlSettings:
      type: object
      properties:
        password:
          type: string
          description: The password to unlock a password-protected PDF.
      description: Optional settings for the file, such as a password for password-protected PDFs.
      title: FileFromUrlSettings
    EditBoundingBox:
      type: object
      properties:
        left:
          type: number
          format: double
          description: The left coordinate of the bounding box (pixels)
        top:
          type: number
          format: double
          description: The top coordinate of the bounding box (pixels)
        right:
          type: number
          format: double
          description: The right coordinate of the bounding box (pixels)
        bottom:
          type: number
          format: double
          description: The bottom coordinate of the bounding box (pixels)
      required:
      - left
      - top
      - right
      - bottom
      description: Bounding box coordinates for the field location in the PDF (pixel coordinates)
      title: EditBoundingBox
    EditTextOptions:
      type: object
      properties:
        fontSize:
          type: number
          format: double
          description: Font size in points
        color:
          type: array
          items:
            type: integer
            minimum: 0
            maximum: 255
          description: RGB color values from 0 to 255 for text color.
        opacity:
          type: number
          format: double
          minimum: 0
          maximum: 1
          description: Text opacity from 0 to 1. Defaults to 1.
        fontColor:
          type: array
          items:
            type: integer
            minimum: 0
            maximum: 255
          description: Deprecated alias for `color`. RGB color values from 0 to 255.
          deprecated: true
        font:
          type: string
          description: Font family name
        combing:
          type: boolean
          description: Whether this is a combed field (like SSN fields with individual character boxes)
        maxLength:
          type: integer
          description: Maximum number of characters allowed
        multiLine:
          type: boolean
          description: Whether text can wrap across multiple lines
      description: Text styling options for text fields
      title: EditTextOptions
    FileFromUrl:
      type: object
      properties:
        url:
          type: string
          description: 'A URL to download the file. For production use cases, we recommend using presigned URLs with a 5-15 minute expiration time.


            Supported file types can be found [here](https://docs.extend.ai/2026-02-09/general/supported-file-types).

            '
        name:
          type: string
          description: The name of the file. If not set, the file name is taken from the URL.
        settings:
          $ref: '#/components/schemas/FileFromUrlSettings'
          description: Optional settings for the file, such as a password for password-protected PDFs.
      required:
      - url
      title: FileFromUrl
    EditSourceAcroFormOption:
      type: object
      properties:
        schemaValue:
          type: string
          description: Value used in the Edit schema.
        exportValue:
          type: string
          description: Value used by the PDF form field.
        displayValue:
          type: string
          description: Label shown in the PDF form.
      required:
      - schemaValue
      - exportValue
      - displayValue
      description: A supported choice for a PDF form field.
      title: EditSourceAcroFormOption
    EditSchemaGenerationConfig:
      type: object
      properties:
        engineVersion:
          type: string
          default: 1.0.0
          description: '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:
          $ref: '#/components/schemas/EditRootJSON'
          description: '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:
          type: string
          description: Custom instructions provided for schema generation.
        advancedOptions:
          $ref: '#/components/schemas/EditSchemaGenerationConfigAdvancedOptions'
          description: Advanced options for schema generation.
      description: Configuration options for edit schema generation.
      title: EditSchemaGenerationConfig
    EditSchemaGenerationResponse:
      type: object
      properties:
        schema:
          $ref: '#/components/schemas/EditRootJSON'
          description: The final generated schema after mapping. If no input schema was provided this will be the same as the annotatedSchema.
        annotatedSchema:
          oneOf:
          - $ref: '#/components/schemas/EditRootJSON'
          - type: 'null'
          description: The original schema that was detected and annotated from the file.
        mappingResult:
          oneOf:
          - $ref: '#/components/schemas/EditSchemaGenerationMappingResult'
          - type: 'null'
          description: Mapping information between `inputSchema` paths and detected form fields when an input schema was provided.
      required:
      - schema
      - annotatedSchema
      - mappingResult
      description: The generated schema and optional mapping metadata.
      title: EditSchemaGenerationResponse
    ApiError:
      type: object
      properties:
        code:
          type: string
          description: Error code for programmatic handling.
        message:
          type: string
          description: "Human-readable error message suitable for displaying to developers. \nDo not rely on the exact text of this message as it may change.\n"
        retryable:
          type: boolean
          description: 'Whether the request can be retried. When true, retry with exponential backoff.

            When false, fix the underlying issue before retrying.

            '
        requestId:
          type: string
          description: "Unique request identifier for support purposes. Always include this \nwhen contacting Extend support about an error.\n"
        docUrl:
          type: string
          description: Link to relevant documentation when one is available.
      required:
      - code
      - message
      - retryable
      description: 'Standard error response format for all Extend API errors.


        See the [Error Codes documentation](https://docs.extend.ai/2026-02-09/api-reference/error-handling) for error handling recommendations.

        '
      title: ApiError
    EditSchemaGenerationConfigAdvancedOptions:
      type: object
      properties:
        tableParsingEnabled:
          type: boolean
          description: Whether to parse table regions as arrays of objects. Defaults to `false`.
        radioEnumsEnabled:
          type: boolean
          description: 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:
          type: boolean
          description: If enabled, only native AcroForm fields from the PDF will be imported and used in the schema, skipping object detection. Defaults to `false`.
        conditionalGenerationEnabled:
          type: boolean
          description: 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`.
      description: Advanced options for schema generation.
      title: EditSchemaGenerationConfigAdvancedOptions
    EditRootJSON:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/EditRootJsonType'
          description: Must be "object" for the root schema
        properties:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/EditJSON'
          description: Map of field names to their schema definitions
        required:
          type: array
          items:
            type: string
          description: List of required field names
        additionalProperties:
          type: boolean
          description: Whether additional properties are allowed
        dependentRequired:
          $ref: '#/components/schemas/EditDependentRequired'
        if:
          $ref: '#/components/schemas/EditConditionalClause'
        then:
          $ref: '#/components/schemas/EditConditionalClause'
        else:
          $ref: '#/components/schemas/EditConditionalClause'
        allOf:
          type: array
          items:
            $ref: '#/components/schemas/EditConditionalClause'
          description: List of conditional clauses that must all match.
        oneOf:
          type: array
          items:
            $ref: '#/components/schemas/EditConditionalClause'
          description: List of conditional clauses where exactly one must match.
        anyOf:
          type: array
          items:
            $ref: '#/components/schemas/EditConditionalClause'
          description: List of conditional clauses where at least one must match.
        not:
          $ref: '#/components/schemas/EditConditionalClause'
      required:
      - type
      - properties
      description: '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.

        '
      title: EditRootJSON
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
x-provenance:
  method: harvested
  publisher: Extend
  source: https://docs.extend.ai/openapi/api-reference.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)