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

## What Changes at a Glance

* **Your request:** mostly the same. A new endpoint, two removed parameters, and one new `options` parameter.
* **Your response:** new. Flat `chunks` become a hierarchical `structure` tree, grounding coordinates change units, and the Markdown for visuals is simpler.
* **Other ADE APIs:** [ADE Extract](/ade/ade-extract) and [ADE Section](/ade/ade-section) expect the v1 response shape. If your workflow chains Parse with either, keep those workflows on the Parse v1 API for now.

## Update Your Request

The request contract is close to the Parse v1 API. Update the endpoint and adjust a few parameters.

| 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)                                                        |
| Page or section splitting | `split` form field           | Removed. Use `options.pages` to select pages to process.                              |
| Figure prompts            | `custom_prompts` form field  | Removed.                                                                              |
| Output customization      | Not functional               | `options`: select pages, set table format, toggle captions, control grounding detail. |

See [Request Options](./parse-input#request-options) for the full `options` schema.

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

<Note>
  The parsed units are called **blocks**. The v1 Parse API called them chunks, and the DPT-3 Preview briefly called them elements. Both terms are retired; blocks is the current name.
</Note>

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.

Blocks no longer carry their own Markdown or coordinates. Instead, each block has a `span` (a `[start, end)` range into the top-level `markdown` string) and an `id` that matches its node in the top-level `grounding` tree.

### Grounding Moved and Changed

In the Parse v1 API, grounding lived both inline on each chunk and in a top-level `grounding` map. In {dpt3}, grounding lives only in the top-level `grounding` field, a second tree that mirrors `structure` (`document → page → block → table cell`). Each block's grounding node repeats its `id` and `span` and adds the spatial data. Walk the two trees together, or index the grounding nodes by `id` for direct lookup; see [Grounding](./parse-response#grounding-where-things-are). Three things changed about the spatial values:

* **Coordinates are integer pixels.** The Parse v1 API used normalized floats from 0 to 1. {dpt3} uses integer pixels, as `[left, top, right, bottom]`. For PDFs, the pixel resolution is set by the `dpi` option (default 200); for images, coordinates are pixels relative to the original upload. To draw or compare boxes, read the page's `width` and `height` from `structure` rather than assuming a 0-to-1 range.
* **Line-level detail through `parts`.** Each block's grounding node adds a `parts` array. For `text` and `marginalia`, there is one part per visual line, so you can highlight or extract at the line level. Visual block types return one part per transcribed line; `table` and `table_cell` return an empty `parts` array.
* **No confidence score.** The v1 `confidence` and `low_confidence_spans` fields are removed.

### Markdown Is Cleaner

The Parse v1 API wrapped visual blocks in non-standard tags (for example, `<::logo: ...::>`) and embedded long generated descriptions. {dpt3} uses standard Markdown:

* **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 such as `[SIGNED]`. See [Figure and Attestation Labels](./parse-response#figure-and-attestation-labels).
* **Page breaks are explicit.** A `<!-- PAGE BREAK -->` comment separates each page's content (absent in single-page documents).
* **Tables are standardized.** Tables use HTML by default (set `options.blocks.table.format="markdown"` for pipe syntax).

### Spans Are the New Link Between Outputs

The Parse v1 API duplicated Markdown onto every chunk. {dpt3} returns the Markdown once, as the top-level `markdown` string, and every block points into it with a `span` of Unicode code point offsets `[start, end)`. To get a block's text, slice the Markdown string with its `span`. This is the main mental shift: structure and grounding describe positions in one shared Markdown document rather than carrying their own copies of the text.

## What Was Removed

These v1 fields and parameters have no equivalent in {dpt3}:

* `chunks` and the per-chunk `markdown` (use `structure` and `span` slices instead)
* `splits` and the `split` parameter
* `custom_prompts`
* `confidence` and `low_confidence_spans`
* Normalized 0-to-1 coordinates
* Inline per-chunk `grounding`

## Migration Checklist

* Point requests at `POST /v2/parse`.
* Remove the `split` and `custom_prompts` parameters; add `options` if you need page selection or output control.
* Stop reading `chunks`. Walk `structure.children` (pages) and their `children` (blocks) instead.
* Read each block's location from the top-level `grounding` tree, which mirrors `structure`: walk the two trees together, or index the grounding nodes by `id`.
* Rescale bounding boxes: switch from normalized floats to integer pixels, using the page's `width` and `height`.
* Slice the top-level `markdown` with each block's `span` to recover its text.
* 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.