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	One-based inclusive ranges. Omit to parse the whole document
`parse_mode`	`low`	Parsing effort: `low` uses native OCR, `medium` routes to the best parser, and `high` adds page verification and correction
`output.formats`	`markdown`, `blocks`	Which renderings to populate on `result.document`. Omitted formats are `null`. `text` is stripped plaintext
`output.table_format`	`html`	How tables are written inside markdown and text. Layout blocks keep their own structure
`output.include_images`	`false`	When true, figure blocks include a crop URL for PDF and raster uploads
`output.include_page_markers`	`true`	Insert `--- Page N ---` headers between PDF pages in markdown and text
`figures.mode`	`include`	Drop figures, keep the crop, or keep the crop and generate a caption (`describe`, one vision call per figure)
`diagrams.mode`	`omit`	Leave flowchart-like figures as images, or rewrite them as Mermaid fences
`chunking.strategy`	`none`	`none` leaves `chunks` empty; `page` and `section` produce RAG-sized pieces
`spreadsheet`	all sheets	Workbook-only filters for sheet names, hidden cells, and formula source text
`password`	none	Password for an encrypted PDF. Write-only: never stored or returned

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