> ## 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 ADE Gen1 to ADE Gen2, including the response changes you need to handle.

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

This guide covers what changed and what to update. For the full response reference, see [Parse API Response](https://docs.landing.ai/dpt3/parse-response.md).

## Confirm Your Input Formats

Parse Gen2 accepts PDFs, images, Office text documents and presentations (DOCX, DOC, PPTX, PPT, ODT, RTF), and spreadsheets (XLSX, XLSM, CSV). Text documents and presentations are converted to PDF before parsing. Parse Gen2 does not accept HTML, XLS, ODS, or ODP files. See [Supported File Types](https://docs.landing.ai/dpt3/file-types.md).

Parse Gen2 parses password-protected PDFs when you pass the password in `options.password`. Decrypt any other password-protected file before uploading it.

## What Changes at a Glance

* **Your request:** mostly the same. A new endpoint, two removed parameters, and one new `options` parameter that now also carries `password`.
* **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 [Extract Gen1](https://docs.landing.ai/ade/ade-extract.md) and [Section](https://docs.landing.ai/ade/ade-section.md) APIs consume the Gen1 parse shape. With the Parse Gen2 API, use the [Extract Gen2](https://docs.landing.ai/dpt3/extract.md) API instead, which works directly on the Gen2 Markdown output. Section has no Gen2 equivalent; keep Section workflows on the Parse Gen1 API.
* **Classify and Split workflows:** unchanged. The [Classify](https://docs.landing.ai/dpt3/classify.md) and [Split](https://docs.landing.ai/dpt3/split.md) APIs work with ADE Gen2 at `/v1/ade/classify` and `/v1/split`. Existing calls to `/v1/ade/split` reach the same Split endpoint. Classify takes the original document, and Split takes the `markdown` returned by the Parse Gen2 API.

## Update Your Request

The request contract is close to the Parse Gen1 API. Update the endpoint and adjust a few parameters. For the full `options` schema, see [Request Options](https://docs.landing.ai/dpt3/parse-input.md#request-options).

| Aspect | Parse Gen1 API (DPT-2) | Parse Gen2 API (DPT-3) |
| - | - | - |
| 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 DPT-3 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`. PDFs only. See [Parse Password-Protected PDFs](https://docs.landing.ai/dpt3/parse-input.md#parse-password-protected-pdfs). |
| 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 Parse Gen1 API called them chunks.

The Parse Gen1 API returns a flat `chunks` array, where each chunk carries its own `markdown` and inline `grounding`. DPT-3 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 Gen1 UUIDs and `{page}-{sequence}` table ids. Block 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 Gen1 API, grounding lived both inline on each chunk and in a top-level `grounding` map keyed by chunk id. In DPT-3, there is no separate grounding map: every node in `structure` carries its own self-contained `grounding` object. See [Grounding](https://docs.landing.ai/dpt3/parse-response.md#grounding-where-things-are).

* **`page` numbers are 1-indexed.** The Parse Gen1 API used 0-indexed page numbers. In DPT-3, 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 Gen1 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 5 decimal places.
* **Fine-grained detail is new.** Leaf blocks add an `atomic_grounding` array: one entry per visual line with DPT-3 Pro, or one per word with DPT-3 Verity. See [Atomic Grounding](https://docs.landing.ai/dpt3/parse-response.md#atomic-grounding).
* **The Gen1 confidence fields are removed.** `confidence` and `low_confidence_spans` have no direct Gen2 equivalent. DPT-3 Verity returns a different signal: a per-word `confidence` on each atomic grounding entry. There is no per-block equivalent of the Gen1 per-chunk score. See [Word Confidence Scores](https://docs.landing.ai/dpt3/parse-response.md#word-confidence-scores-dpt-3-verity).

### Markdown Is Cleaner

The Parse Gen1 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: ...::>`). DPT-3 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](https://docs.landing.ai/dpt3/parse-response.md#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 Gen2](https://docs.landing.ai/dpt3/extract.md) API 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 Gen1 API duplicated Markdown onto every chunk and split. DPT-3 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 Gen1 fields and parameters have no equivalent in ADE Gen2:

* `chunks` and the per-chunk `markdown` (walk `structure` instead; get text through `grounding.range` or `options.inline_markdown`)
* `splits` and the `split` parameter of the Parse API (the [Split API](https://docs.landing.ai/dpt3/split.md) is unaffected)
* `custom_prompts`
* `confidence` and `low_confidence_spans` (DPT-3 Verity adds a different per-word `confidence` on atomic grounding entries)
* 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` and `custom_prompts` parameters. Add `options` if you need page selection or output control.
* For password-protected PDFs, move `password` into `options.password`. Decrypt any other password-protected file before uploading it, because Parse Gen2 accepts a password only for PDFs.
* 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 the Gen1 `confidence` or `low_confidence_spans` fields. To score words with DPT-3 Verity, use the per-word `confidence` instead.
* 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 Extract Gen1 API, move the extraction step to the [Extract Gen2](https://docs.landing.ai/dpt3/extract.md) API. If it used Section, keep that workflow on the Parse Gen1 API.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.