Extraction schema registry

The registry is REST-only — there is no SDK namespace. documents.extract still accepts schema_id once a family exists. Validate a draft first with documents.validate_extract_schema or POST /v1/extract/schema-validation.

Python
TypeScript
curl

import os

import httpx
from ndi_sdk import NdiClient

schema = {
    "type": "object",
    "properties": {
        "invoice_number": {"type": "string"},
        "total": {"type": "number"},
    },
    "required": ["invoice_number", "total"],
}

with NdiClient() as client:
    check = client.documents.validate_extract_schema(json_schema=schema)
    print(check)

base = os.environ["NDI_BASE_URL"]
headers = {"X-API-Key": os.environ["NDI_API_KEY"], "Content-Type": "application/json"}
created = httpx.post(
    f"{base}/v1/extraction-schemas",
    headers=headers,
    json={"name": "Invoice", "description": "Core invoice fields", "schema": schema},
).json()
schema_id = created["schema_id"]

with NdiClient() as client:
    upload = client.documents.create_upload("invoice.pdf")
    job = client.jobs.wait(
        client.documents.extract(upload, schema_id=schema_id, wait_seconds=30).job_id
    )
    print(job.result.schema_id, job.result.schema_version, job.result.data)

import { NdiClient } from "ndi-sdk";

const schema = {
  type: "object",
  properties: {
    invoice_number: { type: "string" },
    total: { type: "number" },
  },
  required: ["invoice_number", "total"],
};

const client = new NdiClient();
const check = await client.documents.validateExtractSchema({ json_schema: schema });
console.log(check);

const created = await fetch(`${process.env.NDI_BASE_URL}/v1/extraction-schemas`, {
  method: "POST",
  headers: {
    "X-API-Key": process.env.NDI_API_KEY ?? "",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "Invoice", description: "Core invoice fields", schema }),
});
const { schema_id } = (await created.json()) as { schema_id: string };

const upload = await client.documents.createUpload("invoice.pdf");
const job = await client.jobs.wait(
  (await client.documents.extract(upload, { schema_id, wait_seconds: 30 })).job_id,
);
console.log(job.result);

curl -s -X POST "$NDI_BASE_URL/v1/extract/schema-validation" \
  -H "X-API-Key: $NDI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"schema":{"type":"object","properties":{"invoice_number":{"type":"string"},"total":{"type":"number"}},"required":["invoice_number","total"]}}'

SCHEMA_ID=$(curl -s -X POST "$NDI_BASE_URL/v1/extraction-schemas" \
  -H "X-API-Key: $NDI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Invoice","description":"Core invoice fields","schema":{"type":"object","properties":{"invoice_number":{"type":"string"},"total":{"type":"number"}},"required":["invoice_number","total"]}}' \
  | jq -r '.schema_id')

curl -s -X POST "$NDI_BASE_URL/v1/extract?wait_seconds=60" \
  -H "X-API-Key: $NDI_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"source\":{\"type\":\"url\",\"url\":\"https://example.com/invoice.pdf\",\"file_name\":\"invoice.pdf\"},\"schema_id\":\"$SCHEMA_ID\"}"

Versioning

POST /v1/extraction-schemas creates a family (sch_…) and version 1
POST /v1/extraction-schemas/{schema_id}/versions appends an immutable version
Extract schema_version pins a version; omit it to use latest
Tenant keys create and append only their own schemas
Reads include tenant and platform families; a tenant row wins on id clash
No drafts, in-place edits, or deletes

See Extract.

Getting started

Guides

Concepts

Python SDK

TypeScript SDK

Agents

Troubleshooting

Versioning

​Versioning

Versioning