Migration Guide

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.

​

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 and 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. See 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

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. 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 , 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. Three things changed about the spatial values:

• Coordinates are integer pixels. The Parse v1 API used normalized floats from 0 to 1. 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. 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.
• 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. 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 :

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