Quickstart

Parse turns a document into markdown and layout blocks you can hand to an LLM, an extraction schema, or your own pipeline. This guide does that with one file and no workspace, then points at the operations that build on the same call.

Prerequisites

An API key is minted in the NDI console and shown exactly once. Export it, and the SDKs and curl examples below pick it up with no extra wiring:

export NDI_API_KEY="ndi_sk_..."
export NDI_BASE_URL="https://ndi-api.nace.ai"  # optional; this is the default

This guide parses report.pdf in the current directory. Any PDF, Office file, image, spreadsheet, audio, or video file works — substitute your own path or an HTTPS URL. NDI hosts no sample document, so bring your own. See Authentication for key scope and rotation, and Format support for what each lane accepts.

Working in a coding agent

NDI speaks MCP, so Claude Code, Cursor, Codex, and opencode can call parse as a tool instead of you writing client code. Authenticate once:

uvx ndi-mcp login

Then add the local server to your agent:

Claude Code
Cursor
Codex
opencode

claude mcp add ndi -- uvx ndi-mcp

Add the server to .cursor/mcp.json:

{
  "mcpServers": {
    "ndi": {
      "command": "uvx",
      "args": ["ndi-mcp"]
    }
  }
}

codex mcp add ndi -- uvx ndi-mcp

opencode mcp add ndi -- uvx ndi-mcp

Ask the agent to run upload_document on the local file, then parse_document with the handle it gets back. The hosted server at https://ndi-api.nace.ai/v1/mcp runs in our cloud and cannot see your filesystem, so local files need the local server. The hosted variant and full tool catalog are on the MCP page. Prefer the shell with no agent? pip install ndi-cli, then ndi parse ./report.pdf. Full command reference: NDI CLI.

Parse a document

Python
TypeScript
curl

Install the SDK. It requires Python 3.11+ and pulls in only httpx and pydantic:

pip install ndi-sdk

Stage the document. create_upload sends the bytes and returns a single-use handle. The bytes are deleted as soon as the job that reads them finishes:

from ndi_sdk import NdiClient

with NdiClient() as client:
    upload = client.documents.create_upload("report.pdf")
    # Returns: UploadResponse with upload_id and expires_at

Parse it. Parse is asynchronous and returns a Job. wait_seconds holds the submission request open so short documents finish inline; jobs.wait covers everything longer:

from ndi_sdk import NdiClient

with NdiClient() as client:
    upload = client.documents.create_upload("report.pdf")
    queued = client.documents.parse(upload, wait_seconds=30)
    # Returns: Job, already succeeded when inline waiting was enough

    job = client.jobs.wait(queued.job_id, timeout=600)
    # Returns: succeeded Job; job.result is a ParseResult

Read the result. job.result is a ParseResult. Markdown is produced by default, and result.markdown is a shortcut for result.document.markdown:

from ndi_sdk import NdiClient
from ndi_sdk.models.jobs import ParseResult

with NdiClient() as client:
    job = client.jobs.wait(
        client.documents.parse(
            client.documents.create_upload("report.pdf"),
            wait_seconds=30,
        ).job_id,
        timeout=600,
    )

    if isinstance(job.result, ParseResult):
        result = job.result
        print(result.document.page_count, result.units, result.ocr_applied)
        print((result.markdown or "")[:1000])

        for block in result.document.blocks or []:
            print(block.type, block.content[:80])

Install the SDK. It requires Node.js 20+, uses native fetch, and ships dual ESM and CommonJS builds:

npm install ndi-sdk

Stage the document. createUpload sends the bytes and returns a single-use handle. The bytes are deleted as soon as the job that reads them finishes:

import { NdiClient } from "ndi-sdk";

const client = new NdiClient();
const upload = await client.documents.createUpload("report.pdf");
// Returns: UploadResponse with upload_id and expires_at

Parse it. Parse is asynchronous and resolves to a Job. wait_seconds holds the submission request open so short documents finish inline; jobs.wait covers everything longer:

import { NdiClient } from "ndi-sdk";

const client = new NdiClient();
const upload = await client.documents.createUpload("report.pdf");
const queued = await client.documents.parse(upload, { wait_seconds: 30 });
// Returns: Promise<Job>, already succeeded when inline waiting was enough

const job = await client.jobs.wait(queued.job_id, { timeout: 600 });
// Returns: succeeded Job; job.result is a ParseResult

Read the result. Narrow job.result with isParseResult before touching parse fields. Markdown is produced by default, and result.markdown is a shortcut for result.document.markdown:

import { NdiClient, isParseResult } from "ndi-sdk";

const client = new NdiClient();
const job = await client.jobs.wait(
  (
    await client.documents.parse(
      await client.documents.createUpload("report.pdf"),
      { wait_seconds: 30 },
    )
  ).job_id,
  { timeout: 600 },
);

if (isParseResult(job.result)) {
  const result = job.result;
  console.log(result.document.page_count, result.units, result.ocr_applied);
  console.log(result.markdown?.slice(0, 1000));

  for (const block of result.document.blocks ?? []) {
    console.log(block.type, block.content.slice(0, 80));
  }
}

Stage the document. POST /v1/uploads takes multipart bytes and returns an upload_id. The handle is single-use:

UPLOAD_ID=$(curl -s -X POST "$NDI_BASE_URL/v1/uploads" \
  -H "X-API-Key: $NDI_API_KEY" \
  -F "file=@report.pdf" | jq -r '.upload_id')

Parse it. wait_seconds is a query parameter, not a body field. It holds the request open for up to 300 seconds so a short document comes back inline:

JOB=$(curl -s -X POST "$NDI_BASE_URL/v1/parse?wait_seconds=60" \
  -H "X-API-Key: $NDI_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"source\":{\"type\":\"upload\",\"upload_id\":\"$UPLOAD_ID\"}}")

JOB_ID=$(echo "$JOB" | jq -r '.job_id')
echo "$JOB" | jq -r '.status'

Read the result. If the status was not terminal, poll the job. An HTTPS source needs no upload step at all — pass {"source":{"type":"url","url":"https://...","file_name":"report.pdf"}} instead:

STATUS=$(curl -s "$NDI_BASE_URL/v1/jobs/$JOB_ID" -H "X-API-Key: $NDI_API_KEY" | jq -r '.status')
until [[ "$STATUS" == "succeeded" || "$STATUS" == "failed" || "$STATUS" == "cancelled" ]]; do
  sleep 3
  STATUS=$(curl -s "$NDI_BASE_URL/v1/jobs/$JOB_ID" -H "X-API-Key: $NDI_API_KEY" | jq -r '.status')
done

curl -s "$NDI_BASE_URL/v1/jobs/$JOB_ID" -H "X-API-Key: $NDI_API_KEY" \
  | jq -r '.result.document.markdown'

Understanding the response

A succeeded parse job looks like this:

{
  "job_id": "550e8400-e29b-41d4-a716-446655440003",
  "kind": "parse",
  "status": "succeeded",
  "units": 96,
  "payload_expires_at": "2026-09-21T10:15:00Z",
  "result": {
    "result_type": "parse",
    "file_name": "report.pdf",
    "lane": "document",
    "document": {
      "page_count": 96,
      "markdown": "# Annual Report\n\n## Portfolio value\n\n| | This period |\n...",
      "text": null,
      "blocks": [
        {
          "id": "b_0001",
          "type": "heading",
          "content": "Annual Report",
          "confidence": 0.98,
          "location": {
            "kind": "page_region",
            "page": 1,
            "polygons": [[[0.35, 0.03], [0.65, 0.03], [0.65, 0.09], [0.35, 0.09]]]
          }
        }
      ],
      "chunks": []
    },
    "ocr_applied": false
  }
}

Field	What it contains
`job_id`	Identifier for this run. Read it again later, stream `events`, or ask for the request it was given
`status`	`queued`, `running`, `succeeded`, `failed`, or `cancelled`. Only `succeeded` carries a `result`
`units`	Billable processing units this run consumed
`payload_expires_at`	When retention drops `result`. The job row survives; reads then return `result_expired`
`result.result_type`	Discriminator for the result union. `parse` here, so SDKs narrow it to `ParseResult`
`result.lane`	Parser that handled the source: `document`, `spreadsheet`, `image`, `audio`, or `video`
`document.page_count`	Pages processed, after any `page_ranges` selection
`document.markdown`	Whole-document rendering. Best for display and for LLM input
`document.blocks`	Layout elements with a type and text, plus a `location` you can draw overlays from when the lane produced one
`document.chunks`	Retrieval-sized pieces. Empty unless you ask for page or section chunking
`document.text`	Plaintext rendering. `null` unless requested in `output.formats`
`ocr_applied`	Whether OCR ran. NDI decides this per document, so read it instead of assuming

Renderings you did not request are null, not missing. Block locations vary by source — pages use normalized polygons, workbooks use sheet ranges, structured text uses spans or JSON pointers. Parse response format covers every variant, including audio and video transcripts.

Customizing the parse

The defaults suit most documents. These four options cover most of what people change first:

Python
TypeScript
curl

from ndi_sdk import NdiClient
from ndi_sdk.models.document_ops import (
    PageRange,
    ParseChunkingOptions,
    ParseOutputOptions,
)

with NdiClient() as client:
    job = client.jobs.wait(
        client.documents.parse(
            client.documents.create_upload("report.pdf"),
            page_ranges=[PageRange(start=1, end=10)],
            parse_mode="medium",
            output=ParseOutputOptions(
                formats=["markdown", "text", "blocks"],
                table_format="html",
            ),
            chunking=ParseChunkingOptions(strategy="section"),
            wait_seconds=30,
        ).job_id,
        timeout=600,
    )
    # Returns: succeeded Job covering pages 1-10, with section chunks

import { NdiClient } from "ndi-sdk";

const client = new NdiClient();
const queued = await client.documents.parse(
  await client.documents.createUpload("report.pdf"),
  {
    page_ranges: [{ start: 1, end: 10 }],
    parse_mode: "medium",
    output: { formats: ["markdown", "text", "blocks"], table_format: "html" },
    chunking: { strategy: "section" },
    wait_seconds: 30,
  },
);
const job = await client.jobs.wait(queued.job_id, { timeout: 600 });
// Returns: succeeded Job covering pages 1-10, with section chunks

curl -s -X POST "$NDI_BASE_URL/v1/parse?wait_seconds=60" \
  -H "X-API-Key: $NDI_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"source\":{\"type\":\"upload\",\"upload_id\":\"$UPLOAD_ID\"},\"page_ranges\":[{\"start\":1,\"end\":10}],\"parse_mode\":\"medium\",\"output\":{\"formats\":[\"markdown\",\"text\",\"blocks\"],\"table_format\":\"html\"},\"chunking\":{\"strategy\":\"section\"}}"

page_ranges — one-based inclusive ranges. Cheaper and faster on long documents when you only need a section.
parse_mode — low (default) uses the native path, medium routes to the best parser for the document, high adds page-level verification and correction for more latency.
output.formats — markdown and blocks by default. Add text for a flattened rendering. table_format switches tables between html (default) and markdown.
chunking.strategy — none by default. Use page or section when the output feeds retrieval.

Figure descriptions, diagram-to-Mermaid, image crops, OCR geometry, spreadsheet sheet selection, and encrypted-PDF passwords are all available too. See the Python or TypeScript parse reference.

What’s next

Extract fields

Define a JSON schema and get typed fields back with citations into the source document.

Split a packet

Cut a multi-document PDF into labeled sections with page ranges.

Classify a document

Assign your own classes to a whole document or to each page.

Ground a claim

Locate a value or phrase on the page so a reviewer can see where it came from.

Build a workspace

Store a corpus, ingest it once, then run search and file tools across it.

Reuse one parse

Pass a succeeded parse job to extract, split, or ground instead of paying for the parse twice.

Troubleshooting

401 unauthorized. Send X-API-Key, and check $NDI_API_KEY is exported in the same shell as the client. Authorization: Bearer works on hosted MCP only. 422 invalid_request on parse. wait_seconds is a query parameter and Idempotency-Key is a header. Neither belongs in the JSON body. Status is failed. Read job.error. Common causes are an unsupported format, a corrupt file, page ranges past the end of the document, and a missing or wrong password on an encrypted PDF. upload_expired. Upload handles expire after 24 hours by default. Stage the file again. Tables came back as HTML. That is the default. Pass output.table_format: "markdown" for markdown tables. result is gone on a job that succeeded. Retention passed payload_expires_at. Re-run the operation. Symptom-based fixes for ingestion, search, and workspaces are in Troubleshooting.

Getting started

Guides

Agents

Concepts

Troubleshooting

Prerequisites

Working in a coding agent

Parse a document

Understanding the response

Customizing the parse

What’s next

Extract fields

Split a packet

Classify a document

Ground a claim

Build a workspace

Reuse one parse

Troubleshooting

​Prerequisites

​Working in a coding agent

​Parse a document

​Understanding the response

​Customizing the parse

​What’s next

Extract fields

Split a packet

Classify a document

Ground a claim

Build a workspace

Reuse one parse

​Troubleshooting

Prerequisites

Working in a coding agent

Parse a document

Understanding the response

Customizing the parse

What’s next

Troubleshooting