Document operations

Document operations are workspace-free: supply a document source and get back results. Every job-creating endpoint returns 202 immediately and accepts ?wait_seconds=N to block up to N seconds (max 300) for the result inline. wait_seconds is a query parameter, not a request body field. Idempotency-Key is an HTTP header, not a request body field. Strict request models refuse extra body fields.

Source types

The five job-creating operations (parse, split, classify, extract, ground) accept the shared document source union. Schema validation is synchronous and validates a schema structure only — it does not accept a document source.

// Staged upload (from POST /v1/uploads)
{"type": "upload", "upload_id": "<uuid>"}

// Public or S3 URL
{"type": "url", "url": "https://example.com/report.pdf", "file_name": "report.pdf"}

// File already in a workspace (workspace_id + file_id)
{"type": "workspace_file", "workspace_id": "<uuid>", "file_id": "<uuid>"}

// Reuse a prior Parse job where supported
{"type": "parse_result", "job_id": "<parse-job-id>"}

See Sources and uploads for details.

Parse

POST /v1/parse

Convert any document into structured text, Markdown, or block JSON. OCR is applied automatically when the document needs it. Query parameters:

wait_seconds (optional, default 0, max 300) — Block up to N seconds for the result inline. 0 returns 202 immediately.

Headers:

Idempotency-Key (optional, max 200 chars) — Replaying with the same key returns the original job.

Request body:

{
  "source": {"type": "upload", "upload_id": "550e8400-e29b-41d4-a716-446655440002"},
  "page_ranges": [{"start": 1, "end": 10}],
  "output": {
    "formats": ["markdown", "text", "blocks"],
    "table_format": "markdown",
    "include_images": false,
    "include_page_markers": true
  },
  "figures": {"mode": "include"},
  "chunking": {"strategy": "page"}
}

Body fields:

source (required) — Document source discriminator.
page_ranges (optional) — One or more 1-indexed inclusive page ranges. Omit to parse all pages.
password (optional) — PDF user/owner password for encrypted uploads/URLs. Write-only: never stored in the job payload or returned in any response. Rejected with parse_result sources. Ignored when the PDF is not encrypted. Non-PDF sources with a password fail with invalid_request.
output.formats (optional, default ["markdown", "blocks"]) — One or more of "markdown", "text", "blocks".
output.table_format (optional, default "html") — Render tables as "html" or GitHub-flavored "markdown".
output.include_images (optional, default false) — Include extracted figure crops in the parsed output. Works for PDF and image uploads (png / jpg / jpeg / webp).
output.include_page_markers (optional, default true) — Insert --- Page N --- headers between PDF pages in markdown and text. Page chunking still uses these headers internally when this is false.
figures.mode (optional, default "include") — "omit", "include", or "describe". Describe captions figure blocks (PDF and image). Independent of diagrams.mode.
diagrams.mode (optional, default "omit") — "omit" or "mermaid". When omit, flowchart mermaid is stripped and node/edge labels are flattened into overlay text. When mermaid, fences stay and figures.mode=describe still appends a Figure: caption.
chunking.strategy (optional, default "none") — "none", "page", or "section". Generated chunks are returned in document.chunks.

When source.type is parse_result, page selection and output.include_images are not supported because NDI reuses the prior Parse result instead of reading the original document again. Example (wait for result):

curl -X POST "$NDI_BASE_URL/v1/parse?wait_seconds=60" \
  -H "X-API-Key: $NDI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: parse-report-v1" \
  -d '{
    "source": {"type": "url", "url": "https://example.com/report.pdf", "file_name": "report.pdf"},
    "password": "optional-when-encrypted"
  }'

Response (202 — queued, or 200 — terminal when wait_seconds hit):

{
  "job_id": "550e8400-e29b-41d4-a716-446655440010",
  "kind": "parse",
  "status": "succeeded",
  "result": {
    "result_type": "parse",
    "file_name": "report.pdf",
    "lane": "document",
    "document": {
      "page_count": 96,
      "markdown": "# Annual Report 2025\n\n...",
      "text": null,
      "blocks": null,
      "chunks": [
        {
          "id": "page-1",
          "content": "# Annual Report 2025\n\n...",
          "location": {"kind": "page_region", "page": 1, "polygons": []}
        }
      ]
    },
    "ocr_applied": false,
    "units": 96
  },
  "created_at": "2026-08-09T12:00:00Z",
  "finished_at": "2026-08-09T12:01:00Z"
}

Result fields:

file_name — Name of the parsed file.
document.page_count — Total pages in the document.
document.markdown — Present when "markdown" was in output.formats.
document.text — Present when "text" was in output.formats.
document.blocks — Present when "blocks" was in output.formats; list of structural blocks.
document.chunks — RAG-oriented chunks produced by the selected chunking.strategy; empty for "none".
ocr_applied — Whether OCR ran.
units — Processing units consumed (for billing).

Split

POST /v1/split

Split a paged document into logical, classified page ranges. For spreadsheets, Split deterministically creates one segment per worksheet, then classifies each worksheet against the provided classes. Query parameters:

wait_seconds (optional, default 0, max 300)

Headers:

Idempotency-Key (optional)

Request body:

{
  "source": {"type": "upload", "upload_id": "550e8400-e29b-41d4-a716-446655440002"},
  "classes": [
    {
      "id": "invoice",
      "label": "Invoice",
      "description": "Supplier invoice or request for payment.",
      "subclasses": [
        {"id": "supplier_bill", "label": "Supplier bill", "description": "Vendor invoice."}
      ]
    },
    {"id": "statement", "label": "Statement"}
  ],
  "unknown_policy": "include",
  "overlap_policy": "exclusive",
  "output": {"include_content": false, "materialize_files": false}
}

Body fields:

source (required) — One upload, URL, workspace-file, or supported Parse-result source.
classes (required) — Target segment categories with stable id values and optional subclasses. Spreadsheet worksheets are classified against the same two-level leaf classes and can return more than one match.
unknown_policy (optional, default "include") — Whether unclassified pages or worksheet segments are included, forced, or rejected.
overlap_policy (optional, default "exclusive") — How adjacent candidate ranges are reconciled. "shared_boundary_page" is reserved for a future runtime.
output.include_content (optional, default false) — Include segment content in the result.
output.materialize_files (optional, default false) — Materialize document segments as child artifacts. Spreadsheet segments always materialize as single-sheet .xlsx artifacts regardless of this option.

page_ranges is not supported for spreadsheet sources. Spreadsheet sheet position is represented as start_page == end_page == sheet_index + 1. Result:

{
  "result_type": "split",
  "file_name": "packet.pdf",
  "lane": "document",
  "page_count": 2,
  "segments": [
    {
      "id": "seg_1",
      "sequence": 0,
      "status": "matched",
      "class": {
        "id": "invoice/supplier_bill",
        "label": "Invoice / Supplier bill",
        "description": "Supplier invoice or request for payment. Vendor invoice.",
        "parent_id": "invoice",
        "subcategory_id": "supplier_bill"
      },
      "classes": null,
      "start_page": 1,
      "end_page": 2,
      "classification_confidence": {"band": "unavailable", "score": null},
      "boundary_confidence": {"band": "unavailable", "score": null},
      "content": null,
      "artifacts": [],
      "warnings": []
    }
  ],
  "units": 2
}

Result fields:

segments — Ordered page-range segments for the document.
class — The selected class for the segment, or null for unclassified segments.
classes — Multi-class set for spreadsheet worksheet segments. Document/PDF segments keep the singular class field and return null here.
start_page / end_page — Inclusive 1-indexed page range.
sheet_name — Worksheet name for spreadsheet segments; null for document segments.
classification_confidence — Confidence band and optional calibrated score for the selected class.
boundary_confidence — Confidence band and optional calibrated score for the segment boundaries.
artifacts — Materialized child files when requested for documents; always one single-sheet .xlsx for spreadsheet segments.
warnings — Non-fatal notes about the segment.

Classify

POST /v1/classify

Classify one document against caller-provided classes. Use granularity: "document" for one document-level label unit, or granularity: "page" for one label unit per page. page_ranges restricts which pages are parsed and classified. Query parameters:

wait_seconds (optional, default 0, max 300)

Headers:

Idempotency-Key (optional)

Request body:

{
  "source": {"type": "upload", "upload_id": "550e8400-e29b-41d4-a716-446655440002"},
  "classes": [
    {
      "id": "invoice",
      "label": "Invoice",
      "description": "Request for payment from a supplier.",
      "criteria": ["Has supplier name", "Has amount due"],
      "subclasses": [
        {"id": "utility", "label": "Utility invoice"}
      ]
    },
    {
      "id": "bank_statement",
      "label": "Bank statement"
    }
  ],
  "granularity": "document",
  "page_ranges": [{"start": 1, "end": 3}],
  "unknown_policy": "allow",
  "output": {"max_alternatives": 3, "include_reason": true}
}

Body fields:

source (required) — One upload, URL, or workspace-file source. parse_result reuse is intentionally rejected for Classify.
classes (required) — One or more classes with stable id, human label, optional description, optional criteria, and optional subclasses.
granularity (optional, default "document") — "document" or "page".
page_ranges (optional) — One-based inclusive page ranges. Valid for paged document sources.
unknown_policy (optional, default "allow") — "allow" returns an unknown unit with its detected Other / … label; "force_best" requires the classifier to select the best configured class.
output.max_alternatives (optional, default 3) — Maximum ranked labels per unit.
output.include_reason (optional, default true) — Include model reasons in labels.

Result:

{
  "result_type": "classify",
  "units": [
    {
      "granularity": "document",
      "page_range": {"start": 1, "end": 3},
      "unknown": false,
      "labels": [
        {
          "class_id": "invoice",
          "subclass_id": "utility",
          "label": "Invoice",
          "rank": 1,
          "confidence": 1.0,
          "reason": "The document includes a supplier, amount due, and invoice number."
        }
      ]
    }
  ]
}

Result fields:

units — One document unit or one unit per page, depending on granularity.
page_range — Page coverage for the unit, or null when not available.
unknown — true when no provided class was selected. The detected freeform type remains in labels under class other.
labels — Ranked class assignments with their reason and coverage-derived confidence. Confidence is the fraction of the unit’s pages or sheets assigned that label, not a calibrated model probability.

Extract

POST /v1/extract

Extract schema-shaped structured data from a document. Exactly one of schema_id or schema must be present. Query parameters:

wait_seconds (optional, default 0, max 300)

Headers:

Idempotency-Key (optional)

Request body:

{
  "source": {"type": "upload", "upload_id": "550e8400-e29b-41d4-a716-446655440002"},
  "schema": {
    "type": "object",
    "properties": {
      "company_name": {"type": "string"},
      "revenue": {"type": "number"}
    },
    "required": ["company_name"]
  },
  "instructions": "Use the consolidated annual total.",
  "page_ranges": [{"start": 1, "end": 10}],
  "citations": {"enabled": true, "include_source_text": true}
}

Body fields:

source (required) — Document source.
schema_id (optional) — A registered schema identifier from /v1/extraction-schemas. Mutually exclusive with schema.
schema_version (optional, ≥ 1) — Pin a registry version when using schema_id. Omit to resolve the latest visible version.
schema (optional) — Inline JSON Schema. Mutually exclusive with schema_id. Pre-validate with POST /v1/extract/schema-validation.
instructions (optional) — Additional guidance for finding values declared by the schema. Instructions cannot add undeclared result fields.
page_ranges (optional) — One or more 1-indexed inclusive page ranges. Not supported with a parse_result source.
citations.enabled (optional, default true) — Attach per-field citations when values can be located.
citations.include_source_text (optional, default true) — Include a short source quote in citations.

Result:

{
  "result_type": "extract",
  "data": {
    "company_name": "Acme Corp",
    "revenue": null
  },
  "fields": [
    {
      "path": "/company_name",
      "value": "Acme Corp",
      "confidence": null,
      "citations": [
        {
          "location": {"kind": "page_region", "page": 1, "polygons": []},
          "source_text": "Acme Corp Annual Report"
        }
      ],
      "status": "found"
    },
    {
      "path": "/revenue",
      "value": null,
      "confidence": null,
      "citations": [],
      "status": "not_found"
    }
  ],
  "schema_id": null,
  "schema_version": null,
  "units": 10,
  "warnings": []
}

Result fields:

data — The extracted object shaped by the submitted schema.
fields — One entry per schema field. Status is found, not_found, or ambiguous. A field the model could not locate is explicitly not_found, never silently omitted.
fields[*].citations — Per-field locations and source text tracing found values back to the source document.
schema_id / schema_version — Set when Extract resolved a registry schema; null for inline schema.
warnings — Non-fatal notes about the request, such as instructions that no declared schema field can satisfy.

Extract schema validation

POST /v1/extract/schema-validation

Validate an extraction schema without creating a job. Synchronous — returns 200 immediately. Request body:

{
  "schema": {
    "type": "object",
    "properties": {
      "name": {"type": "string"},
      "age": {"type": "integer"}
    }
  }
}

Body fields:

schema (optional) — Inline JSON Schema to validate. Mutually exclusive with schema_id.
schema_id (optional) — Registered schema from /v1/extraction-schemas. Mutually exclusive with schema.
schema_version (optional, ≥ 1) — Pin a registry version when using schema_id.

Response (valid):

{
  "valid": true,
  "errors": [],
  "normalized_schema": { ... }
}

Response (invalid):

{
  "valid": false,
  "errors": [
    {"path": "", "message": "Unsupported keyword: $ref"}
  ],
  "normalized_schema": null
}

Use this before submitting an extract job to catch schema errors without consuming processing units.

Ground

POST /v1/ground

Locate target text in a document. Each target is assessed independently as found, not_found, or failed, with ranked matches that report how the location was found. Ground is target location, not claim verification. It locates target text and reports location status only. Query parameters:

wait_seconds (optional, default 0, max 300)

Headers:

Idempotency-Key (optional)

Request body:

{
  "source": {"type": "upload", "upload_id": "550e8400-e29b-41d4-a716-446655440002"},
  "targets": [
    {
      "id": "t1",
      "text": "Net revenue exceeded $1 billion.",
      "hint": "financial highlights",
      "page_hints": [12]
    },
    {
      "id": "t2",
      "text": "more than 50 countries"
    }
  ],
  "options": {
    "max_matches": 10,
    "minimum_semantic_score": 0.7,
    "include_previews": true
  }
}

Body fields:

source (required) — Document source.
targets (required) — Array of 1–30 target texts to locate.
- id — Caller-assigned identifier, echoed in the result.
- text — Text or phrase to locate.
- hint (optional) — Nearby text that helps disambiguate matches.
- page_hints (optional) — 1-based page numbers to search first.
options.max_matches (optional, default 10) — Maximum ranked matches per target.
options.minimum_semantic_score (optional) — Minimum score from 0 to 1 for semantic matches.
options.include_previews (optional, default false) — Generate source-image crops when a visual region is available.

Legacy claims[] requests remain accepted during rollout, but new integrations should send targets[]. Result:

{
  "result_type": "ground",
  "targets": [
    {
      "id": "t1",
      "status": "found",
      "matches": [
        {
          "rank": 1,
          "matched_text": "Net revenue exceeded $1 billion.",
          "match_method": "normalized",
          "confidence": null,
          "location": {"kind": "text_range", "char_start": 120, "char_end": 180},
          "cropped_image_url": "https://ndi.example.com/v1/jobs/550e8400-e29b-41d4-a716-446655440011/ground-crops/czM6Ly8uLi4"
        }
      ]
    },
    {
      "id": "t2",
      "status": "not_found",
      "matches": []
    }
  ],
  "units": 2
}

Result fields:

targets — One entry per input target, in the same order.
status — found, not_found, or failed.
matches — Ranked locations for found targets.
match_method — exact, normalized, or semantic.
confidence — null for exact and normalized matches; set only for probabilistic semantic matches.
cropped_image_url — Authenticated crop URL when previews were requested and a visual region is available; otherwise null. Send the same X-API-Key header when fetching it. See Get a Ground crop.

Job lifecycle

All five job-creating endpoints (parse, split, classify, extract, ground) follow the same pattern:

202 immediately when wait_seconds=0 (default). Poll GET /v1/jobs/{job_id}.
200 with terminal result when wait_seconds=N and the job finished within N seconds.
202 with running job when wait_seconds=N but the job did not finish in time. Still poll.

Read status regardless of whether the response is 200 or 202. See Jobs, idempotency, and async semantics for the full job lifecycle.

Granular operations

Platform resources

Knowledge graph

Tools

Operations

Source types

Parse

Split

Classify

Extract

Extract schema validation

Ground

Job lifecycle

​Source types

​Parse

​Split

​Classify

​Extract

​Extract schema validation

​Ground

​Job lifecycle

Source types

Parse

Split

Classify

Extract

Extract schema validation

Ground

Job lifecycle