Skip to main content
The Parse v2 API is a redesign, not a version bump. The request you send changes very little, but the response is a new shape built around . 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.

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

​
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 and ADE Section APIs consume the v1 parse shape. With the Parse v2 API, use the Extract v2 API 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.

​
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. 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 , there is no separate grounding map: every node in structure carries its own self-contained grounding object with three fields. See Grounding.
  • page numbers are 1-indexed. The Parse v1 API used 0-indexed page numbers. In , 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.
  • 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: ...::>). 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 v2 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 v1 API duplicated Markdown onto every chunk and split. 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 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.