Skip to main content
The Parse Gen2 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.

​
Confirm Your Input Formats

Parse Gen2 accepts PDFs, images, and Office text documents and presentations (DOCX, PPTX, ODT, RTF). Office files are converted to PDF before parsing. If your pipeline depends on spreadsheets (XLSX, CSV) or legacy binary Office files (DOC, PPT), keep those workflows on Parse Gen1. See Supported File Types. Parse Gen2 also does not support password-protected files. Decrypt the file and submit an unencrypted copy, or keep those workflows on Parse Gen1.

​
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 Extract Gen1 and Section APIs consume the Gen1 parse shape. With the Parse Gen2 API, use the Extract Gen2 API instead, which works directly on the Gen2 Markdown output. Section has no Gen2 equivalent; keep Section workflows on the Parse Gen1 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.

​
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.
  • 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.
  • 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.

​
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.
  • 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 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 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
  • 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 (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, 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 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 API. If it used Section, keep that workflow on the Parse Gen1 API.