/v2/ prefix) is deprecated as of July 3, 2026 and stops serving traffic on October 3, 2026. The v3 API (/v3/ prefix) is live and covers the full document-extraction surface. This page maps every v2 endpoint to its v3 successor.
For the semantic changes behind the new paths — keyset pagination, flat run reads, persistent_id round-tripping, idempotency keys — see the v3 migration guide.
Migration window
| Milestone | Date | Signal |
|---|---|---|
| Deprecation announced | July 3, 2026 | Deprecation: Fri, 03 Jul 2026 00:00:00 GMT on every /v2/ response |
| Sunset | October 3, 2026 | Sunset: Sat, 03 Oct 2026 00:00:00 GMT on every /v2/ response |
/v2/ continues to work unchanged. No request or response shape changes — only the deprecation headers were added.
Follow the headers
Every/v2/ response now carries the deprecation signals, and — where a direct v3 equivalent exists — a Link header pointing at it:
</v3/runs/{run_id}/>. Resolve the variable from the v3 response that produced it (a run id comes from triggering a run) rather than following the template verbatim.
Endpoint mapping
Workflows
| v2 | v3 successor | Notes | |POST /v2/workflows/ | POST /v3/workflows/ | Same shape |
| GET /v2/workflows/ | GET /v3/workflows/ | Same shape |
| GET /v2/workflows/{id}/ | GET /v3/workflows/{id}/ | Same shape |
| PUT /v2/workflows/{id}/ | PATCH /v3/workflows/{id}/ | Verb change — v3 updates are partial |
| DELETE /v2/workflows/{id}/ | DELETE /v3/workflows/{id}/ | Same shape |
| GET /v2/workflows/{id}/definition/ | GET /v3/workflows/{id}/ | Definition is embedded in the v3 workflow detail |
Uploading and running
In v3, uploaded files are grouped into a document packet (the successor of the v2 file collection — same entity, same id), and each execution is a first-class run. | v2 | v3 successor | Notes | |POST /v2/workflows/{id}/upload/ | POST /v3/workflows/{id}/upload/ | Returns a document_packet_id |
| POST /v2/workflows/{id}/files/ | POST /v3/workflows/{id}/upload/ | Multi-file upload folds into the packet upload |
| POST /v2/workflows/{id}/files/from-url/ | POST /v3/workflows/{id}/upload/from-url/ | Same HTTPS-URL ingestion |
| POST /v2/workflows/{id}/run/ | POST /v3/workflows/{id}/upload/run/ | Same one-call upload-and-run; returns a run_id |
| POST /v2/workflows/{id}/files/{file_id}/run/ | POST /v3/document-packets/{document_packet_id}/run/ | Runs are triggered on the packet, not the file — use the packet id from the upload response |
Results and status
| v2 | v3 successor | Notes | |GET /v2/workflows/{id}/files/ | GET /v3/workflows/{id}/document-packets/ | Lists packets instead of file collections |
| GET /v2/workflows/{id}/files/{collection_id}/results/ | GET /v3/runs/{run_id}/ | Results hang off the run, not the collection — poll the run_id returned when you triggered the run |
| GET /v2/workflows/{id}/runs/ | GET /v3/workflows/{id}/runs/ | Same shape |
| DELETE /v2/files/{collection_id}/ | DELETE /v3/document-packets/{id}/ | Same entity, same id |
Endpoints without a v3 successor
These keep working until sunset and emitDeprecation/Sunset but no Link header:
- Webhooks (
/v2/webhooks/…) — a v3 webhook surface has not shipped yet; keep using v2 for now. - Operations (
/v2/operations/parse…) — the standalone parse operation has no v3 equivalent yet; a parse-only workflow covers the same need. - Suggestions (
/v2/organizations/{org_id}/suggestions/…) — internal webapp endpoints, not part of the public surface.
Versioning signals reference
The header semantics (X-API-Version, Deprecation, Sunset, Link: rel="successor-version") and recommended alerting setup are documented in Versioning & deprecation.