Parse

documents.parse converts a document into structured text. It can return markdown, plain text, layout blocks, optional chunks, image crops, spreadsheet metadata, or an audio/video transcript depending on the source and options. OCR runs automatically when the document needs it. Read ocr_applied on the result to see whether it ran.

Basic usage

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; it may already be succeeded when inline waiting finishes

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

Method signature

def parse(
    source: DocumentSource | UploadResponse,
    *,
    page_ranges: list[PageRange] | None = None,
    parse_mode: Literal["low", "medium", "high"] = "low",
    quality: Literal["auto"] = "auto",
    ocr: ParseOcrOptions | None = None,
    output: ParseOutputOptions | None = None,
    figures: ParseFiguresOptions | None = None,
    diagrams: ParseDiagramsOptions | None = None,
    chunking: ParseChunkingOptions | None = None,
    spreadsheet: ParseSpreadsheetOptions | None = None,
    password: str | None = None,
    wait_seconds: int = 0,
    idempotency_key: str | None = None,
) -> Job

Parameters

Parameter	Type	Required	Description
`source`	`DocumentSource` or `UploadResponse`	Yes	Staged upload, HTTPS URL, workspace file, or successful parse job
`page_ranges`	`list[PageRange]`	No	One-based inclusive ranges. Omit for the whole document
`parse_mode`	`"low"` / `"medium"` / `"high"`	No	Processing effort. `medium` routes to the best parser; `high` adds page verification and correction
`quality`	`"auto"`	No	Only accepted value
`ocr`	`ParseOcrOptions`	No	Automatic OCR. The current runtime accepts only `mode="auto"` and no language hints
`output`	`ParseOutputOptions`	No	Renderings, table style, images, OCR geometry, and page markers
`figures`	`ParseFiguresOptions`	No	Defaults to `mode="include"`. Pass `mode="describe"` to add figure descriptions or `mode="omit"` to drop figures
`diagrams`	`ParseDiagramsOptions`	No	Omit diagrams or rewrite them as Mermaid
`chunking`	`ParseChunkingOptions`	No	Leave chunks empty or group content by page or section
`spreadsheet`	`ParseSpreadsheetOptions`	No	Sheet, hidden-cell, and formula controls for workbooks
`password`	`str`	No	Encrypted PDF password. Never stored or returned
`wait_seconds`	`int`	No	Hold the submission request open for up to 300 seconds
`idempotency_key`	`str`	No	Override the key the SDK normally mints

Returns

A Job. After success, job.result is a ParseResult:

Field	Description
`file_name`	Name of the source file
`lane`	Parser lane, such as document, spreadsheet, audio, or video
`document`	`page_count`, requested renderings, blocks, chunks, and spreadsheet metadata
`document.content_url`	Authenticated complete content when an inline document rendering is only a preview
`markdown` / `text`	Convenience properties for `document.markdown` and `document.text`
`disclosures`	Typed qualifications, including `content_truncated` for bounded previews
`ocr_applied`	Whether OCR ran
`converted_pdf_url`	Authenticated converted PDF for supported Office sources
`transcript_url` / `transcript`	Media timeline for audio and video
`units`	Billable units

Ordinary results keep the requested content inline and leave content_url null. An oversized Office package that uses structural-text parsing exposes complete extracted text at document.content_url and reports parse_fidelity with mode="reduced_layout". Separately, when a finalized document result is too large, Markdown/text is a bounded preview, document.content_url contains the complete finalized content, and a content_truncated disclosure has target="document_content". Oversized workbooks use target="spreadsheet_region" and expose complete Markdown under each affected document.spreadsheet.sheets[].content_url. Fetch these URLs with the same X-API-Key used by the client.

Source options

Staged upload

from ndi_sdk import NdiClient

with NdiClient() as client:
    upload = client.documents.create_upload("report.pdf")
    job = client.documents.parse(upload)
    # Returns: Job

Public or presigned URL

from ndi_sdk import NdiClient, UrlSource

with NdiClient() as client:
    source = UrlSource(
        url="https://example.com/reports/annual-report.pdf",
        file_name="annual-report.pdf",
    )
    job = client.documents.parse(source)
    # Returns: Job

Workspace file

from ndi_sdk import NdiClient, WorkspaceFileSource

with NdiClient() as client:
    source = WorkspaceFileSource(
        workspace_id="550e8400-e29b-41d4-a716-446655440001",
        file_id="550e8400-e29b-41d4-a716-446655440004",
    )
    job = client.documents.parse(source)
    # Returns: Job; workspace ingestion is not required

See Sources and uploads for lifecycle and access rules.

Configuration

Select pages and processing effort

from ndi_sdk import NdiClient
from ndi_sdk.models.document_ops import PageRange

with NdiClient() as client:
    upload = client.documents.create_upload("report.pdf")
    job = client.documents.parse(
        upload,
        page_ranges=[PageRange(start=1, end=10)],
        parse_mode="medium",
    )
    # Returns: Job for pages 1 through 10

Use low for the default native path, medium to route to the best parser, and high when page-level verification and correction justify additional latency.

Choose output formats

from ndi_sdk import NdiClient
from ndi_sdk.models.document_ops import ParseOutputOptions

with NdiClient() as client:
    upload = client.documents.create_upload("report.pdf")
    job = client.documents.parse(
        upload,
        output=ParseOutputOptions(
            formats=["markdown", "text", "blocks"],
            table_format="html",
            include_page_markers=True,
        ),
    )
    # Returns: Job whose ParseResult populates all three renderings

The default formats are markdown and blocks. Omitted renderings are None. table_format accepts html or markdown and defaults to html. include_page_markers defaults to True.

OCR and OCR geometry

from ndi_sdk import NdiClient
from ndi_sdk.models.document_ops import ParseOutputOptions

with NdiClient() as client:
    upload = client.documents.create_upload("report.pdf")
    job = client.documents.parse(
        upload,
        output=ParseOutputOptions(return_ocr_data=True),
    )
    # Returns: Job; ParseResult.document.ocr contains OCR geometry when produced

OCR mode is automatic, and ParseResult.ocr_applied reports whether it ran. Although ParseOcrOptions exposes languages, the current runtime rejects a non-empty language list.

Figures and diagrams

from ndi_sdk import NdiClient
from ndi_sdk.models.document_ops import (
    ParseDiagramsOptions,
    ParseFiguresOptions,
    ParseOutputOptions,
)

with NdiClient() as client:
    upload = client.documents.create_upload("report.pdf")
    job = client.documents.parse(
        upload,
        output=ParseOutputOptions(include_images=True),
        figures=ParseFiguresOptions(mode="describe"),
        diagrams=ParseDiagramsOptions(mode="mermaid"),
    )
    # Returns: Job with figure crops/descriptions and Mermaid where supported

figures.mode accepts omit, include, or describe and defaults to include. Diagram mode accepts omit or mermaid and defaults to omit.

Chunking

from ndi_sdk import NdiClient
from ndi_sdk.models.document_ops import ParseChunkingOptions

with NdiClient() as client:
    upload = client.documents.create_upload("report.pdf")
    job = client.jobs.wait(
        client.documents.parse(
            upload,
            chunking=ParseChunkingOptions(strategy="section"),
            wait_seconds=30,
        ).job_id
    )
    # Returns: succeeded Job with section chunks in result.document.chunks

Chunking defaults to none, which leaves document.chunks empty. Use page or section for retrieval-oriented chunks. Use markdown for whole-document display.

Spreadsheet controls

from ndi_sdk import NdiClient
from ndi_sdk.models.document_ops import (
    ParseOutputOptions,
    ParseSpreadsheetOptions,
)

with NdiClient() as client:
    workbook = client.documents.create_upload("financials.xlsx")
    job = client.documents.parse(
        workbook,
        output=ParseOutputOptions(table_format="html"),
        spreadsheet=ParseSpreadsheetOptions(
            sheets=["Balance Sheet", "Income Statement"],
            include_hidden_sheets=False,
            include_hidden_rows=False,
            include_hidden_columns=False,
            include_formulas=True,
        ),
    )
    # Returns: Job for the selected worksheets

An empty sheets list is rejected. Formula source text requires HTML table output and markdown or blocks in output.formats.

Encrypted PDF

from ndi_sdk import NdiClient

with NdiClient() as client:
    upload = client.documents.create_upload("encrypted.pdf")
    job = client.documents.parse(upload, password="document-password")
    # Returns: Job; the password is write-only

The password is accepted only for PDF sources and is excluded from stored job requests and representations.

Response structure

# After client.jobs.wait returns a succeeded parse job:
result = ...

print(result.document.page_count)
print(result.document.markdown)
print(result.document.blocks)
print(result.document.chunks)
print(result.ocr_applied)
print(result.units)

Layout block locations vary by source: pages use normalized polygons, workbooks use sheet ranges, tables can use row ranges, and structured text can use JSON pointers or character spans. Audio and video use the same method. Their result lane is audio or video, and transcript contains the speaker-attributed timeline on a single-job read. See Parse response format.

Reuse a parse

Pass a successful parse job to extract, split, or ground to avoid paying for the same parse twice:

from ndi_sdk import NdiClient, ParseResultSource

with NdiClient() as client:
    upload = client.documents.create_upload("invoice.pdf")
    parsed = client.jobs.wait(
        client.documents.parse(upload, wait_seconds=30).job_id
    )
    source = ParseResultSource(job_id=parsed.job_id)
    schema = {
        "type": "object",
        "properties": {"total": {"type": "number"}},
    }
    extract_job = client.documents.extract(source, json_schema=schema)
    # Returns: Job; NDI reuses the prior ParseResult

Classify does not accept a parse-result source. Page selection is unavailable when reusing a parse, and a reused parse cannot add images that were not already produced.

Async parse

import asyncio

from ndi_sdk import AsyncNdiClient


async def main() -> None:
    async with AsyncNdiClient() as client:
        upload = await client.documents.create_upload("report.pdf")
        queued = await client.documents.parse(upload, wait_seconds=30)
        job = await client.jobs.wait(queued.job_id, timeout=600)
        # Returns: succeeded Job with a ParseResult
        print(job.result.markdown)


asyncio.run(main())

Use the async client guide for bounded concurrent processing.

Complete example

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

with NdiClient() as client:
    upload = client.documents.create_upload("annual-report.pdf")
    queued = client.documents.parse(
        upload,
        page_ranges=[PageRange(start=1, end=20)],
        parse_mode="medium",
        output=ParseOutputOptions(
            formats=["markdown", "blocks"],
            table_format="html",
            include_images=True,
        ),
        figures=ParseFiguresOptions(mode="describe"),
        chunking=ParseChunkingOptions(strategy="section"),
        wait_seconds=30,
    )
    job = client.jobs.wait(queued.job_id, timeout=600)
    # Returns: ParseResult with markdown, blocks, images, and section chunks

    result = job.result
    print(f"Processed {result.document.page_count} pages")
    print(f"Used {result.units} units")
    print(f"Created {len(result.document.chunks)} chunks")

Error handling

from ndi_sdk import InvalidRequestError, JobFailedError, NdiClient

with NdiClient() as client:
    try:
        queued = client.documents.parse(
            client.documents.create_upload("report.pdf")
        )
        job = client.jobs.wait(queued.job_id, timeout=600)
        # Returns: succeeded Job, or raises for request/job failure
    except InvalidRequestError as exc:
        print(exc.code, exc.message)
    except JobFailedError as exc:
        print(exc.job.status, exc.job.error)

Common failures include an unsupported format, a corrupt file, invalid page ranges, a wrong PDF password, or options incompatible with the source.

Best practices

Request only what you use

Extra renderings, images, descriptions, and higher parse modes add work. Figure descriptions are enabled by default; pass ParseFiguresOptions(mode="omit") when you do not need them.

Inspect OCR status

Use ocr_applied rather than assuming every document was OCR-processed.

Chunk for retrieval

Choose page or section chunking for RAG. Keep whole-document markdown for display.

Reuse successful parses

Pass ParseResultSource to extract, split, or ground when they should read the same parse.

Get started

Core methods

Async and utilities

Basic usage

Method signature

Parameters

Returns

Source options

Staged upload

Public or presigned URL

Workspace file

Configuration

Select pages and processing effort

Choose output formats

OCR and OCR geometry

Figures and diagrams

Chunking

Spreadsheet controls

Encrypted PDF

Response structure

Reuse a parse

Async parse

Complete example

Error handling

Best practices

Request only what you use

Inspect OCR status

Chunk for retrieval

Reuse successful parses

Next steps

​Basic usage

​Method signature

​Parameters

​Returns

​Source options

​Staged upload

​Public or presigned URL

​Workspace file

​Configuration

​Select pages and processing effort

​Choose output formats

​OCR and OCR geometry

​Figures and diagrams

​Chunking

​Spreadsheet controls

​Encrypted PDF

​Response structure

​Reuse a parse

​Async parse

​Complete example

​Error handling

​Best practices

Request only what you use

Inspect OCR status

Chunk for retrieval

Reuse successful parses

​Next steps

Basic usage

Method signature

Parameters

Returns

Source options

Staged upload

Public or presigned URL

Workspace file

Configuration

Select pages and processing effort

Choose output formats

OCR and OCR geometry

Figures and diagrams

Chunking

Spreadsheet controls

Encrypted PDF

Response structure

Reuse a parse

Async parse

Complete example

Error handling

Best practices

Next steps