Schema Builder

POST /v1/schema/auto returns the canonical Docspeed extraction schema format: Schema V2.

Schema V2 is the same object accepted by POST /v1/extract:

{
  "doc_class": "invoice",
  "fields": [
    {
      "key": "invoice.invoice_number",
      "description": "Invoice number",
      "type": "string",
      "array": false
    }
  ],
  "tables": [
    {
      "key": "line_items",
      "description": "Invoice line items",
      "fields": [
        {
          "key": "description",
          "description": "Line item description",
          "type": "string",
          "array": false
        }
      ]
    }
  ]
}

The generated schema object can be copied directly into Extract. Do not mix Schema V2 with older legacy schema payloads; the public contract and generated reference use Schema V2.

Modes

POST /v1/schema/auto supports:

• zero document: pass instructions only
• single document: pass one input or one file_id
• multi document: pass inputs[] or a file_id array

Use execution_mode: "sync" when you need the schema immediately. Use execution_mode: "async" for larger document sets and poll the returned job.

cURL

curl -sS -X POST "https://api.docspeed.ai/v1/schema/auto" \
  -H "Authorization: Bearer ${DOCSPEED_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": [
      {"file_id": "file_april"},
      {"file_id": "file_may"},
      {"file_id": "file_june"}
    ],
    "instructions": "Create a shared invoice schema with supplier, invoice number, total due, tax, and line items.",
    "execution_mode": "sync"
  }'

Python

import requests

response = requests.post(
    "https://api.docspeed.ai/v1/schema/auto",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "inputs": [
            {"file_id": "file_april"},
            {"file_id": "file_may"},
            {"file_id": "file_june"},
        ],
        "instructions": "Create a shared invoice schema with supplier, invoice number, total due, tax, and line items.",
        "execution_mode": "sync",
    },
    timeout=600,
)
response.raise_for_status()
schema = response.json()
print(schema)

TypeScript

const response = await fetch("https://api.docspeed.ai/v1/schema/auto", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    inputs: [
      { file_id: "file_april" },
      { file_id: "file_may" },
      { file_id: "file_june" },
    ],
    instructions: "Create a shared invoice schema with supplier, invoice number, total due, tax, and line items.",
    execution_mode: "sync",
  }),
});

if (!response.ok) throw new Error(await response.text());
const schema = await response.json();
console.log(schema);

Example response

{
  "doc_class": "invoice",
  "fields": [
    {
      "key": "invoice.invoice_number",
      "description": "Invoice number",
      "type": "string",
      "array": false
    },
    {
      "key": "supplier.name",
      "description": "Supplier legal name",
      "type": "string",
      "array": false
    },
    {
      "key": "invoice.total_due",
      "description": "Final amount due",
      "type": "number",
      "array": false
    }
  ],
  "tables": [
    {
      "key": "line_items",
      "description": "Invoice line items",
      "fields": [
        {
          "key": "description",
          "description": "Line item description",
          "type": "string",
          "array": false
        },
        {
          "key": "amount",
          "description": "Line item amount",
          "type": "number",
          "array": false
        }
      ]
    }
  ]
}

Use the schema in Extract

Send the exact response object as schema:

{
  "input": {"file_id": "file_123"},
  "execution_mode": "sync",
  "grounding": "cell",
  "schema": {
    "doc_class": "invoice",
    "fields": [
      {"key": "invoice.invoice_number", "description": "Invoice number", "type": "string", "array": false}
    ],
    "tables": []
  }
}

When to use it

• Use zero-doc mode when you know the target fields before sharing examples.
• Use single-doc mode to bootstrap from a representative invoice, statement, or form.
• Use multi-doc mode when a production flow needs one shared schema across variations.
• Review generated keys before using them in production; stable downstream integrations should treat schema keys as a versioned contract.