How Parse Works - LandingAI

The new Parse API converts a document into structured data for retrieval-augmented generation (RAG), search, extraction, or any downstream workflow. This page covers how to call the API, select a model version, and customize the parse with options. It then explains the response: the reading-order Markdown, the document structure, the per-element grounding that maps everything back to the source, and the request metadata. If you haven’t made an API call yet, start with the Quickstart to get a real response to follow along with.

This is a Preview release. Don’t use it in production. See Important to Know for details. To learn more about the generally available (GA) version of ADE, go to ADE Overview.

Call the Parse API

Send a document to the parse endpoint with a POST request. Replace YOUR_API_KEY with your API key and document.pdf with the path to your file. The options field is optional: the defaults suit most documents, so include it only to customize the parse (here, to process specific pages). For the full request and response contract, see the API reference.

curl -X POST 'https://api.ade.landing.ai/v2/parse' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'document=@document.pdf' \
  -F 'model=dpt-3-pro-latest' \
  -F 'options={"pages":[0]}'

Model Version

is the current version of . By default, requests use the latest snapshot. To pin to a specific snapshot, supply it in the model form field on the request. The resolved version is returned in metadata.version. Use a -latest alias for development or when you want continuous improvements; pin to a dated snapshot for production workloads where consistent results matter. Accepted values:

Value	Behavior
`dpt-3-pro-latest`	The latest snapshot of DPT-3 Pro.
`dpt-3-pro-20260515`	The snapshot of DPT-3 Pro generated on May 15, 2026.

Request Options

The optional options form field is a JSON object that customizes the response. All fields are optional; omitted fields take the defaults shown.

Field	Type	Default	Description
`pages`	`int[]`	`null`	0-indexed page indices to process. `null` processes all pages. Negative indices return HTTP 422; indices beyond `page_count` are silently ignored. Skipped pages are absent from `structure.children`, and the Markdown has no gap marker; check `structure.children[].page` to identify missing pages.
`elements.<type>.caption`	`bool`	`true`	Whether to include the element type’s content in the Markdown. Applies to `text`, `table`, `figure`, `marginalia`, `attestation`, `logo`, `scan_code`, and `card`. When `false`, visual types (`figure`, `logo`, `scan_code`, `card`, `attestation`) emit only a header line such as `> [!FIGURE]`; `text`, `table`, and `marginalia` emit nothing. Suppressed elements still appear in `structure` and `grounding`.
`elements.table.format`	`"markdown"` or `"html"`	`"markdown"`	Table representation in the Markdown output.
`grounding.parts`	`bool`	`true`	Whether to include the fine-grained `parts` array in each grounding entry. Set `false` to omit.

Example Options

The following examples all parse the same sample calibration report, so you can see exactly what each option changes. For the complete, unmodified output, download the full default response (parsed with no options). Each example shows the full request with the relevant options line highlighted, followed by a trimmed response.

Process Specific Pages

Pass pages to parse only the pages you need. metadata.page_count still reports the full document length, while structure.children returns only the requested pages.

curl -X POST 'https://api.ade.landing.ai/v2/parse' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'document=@calibration-report.pdf' \
  -F 'model=dpt-3-pro-latest' \
  -F 'options={"pages":[0,2]}'

The response counts all pages in page_count but returns only pages 0 and 2 in structure.children:

{
  "metadata": {
    "page_count": 3,
    "failed_pages": []
    // ...
  },
  "structure": {
    "type": "document",
    "children": [
      { "type": "page", "page": 0, "span": [0, 1543], "status": "ok", "children": [ /* ... */ ] },
      { "type": "page", "page": 2, "span": [1558, 3068], "status": "ok", "children": [ /* ... */ ] }
    ]
  }
}

Render Tables as HTML

Set elements.table.format to html to receive tables as HTML <table> markup instead of the default pipe syntax. HTML preserves merged cells and nested layouts that pipe tables cannot represent.

curl -X POST 'https://api.ade.landing.ai/v2/parse' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'document=@calibration-report.pdf' \
  -F 'model=dpt-3-pro-latest' \
  -F 'options={"elements":{"table":{"format":"html"}}}'

The markdown field returns the table as HTML, preserving the merged Measured Value header that pipe syntax can’t represent:

<table>
<tr><td rowspan="2">Test Point</td><td rowspan="2">Nominal (V)</td><td colspan="2">Measured Value (V)</td><td rowspan="2">As-Found Deviation (mV)</td><td rowspan="2">Tolerance (±mV)</td><td rowspan="2">Result</td></tr>
<tr><td>As Found</td><td>As Left</td></tr>
<tr><td>TP-1</td><td>0.000</td><td>0.001</td><td>0.000</td><td>+1</td><td>5</td><td>Pass</td></tr>
<tr><td>TP-2</td><td>2.500</td><td>2.503</td><td>2.500</td><td>+3</td><td>10</td><td>Pass</td></tr>
<tr><td>TP-3</td><td>5.000</td><td>5.041</td><td>5.002</td><td>+41</td><td>20</td><td>Fail</td></tr>
<tr><td>TP-4</td><td>7.500</td><td>7.512</td><td>7.503</td><td>+12</td><td>30</td><td>Pass</td></tr>
<tr><td>TP-5</td><td>10.000</td><td>10.018</td><td>10.004</td><td>+18</td><td>40</td><td>Pass</td></tr>
</table>

Suppress an Element Type

Set an element type’s caption to false to drop its content from the markdown. Here, figures are suppressed, so each figure collapses to a > [!FIGURE] header line. The figure still appears in structure and grounding.

curl -X POST 'https://api.ade.landing.ai/v2/parse' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'document=@calibration-report.pdf' \
  -F 'model=dpt-3-pro-latest' \
  -F 'options={"elements":{"figure":{"caption":false}}}'

The markdown field shows each figure as a header line instead of a description:

AS-FOUND DEVIATION BY TEST POINT

> [!FIGURE]

Omit Grounding Parts

Set grounding.parts to false to drop the fine-grained parts array from each grounding entry, leaving only the element-level box. Use this to reduce response size when you don’t need line-level coordinates.

curl -X POST 'https://api.ade.landing.ai/v2/parse' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'document=@calibration-report.pdf' \
  -F 'model=dpt-3-pro-latest' \
  -F 'options={"grounding":{"parts":false}}'

Each grounding entry returns an empty parts array:

{
  "21": {
    "page": 0,
    "span": [570, 1018],
    "box": [55, 292, 549, 357],
    "parts": []
  }
  // ...
}

The Response Shape

A successful parse returns a JSON object with these top-level fields:

Field	Description
`markdown`	The complete document as a single Markdown string, in reading order.
`metadata`	Information about the job: model version, page count, duration, credit usage, and more.
`structure`	A `document` node whose `children` are pages. Each page’s `children` are the elements detected on that page. Carries types, ids, and Markdown spans only (no spatial data).
`grounding`	A flat object keyed by element `id`. Each value carries the element’s page, Markdown span, bounding box, and finer-grained parts.

Markdown

The markdown field is a single string containing the document in reading order, following CommonMark 0.31.2 with a few extensions. Use it directly for RAG, search indexing, or anything that takes Markdown as input. All span offsets elsewhere in the response point into this string as Unicode code point indices.

Element	Representation
Page break	`<!-- page -->` appended after each page’s content. Absent in single-page documents.
Table	Pipe syntax by default. Merged cells expand into empty adjacent cells. Use `options.elements.table.format="html"` to emit HTML `<table>` instead.
Figure	Markdown image syntax `![label]`. The label is either a classification subtype (for example, `![CHART]`) or a brief description (for example, `![Bar chart showing Q1 revenue]` or `![Share button]`). See Figure and Attestation Labels below.
Logo	Markdown image syntax `![label]` containing a brief description (for example, `![ADP logo]`).
Card	Transcribed visible text content from the card.
Scan code	Transcribed code type and value.
Attestation	A Markdown image tag for the visual mark followed by the transcribed text: `![TYPE] caption`. Printed text on an attestation appears as plain prose without a label. See Figure and Attestation Labels.
Math (block)	`$$...$$`
Math (inline)	$...$

Figure and Attestation Labels

The Markdown image syntax for figures and attestations can carry a classification label that downstream consumers can branch on without re-running detection.

Element	Labels	Example
Figure	`CHART`, `FLOWCHART`, `DIAGRAM`, `ILLUSTRATION`, `PHOTOGRAPH` (fallback `FIGURE`)	`![CHART]`
Attestation	`SIGNATURE`, `E-SIGN`, `STAMP`, `SEAL` (printed text has no label)	`![SIGNATURE] J. Doe`

Structure: Pages and Elements

The structure field is a document node whose children are pages, and each page’s children are the elements on that page. The tree carries types, ids, and Markdown spans. Spatial information lives in grounding.

Common Element Fields

Every node in the structure tree shares the same base shape:

Field	Description
`type`	The node type. See element types below.
`id`	A unique element identifier within the document. Used to look up entries in the top-level `grounding`. Treat as opaque (current model versions emit stringified monotonically-increasing integers, but the shape is not part of the contract).
`span`	A two-element array `[start, end)` giving the Unicode code point offsets in the global `markdown` string covered by this node.
`children`	Child elements. Present on `document`, `page`, and `table`.

Page Fields

page nodes have additional fields describing the source page:

Field	Description
`page`	The 0-indexed page number in the source document.
`width`, `height`	Page dimensions, in `unit`. `null` for failed pages.
`dpi`	Resolution used for the coordinate system. `null` for failed pages.
`unit`	`"pt"` for PDFs, `"px"` for images. `null` for failed pages.
`status`	`"ok"` if the page was parsed successfully, or `"failed"`.
`reason`	Failure reason. Present only when `status` is `"failed"`.
`span`	Markdown range covering the page’s content. Zero-length `[n, n]` for failed pages.

Element Types

recognizes the following element types:

Type	Description
`text`	Any textual content: titles, headings, paragraphs, lists, captions, key-value pairs, form fields, headers, and footers.
`table`	A table. Its `children` are the cells.
`td`	A table data cell.
`th`	A table header cell.
`figure`	An image, chart, diagram, or other non-text visual content.
`marginalia`	Text appearing in the margins, outside the main content flow.
`attestation`	A certification, stamp, or signature region.
`logo`	A company or brand logo.
`card`	A business card or card-like element.
`scan_code`	A QR code, barcode, or other machine-readable code.

Tables and Cells

A table element has its own id and span, and a children array of td (data) and th (header) cells in row-major order. Each cell carries its grid position:

Field	Description
`row`	0-indexed row position.
`col`	0-indexed column position.
`colspan`	Number of columns the cell spans. Defaults to 1.
`rowspan`	Number of rows the cell spans. Defaults to 1.

{
  "type": "table",
  "id": "3",
  "span": [114, 212],
  "children": [
    { "type": "th", "id": "4", "span": [114, 114], "row": 0, "col": 0, "colspan": 1, "rowspan": 1 },
    { "type": "th", "id": "5", "span": [118, 125], "row": 0, "col": 1, "colspan": 1, "rowspan": 1 },
    { "type": "td", "id": "6", "span": [154, 161], "row": 1, "col": 0, "colspan": 1, "rowspan": 1 },
    { "type": "td", "id": "7", "span": [164, 169], "row": 1, "col": 1, "colspan": 1, "rowspan": 1 }
  ]
}

Grounding: Where Things Are

The top-level grounding field is a flat object keyed by element id. Each value carries the element’s spatial information and a finer-grained parts array.

Element Grounding Fields

Field	Description
`page`	The 0-indexed page number the element belongs to.
`span`	A two-element array `[start, end)` giving the Unicode code point offsets in the global `markdown` string covered by the full element. Matches the `span` on the same element in the `structure` tree.
`box`	A four-element array `[left, top, right, bottom]` giving the element’s bounding box on the source page. Coordinates use the page’s `unit` (`pt` for PDFs, `px` for images).
`parts`	Finer-grained grounding segments. Each entry has the same `span` and `box` shape as the element-level fields.

Parts

The parts array gives line-level (or finer) detail:

For text and marginalia, you get one entry per visual line.
For all other element types, parts is an empty array [].
Segment spans are contiguous sub-ranges of the element’s span.

Example: Multi-Line Paragraph

A paragraph that wraps across two visual lines produces one element with two parts. The element-level box covers both lines:

"2": {
  "page": 0,
  "span": [29, 112],
  "box": [49, 95, 563, 143],
  "parts": [
    { "span": [29, 74],  "box": [49, 95,  563, 119] },
    { "span": [75, 112], "box": [49, 119, 355, 143] }
  ]
}

Example: Figure (No Parts)

Non-text elements have an empty parts array. The element-level box is the direct bounding region:

"8": {
  "page": 0,
  "span": [214, 354],
  "box": [49, 380, 563, 618],
  "parts": []
}

Working with Boxes

Boxes use integer coordinates in the page’s unit. For PDFs, the unit is typically pt (points, where 1 inch = 72 points). For images, the unit is px (pixels). To normalize a box to page-relative coordinates:

left, top, right, bottom = entry["box"]
normalized = (
    left / page["width"],
    top / page["height"],
    right / page["width"],
    bottom / page["height"],
)

Slicing the Markdown

To get the actual text of an element, slice the global Markdown string using span. When an element has multiple parts, each part slices its own substring:

start, end = entry["span"]
element_markdown = response["markdown"][start:end]

Metadata

The metadata field describes the job.

Field	Description
`job_id`	A unique identifier for this parse job. Useful for tracking a document across a workflow (for example, parse to extract) and for support requests.
`filename`	The filename of the parsed document.
`version`	The exact model snapshot used (for example, `dpt-3-pro-20260515`).
`page_count`	Total number of pages in the source document. Includes pages filtered out by `options.pages`; the pages actually returned are in `structure.children`.
`failed_pages`	An array of 0-indexed page numbers that failed to parse. Empty on success. Also reflected inline in `structure.children` with `status: "failed"` and a `reason`. See Troubleshoot Parsing.
`duration_ms`	Total processing time in milliseconds.
`markdown_chars`	Number of Unicode code points in the returned `markdown` string.
`credit_usage`	Credits consumed by this job (`0` if no credits were consumed). See Pricing for how this is calculated.

​Call the Parse API

​Model Version

​Request Options

​Example Options

​Process Specific Pages

​Render Tables as HTML

​Suppress an Element Type

​Omit Grounding Parts

​The Response Shape

​Markdown

​Figure and Attestation Labels

​Structure: Pages and Elements

​Common Element Fields

​Page Fields

​Element Types

​Tables and Cells

​Grounding: Where Things Are

​Element Grounding Fields

​Parts

​Example: Multi-Line Paragraph

​Example: Figure (No Parts)

​Working with Boxes

​Slicing the Markdown

​Metadata

Call the Parse API

Model Version

Request Options

Example Options

Process Specific Pages

Render Tables as HTML

Suppress an Element Type

Omit Grounding Parts

The Response Shape

Markdown

Figure and Attestation Labels

Structure: Pages and Elements

Common Element Fields

Page Fields

Element Types

Tables and Cells

Grounding: Where Things Are

Element Grounding Fields

Parts

Example: Multi-Line Paragraph

Example: Figure (No Parts)

Working with Boxes

Slicing the Markdown

Metadata