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 or in-place edits

Deleting a schema

DELETE /v1/extraction-schemas/{schema_id} deletes a schema you created, with every version. NDI removes its name, description and JSON Schema at once and keeps only the id, version numbers and timestamps, so finished jobs that used it still show which schema_id and schema_version they ran with. A job accepted before the delete keeps its own copy of the schema and finishes. After the delete, reading the schema or starting Extract with its schema_id returns 404 schema_not_found. Deleting it again returns 204. Platform schemas cannot be deleted.

curl -s -X DELETE "$NDI_BASE_URL/v1/extraction-schemas/$SCHEMA_ID" \
  -H "X-API-Key: $NDI_API_KEY"

Retention

A schema you create, with all of its versions, is kept until you delete it or your organization is closed. See Saved schemas and domains. See Extract.

Getting started

Guides

Agents

Concepts

Troubleshooting

Versioning

Deleting a schema

Retention

​Versioning

​Deleting a schema

​Retention

Versioning

Deleting a schema

Retention