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

# Parse Input Parameters

> Set the document, model version, and options when calling the Parse v2 API.

export const dpt3pro = 'DPT-3 Pro';

export const dpt3 = 'DPT-3';

export const parseDpt3 = 'Parse';

export const ade = 'Agentic Document Extraction';

Send input to the Parse v2 API as a POST request to `https://api.ade.landing.ai/v2/parse`. This page describes each request field.

## Sample Request

Send a document to the parse endpoint with a POST request. Replace `YOUR_API_KEY` with your [API key](./agentic-api-key) and `document.pdf` with the path to your file.

<CodeGroup>
  ```bash cURL theme={null}
  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":[1]}'
  ```

  ```python Python theme={null}
  from pathlib import Path
  from landingai_ade import LandingAIADE

  client = LandingAIADE()

  response = client.v2.parse(
      document=Path("document.pdf"),
      model="dpt-3-pro-latest",
      options={"pages": [1]},
  )
  print(response.markdown)
  ```

  ```typescript TypeScript theme={null}
  import fs from "fs";
  import LandingAIADE from "landingai-ade";

  const client = new LandingAIADE();

  const response = await client.v2.parse({
    document: fs.createReadStream("document.pdf"),
    model: "dpt-3-pro-latest",
    options: { pages: [1] },
  });
  console.log(response.markdown);
  ```
</CodeGroup>

## Parameters

| Parameter      | Required    | Description                                                                                                  |
| -------------- | ----------- | ------------------------------------------------------------------------------------------------------------ |
| `document`     | Conditional | The document to parse (PDF or image), 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 version. Defaults to the latest snapshot. See [Model Version](#model-version).             |
| `options`      | No          | A JSON object of optional settings. See [Request Options](#request-options).                                 |

## Model Version

{dpt3pro} is the current version of {dpt3}. By default, requests use the latest {dpt3pro} snapshot. To pin to a specific snapshot, supply it in the `model` form field on the request. The resolved version is returned in `metadata.model_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. This is the default.         |
| `dpt-3-pro`          | Alias for `dpt-3-pro-latest`; resolves to the latest snapshot. |
| `dpt-3-pro-20260710` | The snapshot of DPT-3 Pro generated on July 10, 2026.          |

<Info>
  Some snapshots have been superseded: a newer snapshot replaced them, and they no longer appear in the table above. If you pin a superseded snapshot, your requests still succeed. The API resolves the name to the current snapshot and reports the current version in `metadata.model_version`. Update pinned code to a value from the table.
</Info>

## 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 return HTTP 422; numbers beyond `page_count` are silently ignored. 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.                                                                                                                                                                                                                                                                                                                                        |
| `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 <a href="/examples/options/calibration-report.pdf" download="calibration-report.pdf">sample calibration report</a>, so you can see exactly what each option changes.

For the complete, unmodified output, download the <a href="/examples/options/response-no-options.json" download="response-no-options.json">full default response</a> (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. 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.

<CodeGroup>
  ```bash cURL highlight={5} theme={null}
  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":[1,3]}'
  ```

  ```python Python highlight={9} theme={null}
  from pathlib import Path
  from landingai_ade import LandingAIADE

  client = LandingAIADE()

  response = client.v2.parse(
      document=Path("calibration-report.pdf"),
      model="dpt-3-pro-latest",
      options={"pages": [1, 3]},
  )
  print(response.markdown)
  ```

  ```typescript TypeScript highlight={9} theme={null}
  import fs from "fs";
  import LandingAIADE from "landingai-ade";

  const client = new LandingAIADE();

  const response = await client.v2.parse({
    document: fs.createReadStream("calibration-report.pdf"),
    model: "dpt-3-pro-latest",
    options: { pages: [1, 3] },
  });
  console.log(response.markdown);
  ```
</CodeGroup>

The response counts all pages in `page_count` but returns only pages 1 and 3 in `structure.children`:

```json theme={null}
{
  "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:

```html theme={null}
<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:

<CodeGroup>
  ```bash cURL highlight={5} theme={null}
  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={"blocks":{"table":{"format":"markdown"}}}'
  ```

  ```python Python highlight={9} theme={null}
  from pathlib import Path
  from landingai_ade import LandingAIADE

  client = LandingAIADE()

  response = client.v2.parse(
      document=Path("calibration-report.pdf"),
      model="dpt-3-pro-latest",
      options={"blocks": {"table": {"format": "markdown"}}},
  )
  print(response.markdown)
  ```

  ```typescript TypeScript highlight={9} theme={null}
  import fs from "fs";
  import LandingAIADE from "landingai-ade";

  const client = new LandingAIADE();

  const response = await client.v2.parse({
    document: fs.createReadStream("calibration-report.pdf"),
    model: "dpt-3-pro-latest",
    options: { blocks: { table: { format: "markdown" } } },
  });
  console.log(response.markdown);
  ```
</CodeGroup>

The `markdown` field returns the same table using pipe syntax, with the merged header flattened into empty cells:

```markdown theme={null}
| 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.

<CodeGroup>
  ```bash cURL highlight={5} theme={null}
  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={"blocks":{"figure":{"markdown":false}}}'
  ```

  ```python Python highlight={9} theme={null}
  from pathlib import Path
  from landingai_ade import LandingAIADE

  client = LandingAIADE()

  response = client.v2.parse(
      document=Path("calibration-report.pdf"),
      model="dpt-3-pro-latest",
      options={"blocks": {"figure": {"markdown": False}}},
  )
  print(response.markdown)
  ```

  ```typescript TypeScript highlight={9} theme={null}
  import fs from "fs";
  import LandingAIADE from "landingai-ade";

  const client = new LandingAIADE();

  const response = await client.v2.parse({
    document: fs.createReadStream("calibration-report.pdf"),
    model: "dpt-3-pro-latest",
    options: { blocks: { figure: { markdown: false } } },
  });
  console.log(response.markdown);
  ```
</CodeGroup>

The `markdown` field shows each figure as a header line instead of its content:

```markdown theme={null}
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 line-level coordinates.

<CodeGroup>
  ```bash cURL highlight={5} theme={null}
  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={"atomic_grounding":false}'
  ```

  ```python Python highlight={9} theme={null}
  from pathlib import Path
  from landingai_ade import LandingAIADE

  client = LandingAIADE()

  response = client.v2.parse(
      document=Path("calibration-report.pdf"),
      model="dpt-3-pro-latest",
      options={"atomic_grounding": False},
  )
  print(response.markdown)
  ```

  ```typescript TypeScript highlight={9} theme={null}
  import fs from "fs";
  import LandingAIADE from "landingai-ade";

  const client = new LandingAIADE();

  const response = await client.v2.parse({
    document: fs.createReadStream("calibration-report.pdf"),
    model: "dpt-3-pro-latest",
    options: { atomic_grounding: false },
  });
  console.log(response.markdown);
  ```
</CodeGroup>

Each block returns only its block-level grounding; the `atomic_grounding` field is omitted entirely:

```json theme={null}
{
  "type": "text",
  "id": "text-8",
  "grounding": {
    "page": 1,
    "range": { "start": 720, "end": 1169 },
    "box": { "xmin": 0.09019608, "ymin": 0.36545455, "xmax": 0.92810458, "ymax": 0.45272727 }
  }
}
```

#### 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`.

<CodeGroup>
  ```bash cURL highlight={5} theme={null}
  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={"inline_markdown":true}'
  ```

  ```python Python highlight={9} theme={null}
  from pathlib import Path
  from landingai_ade import LandingAIADE

  client = LandingAIADE()

  response = client.v2.parse(
      document=Path("calibration-report.pdf"),
      model="dpt-3-pro-latest",
      options={"inline_markdown": True},
  )
  print(response.markdown)
  ```

  ```typescript TypeScript highlight={9} theme={null}
  import fs from "fs";
  import LandingAIADE from "landingai-ade";

  const client = new LandingAIADE();

  const response = await client.v2.parse({
    document: fs.createReadStream("calibration-report.pdf"),
    model: "dpt-3-pro-latest",
    options: { inline_markdown: true },
  });
  console.log(response.markdown);
  ```
</CodeGroup>

Every structure node (document, page, block, and table cell) carries its `markdown` slice. Entries in `atomic_grounding` do not; to get per-line text, slice by the entry's `range` or read the parent block's `markdown`:

```json theme={null}
{
  "type": "text",
  "id": "text-0",
  "grounding": {
    "page": 1,
    "range": { "start": 0, "end": 27 },
    "box": { "xmin": 0.08006536, "ymin": 0.02050505, "xmax": 0.74019608, "ymax": 0.05964646 }
  },
  "markdown": "**Report No.** TVL-CAL-7731"
}
```