Perception
Parse
client.documents.parse(params, options?) converts a document to Markdown, text, layout blocks or chunks. It takes the shared parameters and:
| Parameter | Type | Required | Description |
|---|---|---|---|
page_ranges | Array<{ start, end }> | No | Pages to parse. Not with a parse_result source. Default: all pages. |
parse_mode | "low" | "medium" | "high" | No | Effort. low uses native OCR, medium routes to the best parser, high adds page verification and correction. Only low with a parse_result source. Default: "low". |
output | { formats?, table_format?, include_images?, include_page_markers?, return_ocr_data? } | No | What the result holds and how. See output. |
figures | { mode?: "include" | "omit" | "describe" } | No | What to do with figures. See figures. |
diagrams | { mode?: "omit" | "mermaid" } | No | Whether to rewrite flowchart-like figures. See diagrams. |
chunking | { strategy?: "none" | "page" | "section" } | No | Split the result into pieces for retrieval. See chunking. |
spreadsheet | { sheets?, include_hidden_sheets?, include_hidden_rows?, include_hidden_columns?, include_formulas? } | No | Which sheets, hidden parts and formulas to read. Not with a parse_result source. See spreadsheet. |
password | string | No | Password for an encrypted PDF. Never stored or returned. Not with a parse_result source. |
A parse_result source with an option marked "not with a parse_result source" set to something other than its default (for spreadsheet: sheets, an include_hidden_* of false, or include_formulas: true), or with a parse_mode other than low, is refused with 422 before a job starts. OCR runs when the file needs it: the document service refuses any ocr setting other than the default with 422 invalid_request.
Each object option takes these keys:
output
| Key | Type | Default | Description |
|---|---|---|---|
output.formats | Array<string> | ["markdown", "blocks"] | What to return: "markdown", "blocks" and "text". |
output.table_format | "html" | "markdown" | "html" | How tables are written in the Markdown and blocks. |
output.include_images | boolean | false | Include the page images. Not with a parse_result source. |
output.include_page_markers | boolean | true | Insert page markers between pages. |
output.return_ocr_data | boolean | false | Return word and line OCR geometry. PDF sources only. |
figures
| Key | Type | Default | Description |
|---|---|---|---|
figures.mode | "include" | "omit" | "describe" | "include" | Keep the figures, drop them, or caption each one with a vision call. |
diagrams
| Key | Type | Default | Description |
|---|---|---|---|
diagrams.mode | "omit" | "mermaid" | "omit" | Leave diagrams alone, or rewrite flowchart-like figures as Mermaid. |
chunking
| Key | Type | Default | Description |
|---|---|---|---|
chunking.strategy | "none" | "page" | "section" | "none" | How to split the result into pieces sized for retrieval. |
spreadsheet
Not with a parse_result source.
| Key | Type | Default | Description |
|---|---|---|---|
spreadsheet.sheets | Array<string> | All sheets | The names of the sheets to parse. |
spreadsheet.include_hidden_sheets | boolean | true | Read sheets marked hidden. |
spreadsheet.include_hidden_rows | boolean | true | Read rows marked hidden. |
spreadsheet.include_hidden_columns | boolean | true | Read columns marked hidden. |
spreadsheet.include_formulas | boolean | false | Include cell formulas. Needs output.table_format "html" and markdown or blocks output. |
const job = await client.documents.parse({
source: { type: "url", url: "https://example.com/report.pdf", file_name: "report.pdf" },
page_ranges: [{ start: 1, end: 3 }],
output: { formats: ["markdown", "blocks"] },
chunking: { strategy: "page" },
});
const done = await client.jobs.wait(job.job_id);See Parse for the result shape, and Job files for full content too large to inline.