> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anyformat.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# v2 → v3 migration

> The v2 API is deprecated and sunsets on October 3, 2026. Endpoint-by-endpoint mapping to v3.

The v2 API (`/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](/api-reference-v3/migrating-from-v2).

<Warning>
  **Sunset date: October 3, 2026.** After this date, `/v2/` endpoints stop serving traffic. Migrate before then — and wire your integration to [alert on the `Sunset` header](/api-reference/introduction#dont-get-surprised-—-alert-on-sunset) so you never depend on release notes.
</Warning>

## 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      |

During the window, `/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:

```http theme={null}
HTTP/1.1 200 OK
X-API-Version: 2.0.0
Deprecation: Fri, 03 Jul 2026 00:00:00 GMT
Sunset: Sat, 03 Oct 2026 00:00:00 GMT
Link: </v3/workflows/abc123/>; rel="successor-version"
```

When the v3 successor is addressed by an identifier your v2 request doesn't carry, the link is a [URI Template (RFC 6570)](https://datatracker.ietf.org/doc/html/rfc6570) with the unresolved variable left literal — for example `</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 emit `Deprecation`/`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](/api-reference/introduction#versioning--deprecation).