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

# Migration Guide

> Migrate from the Parse v1 API to DPT-3, including the response changes you need to handle.

export const dpt3 = 'DPT-3';

export const dpt2 = 'DPT-2';

export const parseDpt3 = 'Parse';

export const parse = 'ADE Parse';

export const ade = 'Agentic Document Extraction';

The [Parse v2 API](https://docs.landing.ai/api-reference/parse/ade-parse) is a redesign, not a version bump. The request you send changes very little, but the response is a new shape built around {dpt3}. Plan to rewrite the code that reads the parse response; there is no field-for-field mapping from the Parse v1 API.

This guide covers what changed and what to update. For the full response reference, see [Parse API Response](./parse-response).

## Confirm Your Input Formats

The Parse v2 API accepts PDFs and images only. If your pipeline depends on Office formats supported by the Parse v1 API (Word, PowerPoint, spreadsheets), keep those workflows on the Parse v1 API. See [Supported File Types](./file-types).

The Parse v2 API also does not support password-protected files. Decrypt the file and submit an unencrypted copy, or keep those workflows on the [Parse v1 API](/ade/ade-parse-password).

## What Changes at a Glance

* **Your request:** mostly the same. A new endpoint, three removed parameters, and one new `options` parameter.
* **Your response:** new. Flat `chunks` become a hierarchical `structure` tree in which every block carries its own grounding, and the Markdown is cleaner.
* **Extraction workflows:** the v1 [ADE Extract](/ade/ade-extract) and [ADE Section](/ade/ade-section) APIs consume the v1 parse shape. With the Parse v2 API, use the [Extract v2 API](./extract) instead, which works directly on the v2 Markdown output.

## Update Your Request

The request contract is close to the Parse v1 API. Update the endpoint and adjust a few parameters. For the full `options` schema, see [Request Options](./parse-input#request-options).

| Aspect                    | Parse v1 API ({dpt2})        | Parse v2 API ({dpt3})                                                                                                                                  |
| ------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Endpoint                  | `POST /v1/ade/parse`         | `POST /v2/parse`                                                                                                                                       |
| Authentication            | Bearer API key               | Bearer API key (unchanged)                                                                                                                             |
| File input                | `document` or `document_url` | `document` or `document_url` (unchanged)                                                                                                               |
| Model selection           | `model` form field           | `model` form field (unchanged); use a {dpt3} snapshot such as `dpt-3-pro-latest`                                                                       |
| Page or section splitting | `split` form field           | Removed. Use `options.pages` to select pages to process (1-indexed).                                                                                   |
| Figure prompts            | `custom_prompts` form field  | Removed.                                                                                                                                               |
| Password-protected PDFs   | `password` form field        | Moved to `options.password`, but password-protected files are not supported: providing a password returns HTTP 422. Decrypt the file before uploading. |
| Output customization      | Not available                | `options`: select pages, set the table format, suppress block types from the Markdown, control grounding detail, and inline each block's Markdown.     |

## Rework Your Response Handling

This is where the work is. The top-level response fields are different, and the concepts behind them changed.

### Chunks Are Now Blocks

Parsed units are now called **blocks**. The v1 Parse API called them chunks.

The Parse v1 API returns a flat `chunks` array, where each chunk carries its own `markdown` and inline `grounding`. {dpt3} replaces this with a hierarchical `structure` tree: a `document` whose `children` are pages, and each page's `children` are the blocks on that page. Tables nest their cells (`table_cell`) as children.

Block ids are semantic: `<type>-<index>`, with a per-type counter in reading order (`text-0`, `figure-0`, `table_cell-3`). They replace the v1 UUIDs and `{page}-{sequence}` table ids. Ids are stable within a response but not across re-parses of the same document.

### Grounding Is Inline, and the Values Changed

In the Parse v1 API, grounding lived both inline on each chunk and in a top-level `grounding` map keyed by chunk id. In {dpt3}, there is no separate grounding map: every node in `structure` carries its own self-contained `grounding` object with three fields. See [Grounding](./parse-response#grounding-where-things-are).

* **`page` numbers are 1-indexed.** The Parse v1 API used 0-indexed page numbers. In {dpt3}, page 1 is the document's first page, everywhere: in each node's `grounding.page`, in `metadata.failed_pages`, and in the `options.pages` request selector. Table `row` and `col` positions stay 0-indexed.
* **`range` locates the block in the Markdown.** Each grounding carries `{"start": n, "end": n}` offsets into the top-level `markdown` string, in Unicode code points (`start` inclusive, `end` exclusive). The v1 response had no equivalent; each chunk carried its own Markdown copy instead.
* **`box` keys are renamed.** Coordinates are still normalized fractions of the page, from 0 to 1, but the keys change from `left`, `top`, `right`, `bottom` to `xmin`, `ymin`, `xmax`, `ymax`, with at most 8 decimal places.
* **Line-level detail is new.** Leaf blocks add an `atomic_grounding` array with one entry per visual line, so you can highlight or extract at the line level. See [Atomic Grounding](./parse-response#atomic-grounding).
* **No confidence score.** The v1 `confidence` and `low_confidence_spans` fields are removed.

### Markdown Is Cleaner

The Parse v1 API embedded `<a id='...'></a>` anchors and id attributes in the Markdown to link it to chunks, and wrapped visual chunks in non-standard tags (for example, `<::logo: ...::>`). {dpt3} returns clean Markdown with no embedded ids:

* **Blocks link to the Markdown through ranges,** not anchors. Slice the `markdown` string with a block's `grounding.range` to get its text.
* **Visual blocks are structured and labeled.** Figures render as HTML-style `<figure type="CHART">...</figure>` elements containing transcribed text and generated `<description>` blocks. Logos, scan codes, and attestations render as transcribed text with short bracketed labels; an attestation can carry more than one, such as `[STAMPED][SIGNED]`. See [Attestations](./parse-response#attestations).
* **Page breaks are explicit.** A `<!-- PAGE BREAK -->` comment separates each page's content (absent in single-page documents).
* **The output ends with a document ID.** The final line is `<!-- doc_id=<job_id> -->`, which the [Extract v2 API](./extract) reads to link an extraction back to its parse job.
* **Tables are standardized.** Tables use HTML by default (set `options.blocks.table.format="markdown"` for pipe syntax).

### One Markdown String Instead of Copies

The Parse v1 API duplicated Markdown onto every chunk and split. {dpt3} returns the Markdown once, as the top-level `markdown` string, and every block points into it with its `grounding.range`. To get a block's text, slice the Markdown string with the range, or set [`options.inline_markdown`](./parse-input#request-options) to `true` to have every block carry its own `markdown` slice again.

## What Was Removed

These v1 fields and parameters have no equivalent in ADE v2:

* `chunks` and the per-chunk `markdown` (walk `structure` instead; get text through `grounding.range` or `options.inline_markdown`)
* `splits` and the `split` parameter
* `custom_prompts`
* `password` as a top-level field (it moved to `options.password`, but password-protected files are not supported and providing it returns HTTP 422)
* `confidence` and `low_confidence_spans`
* The top-level `grounding` map (grounding is inline on each node)
* Embedded `<a id>` anchors and id attributes in the Markdown

## Migration Checklist

* Point requests at `POST /v2/parse`.
* Remove the `split`, `custom_prompts`, and `password` parameters; add `options` if you need page selection or output control.
* Stop reading `chunks`. Walk `structure.children` (pages) and their `children` (blocks) instead, or flatten the tree into a map by block `id`.
* Read each block's location from its inline `grounding` object: `page`, `range`, and `box`.
* Shift page-number logic from 0-indexed to 1-indexed, including any `options.pages` values you send.
* Rename box keys: `left`, `top`, `right`, `bottom` become `xmin`, `ymin`, `xmax`, `ymax` (still normalized 0 to 1).
* Get a block's text by slicing the top-level `markdown` with its `grounding.range`, or set `options.inline_markdown` to `true`.
* Remove any logic that depends on `confidence` or `low_confidence_spans`.
* Update visual-block handling for the structured formats (`<figure type="...">` elements and bracketed labels such as `[SIGNED]`) instead of `<:: ... ::>` tags, and remove any code that parses `<a id>` anchors out of the Markdown.
* If your workflow chained Parse with the v1 ADE Extract or Section APIs, move the extraction step to the [Extract v2 API](./extract).