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

import { NdiClient, isParseResult } 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>; it may already be succeeded when inline waiting finishes

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

Method signature

parse(
  source: DocumentSource | UploadResponse,
  opts?: {
    page_ranges?: PageRange[];
    parse_mode?: "low" | "medium" | "high";
    quality?: "auto";
    ocr?: ParseOcrOptions;
    output?: ParseOutputOptions;
    figures?: ParseFiguresOptions;
    diagrams?: ParseDiagramsOptions;
    chunking?: ParseChunkingOptions;
    spreadsheet?: ParseSpreadsheetOptions;
    password?: string;
    wait_seconds?: number;
    idempotency_key?: string;
  },
): Promise<Job>

Parameters

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

Returns

A Promise<Job>. After success, narrow with isParseResult(job.result). result.markdown is a convenience alias for result.document.markdown. Audio and video set result.lane to "audio" or "video" and mint result.transcript_url; result.transcript is inline on jobs.get only.

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 getters 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

import { NdiClient, isParseResult } 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)).job_id,
);
// Returns: succeeded Job with a ParseResult

Public or presigned URL

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

const client = new NdiClient();
const source = {
  type: "url" as const,
  url: "https://example.com/reports/annual-report.pdf",
  file_name: "annual-report.pdf",
};
const job = await client.jobs.wait(
  (await client.documents.parse(source)).job_id,
);
// Returns: succeeded Job with a ParseResult

The URL must use HTTPS and be reachable by NDI. Use a presigned URL for private storage.

Workspace file

import { NdiClient } from "ndi-sdk";

const client = new NdiClient();
const source = {
  type: "workspace_file" as const,
  workspace_id: "550e8400-e29b-41d4-a716-446655440001",
  file_id: "550e8400-e29b-41d4-a716-446655440004",
};
const job = await client.documents.parse(source);
// Returns: Promise<Job>; workspace ingestion is not required

See Sources and uploads for lifecycle and access rules.

Configuration

Select pages and processing effort

import { NdiClient } from "ndi-sdk";

const client = new NdiClient();
const upload = await client.documents.createUpload("report.pdf");
const job = await client.documents.parse(upload, {
  page_ranges: [{ start: 1, end: 10 }],
  parse_mode: "medium",
});
// Returns: Promise<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

import { NdiClient, isParseResult } 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, {
      output: {
        formats: ["markdown", "text", "blocks"],
        table_format: "html",
        include_page_markers: true,
      },
    })
  ).job_id,
);
// Returns: succeeded Job whose ParseResult populates all three renderings
if (isParseResult(job.result)) {
  console.log(job.result.document.blocks?.length);
}

The default formats are ["markdown", "blocks"]. table_format accepts "html" or "markdown" and defaults to "html". include_page_markers defaults to true.

OCR and OCR geometry

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

const client = new NdiClient();
const upload = await client.documents.createUpload("scanned.pdf");
const job = await client.jobs.wait(
  (
    await client.documents.parse(upload, {
      output: { return_ocr_data: true },
    })
  ).job_id,
);
// Returns: succeeded Job; ParseResult.document.ocr contains OCR geometry when produced
if (isParseResult(job.result)) {
  console.log(job.result.ocr_applied);
  console.log(job.result.document.ocr?.words?.length);
}

OCR mode is automatic, and ocr_applied reports whether it ran. The current runtime accepts only mode: "auto" and rejects a non-empty languages array.

Figures and diagrams

import { NdiClient, isParseResult } 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, {
      output: { include_images: true },
      figures: { mode: "describe" },
      diagrams: { mode: "mermaid" },
    })
  ).job_id,
);
// Returns: succeeded 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

import { NdiClient, isParseResult } 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, {
      chunking: { strategy: "section" },
      wait_seconds: 30,
    })
  ).job_id,
);
// Returns: succeeded Job with section chunks in result.document.chunks
if (isParseResult(job.result)) {
  console.log(job.result.document.chunks?.length);
}

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

import { NdiClient } from "ndi-sdk";

const client = new NdiClient();
const workbook = await client.documents.createUpload("financials.xlsx");
const job = await client.documents.parse(workbook, {
  output: { table_format: "html" },
  spreadsheet: {
    sheets: ["Balance Sheet", "Income Statement"],
    include_hidden_sheets: false,
    include_hidden_rows: false,
    include_hidden_columns: false,
    include_formulas: true,
  },
});
// Returns: Promise<Job> for the selected worksheets

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

Encrypted PDF

import { NdiClient } from "ndi-sdk";

const client = new NdiClient();
const upload = await client.documents.createUpload("encrypted.pdf");
const job = await client.documents.parse(upload, {
  password: "document-password",
});
// Returns: Promise<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

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

const client = new NdiClient();
const job = await client.jobs.wait("job_01JZ8WQ4VK2P7T1J0Y6S4M3N2B");
// Returns: succeeded Job

if (isParseResult(job.result)) {
  const result = job.result;
  console.log(result.document.page_count);
  console.log(result.markdown);          // alias for result.document.markdown
  console.log(result.document.blocks);
  console.log(result.document.chunks);
  console.log(result.ocr_applied);
  console.log(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:

import { NdiClient } from "ndi-sdk";

const client = new NdiClient();
const upload = await client.documents.createUpload("invoice.pdf");
const parsed = await client.jobs.wait(
  (await client.documents.parse(upload, { wait_seconds: 30 })).job_id,
);
// Returns: succeeded Job

const schema = {
  type: "object",
  properties: { total: { type: "number" } },
};
const extractJob = await client.documents.extract(
  { type: "parse_result", job_id: parsed.job_id },
  { json_schema: schema },
);
// Returns: Promise<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. parse_mode must remain "low" on a parse_result source.

Complete example

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

const client = new NdiClient();
const upload = await client.documents.createUpload("annual-report.pdf");
const queued = await client.documents.parse(upload, {
  page_ranges: [{ start: 1, end: 20 }],
  parse_mode: "medium",
  output: {
    formats: ["markdown", "blocks"],
    table_format: "html",
    include_images: true,
  },
  figures: { mode: "describe" },
  chunking: { strategy: "section" },
  wait_seconds: 30,
});
const job = await client.jobs.wait(queued.job_id, { timeout: 600 });
// Returns: ParseResult with markdown, blocks, images, and section chunks

if (isParseResult(job.result)) {
  const result = job.result;
  console.log(`Processed ${result.document.page_count} pages`);
  console.log(`Used ${result.units} units`);
  console.log(`Created ${result.document.chunks?.length ?? 0} chunks`);
}

Error handling

import { NdiClient, InvalidRequestError, JobFailedError } from "ndi-sdk";

const client = new NdiClient();
try {
  const upload = await client.documents.createUpload("report.pdf");
  const queued = await client.documents.parse(upload);
  const job = await client.jobs.wait(queued.job_id, { timeout: 600 });
  // Returns: succeeded Job, or throws for request/job failure
} catch (err) {
  if (err instanceof InvalidRequestError) {
    console.log(err.code, err.message);
  } else if (err instanceof JobFailedError) {
    console.log(err.job.status, err.job.error);
  } else {
    throw err;
  }
}

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 figures: { 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 { type: "parse_result", job_id } 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

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

​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

Complete example

Error handling

Best practices

Next steps