Parse a document - NDI Platform API

Parse converts a document into structured text. OCR runs when the file needs it; ocr_applied on the result says whether it did.

Python
TypeScript
curl

from ndi_sdk import NdiClient

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

import { NdiClient } from "ndi-sdk";

const client = new NdiClient();
const upload = await client.documents.createUpload("report.pdf");
const job = await client.jobs.wait(
  (await client.documents.parse(upload, { wait_seconds: 30 })).job_id,
  { timeout: 600 },
);
console.log(job.result && "markdown" in job.result ? job.result.markdown : job.result);

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')

curl -s -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\":\"upload\",\"upload_id\":\"$UPLOAD_ID\"}}"

Sources

Upload, URL, workspace file, or a prior parse (ParseResultSource / { type: "parse_result", job_id }). Reusing a parse skips page selection and include_images. See Sources.

Useful options

Option	Default	Meaning
`page_ranges`	all pages	Inclusive 1-indexed ranges
`output.formats`	`markdown`, `blocks`	Also `text`
`output.table_format`	`html`	or `markdown`
`output.include_images`	`false`	Figure crops (PDF and raster images)
`output.include_page_markers`	`true`	`--- Page N ---` in markdown/text
`figures.mode`	`describe`	`omit` / `include` / `describe`
`diagrams.mode`	`omit`	`omit` or `mermaid`
`chunking.strategy`	`none`	`none` / `page` / `section`
`spreadsheet`	all sheets	Sheet/row/column filters for workbooks
`password`	unset	Encrypted PDF; write-only, never echoed

from ndi_sdk import NdiClient

with NdiClient() as client:
    upload = client.documents.create_upload("report.pdf")
    job = client.jobs.wait(
        client.documents.parse(
            upload,
            page_ranges=[{"start": 1, "end": 1}],
            output={"formats": ["markdown", "blocks"], "table_format": "html"},
            chunking={"strategy": "page"},
            wait_seconds=30,
        ).job_id
    )
    print(len(job.result.document.chunks))

Async batch

Share one AsyncNdiClient. Each jobs.wait polls independently.

import asyncio

from ndi_sdk import AsyncNdiClient


async def parse_one(client: AsyncNdiClient, name: str) -> str:
    upload = await client.documents.create_upload(name)
    job = await client.documents.parse(upload, wait_seconds=30)
    job = await client.jobs.wait(job.job_id, timeout=600)
    return job.result.markdown


async def main() -> None:
    async with AsyncNdiClient() as client:
        pages = await asyncio.gather(
            parse_one(client, "invoice.pdf"),
            parse_one(client, "report.pdf"),
            return_exceptions=True,
        )
    print([type(p).__name__ if isinstance(p, Exception) else len(p) for p in pages])


asyncio.run(main())

TypeScript is already async — Promise.all over the same client.

Errors

invalid_request — extra body fields, bad source, password on a non-PDF
unsupported_file_type
JobFailedError — job status=failed (for example corrupt_file)

Next