Documentation Index
Fetch the complete documentation index at: https://docs.landing.ai/llms.txt
Use this file to discover all available pages before exploring further.
The new Parse API converts a document into these outputs:
- a reading-order Markdown rendering
- a lean document structure
- a per-element grounding map that ties everything back to the source
- metadata for the API call
This page explains how those outputs fit together so you can use them for retrieval-augmented generation (RAG), search, extraction, or any downstream workflow.
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. 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) | $...$ |
| 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] }
]
}
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]
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 content for the given element type in the Markdown. Applies to text, table, figure, marginalia, attestation, logo, scan_code, and card. When false, content for that type is omitted from the Markdown. |
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. |
{
"pages": [0],
"elements": { "table": { "format": "html" } },
"grounding": { "parts": false }
}
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. |
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. |
