Parse Input Parameters

The Parse API accepts a document, an optional model, and an optional options object. The same core fields work whether you call it synchronously or create a Parse Job, which takes a few additional parameters of its own.

Sample Request

Create a Parse Job on the standard service tier, then collect the parse results from the finished job. Replace YOUR_API_KEY with your API key and document.pdf with the path to your file.

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

from pathlib import Path
from landingai_ade import LandingAIADE

client = LandingAIADE()

job = client.v2.parse_jobs.create(
    document=Path("document.pdf"),
    model="dpt-3-pro-latest",
    options={"pages": [1]},
    service_tier="standard",
)
done = client.v2.parse_jobs.wait(job.job_id)
print(done.result.markdown)

import fs from "fs";
import LandingAIADE from "landingai-ade";

const client = new LandingAIADE();

const job = await client.v2.parseJobs.create({
  document: fs.createReadStream("document.pdf"),
  model: "dpt-3-pro-latest",
  options: { pages: [1] },
  service_tier: "standard",
});
const done = await client.v2.parseJobs.wait(job.job_id);
console.log((done.result as LandingAIADE.V2ParseResponse).markdown);

Parameters

Parameter	Required	Description
`document`	Conditional	The document to parse (PDF, image, or Office document), sent as an uploaded file. Provide either `document` or `document_url`.
`document_url`	Conditional	A public URL that the API fetches the document from. Provide either `document` or `document_url`.
`model`	No	The parsing model family and snapshot. Defaults to the latest DPT-3 Pro snapshot. See Model Version.
`options`	No	A JSON object of optional settings. See Request Options.
`service_tier`	No	Parse Jobs only: the tier the job runs on, either `standard` or `priority`. Defaults to `standard`. See Choose a Service Tier.
`output_save_url`	No	Parse Jobs only: a presigned URL the job delivers its output to, instead of returning it in `result`. See Save Parsed Output to a URL.

Model Version

The model form field selects the parsing model family and snapshot:

dpt-3-pro: the highest-quality model. Default.
dpt-3-verity: the lower-latency model for digitally created text documents. In preview.

Requests that omit model use the latest DPT-3 Pro snapshot, and the response reports the resolved version in metadata.model_version. For the full comparison, all accepted values, and guidance on pinning snapshots, see Parsing Models. For example, this request selects the latest DPT-3 Pro snapshot:

cURL

curl -X POST 'https://api.ade.landing.ai/v2/parse/jobs' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'document=@document.pdf' \
  -F 'model=dpt-3-pro-latest' \
  -F 'service_tier=standard'

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`	1-indexed page numbers to process. `null` processes all pages. Page numbers below 1 or beyond the document’s last page return HTTP 422, and a single invalid value rejects the whole request. Skipped pages are absent from `structure.children`, and the Markdown has no gap marker; check each page’s `grounding.page` to identify missing pages.
`blocks.<type>.markdown`	`bool`	`true`	Whether to include the block 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 blocks still appear in `structure`, with a zero-length `range` and an empty `atomic_grounding` array.
`blocks.table.format`	`"markdown"` or `"html"`	`"html"`	Table representation in the Markdown output. HTML preserves merged cells that pipe syntax cannot; `markdown` uses pipe syntax.
`atomic_grounding`	`bool`	`true`	Whether to include the fine-grained `atomic_grounding` array on leaf blocks. Set `false` to omit the field from every node. On DPT-3 Verity, this also removes every `confidence` score, because the scores live on the word entries.
`inline_markdown`	`bool`	`false`	When `true`, every structure node (the document root, each page, and each block, including table cells) carries its own `markdown` field with its slice of the top-level Markdown, so you don’t have to slice by `range` yourself. Entries in `atomic_grounding` do not carry it.
`password`	`string`	`null`	Not currently supported: encrypted PDFs are rejected, and providing a password returns HTTP 422. Decrypt the file and upload an unencrypted copy.

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 view of the parse results the finished job returns in result.

Process Specific Pages

Pass pages to parse only the pages you need. Page numbers are 1-indexed: 1 is the document’s first page. 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/jobs' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'document=@calibration-report.pdf' \
  -F 'model=dpt-3-pro-latest' \
  -F 'options={"pages":[1,3]}' \
  -F 'service_tier=standard'

from pathlib import Path
from landingai_ade import LandingAIADE

client = LandingAIADE()

job = client.v2.parse_jobs.create(
    document=Path("calibration-report.pdf"),
    model="dpt-3-pro-latest",
    options={"pages": [1, 3]},
    service_tier="standard",
)
done = client.v2.parse_jobs.wait(job.job_id)
print(done.result.markdown)

import fs from "fs";
import LandingAIADE from "landingai-ade";

const client = new LandingAIADE();

const job = await client.v2.parseJobs.create({
  document: fs.createReadStream("calibration-report.pdf"),
  model: "dpt-3-pro-latest",
  options: { pages: [1, 3] },
  service_tier: "standard",
});
const done = await client.v2.parseJobs.wait(job.job_id);
console.log((done.result as LandingAIADE.V2ParseResponse).markdown);

When you get the parse results, page_count counts all pages but structure.children holds only pages 1 and 3:

{
  "metadata": {
    "page_count": 3,
    "failed_pages": []
    // ...
  },
  "structure": {
    "type": "document",
    "children": [
      {
        "type": "page",
        "grounding": { "page": 1, "range": { "start": 0, "end": 1695 }, "box": { "xmin": 0, "ymin": 0, "xmax": 1, "ymax": 1 } },
        "status": "ok",
        "children": [ /* ... */ ]
      },
      {
        "type": "page",
        "grounding": { "page": 3, "range": { "start": 1716, "end": 3224 }, "box": { "xmin": 0, "ymin": 0, "xmax": 1, "ymax": 1 } },
        "status": "ok",
        "children": [ /* ... */ ]
      }
    ]
  }
}

Render Tables as Markdown

Tables are returned as HTML by default. HTML preserves merged cells and nested layouts that pipe syntax cannot represent, such as the Measured Value header spanning the As Found and As Left columns in this calibration table:

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

Set blocks.table.format to markdown to receive tables as pipe-syntax Markdown instead. Merged cells expand into empty adjacent cells:

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

from pathlib import Path
from landingai_ade import LandingAIADE

client = LandingAIADE()

job = client.v2.parse_jobs.create(
    document=Path("calibration-report.pdf"),
    model="dpt-3-pro-latest",
    options={"blocks": {"table": {"format": "markdown"}}},
    service_tier="standard",
)
done = client.v2.parse_jobs.wait(job.job_id)
print(done.result.markdown)

import fs from "fs";
import LandingAIADE from "landingai-ade";

const client = new LandingAIADE();

const job = await client.v2.parseJobs.create({
  document: fs.createReadStream("calibration-report.pdf"),
  model: "dpt-3-pro-latest",
  options: { blocks: { table: { format: "markdown" } } },
  service_tier: "standard",
});
const done = await client.v2.parseJobs.wait(job.job_id);
console.log((done.result as LandingAIADE.V2ParseResponse).markdown);

When you get the parse results, the markdown field carries the same table in pipe syntax, with the merged header flattened into empty cells:

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

Suppress a Block Type

Set a block type’s markdown option to false to drop its content from the markdown. Suppressing a block type also speeds up parsing, because suppressed blocks skip model captioning. Here, figures are suppressed, so each figure collapses to a > [!FIGURE] header line. The figure still appears in structure, with a zero-length range and an empty atomic_grounding array.

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

from pathlib import Path
from landingai_ade import LandingAIADE

client = LandingAIADE()

job = client.v2.parse_jobs.create(
    document=Path("calibration-report.pdf"),
    model="dpt-3-pro-latest",
    options={"blocks": {"figure": {"markdown": False}}},
    service_tier="standard",
)
done = client.v2.parse_jobs.wait(job.job_id)
print(done.result.markdown)

import fs from "fs";
import LandingAIADE from "landingai-ade";

const client = new LandingAIADE();

const job = await client.v2.parseJobs.create({
  document: fs.createReadStream("calibration-report.pdf"),
  model: "dpt-3-pro-latest",
  options: { blocks: { figure: { markdown: false } } },
  service_tier: "standard",
});
const done = await client.v2.parseJobs.wait(job.job_id);
console.log((done.result as LandingAIADE.V2ParseResponse).markdown);

When you get the parse results, the markdown field shows each figure as a header line instead of its content:

AS-FOUND DEVIATION BY TEST POINT

> [!FIGURE]

Omit Atomic Grounding

Set atomic_grounding to false to drop the fine-grained atomic_grounding array from every block, leaving only the block-level grounding. Use this to reduce response size when you don’t need the fine-grained coordinates.

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

from pathlib import Path
from landingai_ade import LandingAIADE

client = LandingAIADE()

job = client.v2.parse_jobs.create(
    document=Path("calibration-report.pdf"),
    model="dpt-3-pro-latest",
    options={"atomic_grounding": False},
    service_tier="standard",
)
done = client.v2.parse_jobs.wait(job.job_id)
print(done.result.markdown)

import fs from "fs";
import LandingAIADE from "landingai-ade";

const client = new LandingAIADE();

const job = await client.v2.parseJobs.create({
  document: fs.createReadStream("calibration-report.pdf"),
  model: "dpt-3-pro-latest",
  options: { atomic_grounding: false },
  service_tier: "standard",
});
const done = await client.v2.parseJobs.wait(job.job_id);
console.log((done.result as LandingAIADE.V2ParseResponse).markdown);

When you get the parse results, each block carries only its block-level grounding, and the atomic_grounding field is omitted entirely:

{
  "type": "text",
  "id": "text-8",
  "grounding": {
    "page": 1,
    "range": { "start": 720, "end": 1169 },
    "box": { "xmin": 0.0902, "ymin": 0.36545, "xmax": 0.9281, "ymax": 0.45273 }
  }
}

Include Markdown on Each Node

Set inline_markdown to true to add each node’s slice of the document Markdown as a markdown field on the node itself, so you can read a block’s text without slicing the top-level string by range.

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

from pathlib import Path
from landingai_ade import LandingAIADE

client = LandingAIADE()

job = client.v2.parse_jobs.create(
    document=Path("calibration-report.pdf"),
    model="dpt-3-pro-latest",
    options={"inline_markdown": True},
    service_tier="standard",
)
done = client.v2.parse_jobs.wait(job.job_id)
print(done.result.markdown)

import fs from "fs";
import LandingAIADE from "landingai-ade";

const client = new LandingAIADE();

const job = await client.v2.parseJobs.create({
  document: fs.createReadStream("calibration-report.pdf"),
  model: "dpt-3-pro-latest",
  options: { inline_markdown: true },
  service_tier: "standard",
});
const done = await client.v2.parseJobs.wait(job.job_id);
console.log((done.result as LandingAIADE.V2ParseResponse).markdown);

When you get the parse results, every structure node (document, page, block, and table cell) carries its markdown slice. Entries in atomic_grounding do not. To get an entry’s text, slice by its range or read the parent block’s markdown:

{
  "type": "text",
  "id": "text-0",
  "grounding": {
    "page": 1,
    "range": { "start": 0, "end": 27 },
    "box": { "xmin": 0.08007, "ymin": 0.02051, "xmax": 0.7402, "ymax": 0.05965 }
  },
  "markdown": "**Report No.** TVL-CAL-7731"
}

Get Started

Client Libraries

Parsing

Extraction

Grounding

General

Security

Administration

Pricing & Credits

Parse Input Parameters

Sample Request

Parameters

Model Version

Request Options

Example Options

Process Specific Pages

Render Tables as Markdown

Suppress a Block Type

Omit Atomic Grounding

Include Markdown on Each Node

​Sample Request

​Parameters

​Model Version

​Request Options

​Example Options

​Process Specific Pages

​Render Tables as Markdown

​Suppress a Block Type

​Omit Atomic Grounding

​Include Markdown on Each Node

Sample Request

Parameters

Model Version

Request Options

Example Options

Process Specific Pages

Render Tables as Markdown

Suppress a Block Type

Omit Atomic Grounding

Include Markdown on Each Node