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

# API versions

> Pin requests with Flow-Version and handle dated contract changes.

Every path starts with `/v0`: this is API **V0**, the shape before the stable release. `/v1` is kept for that release, version 1.0, after which the shape is frozen. Within V0 the API is versioned by date, and the `Flow-Version` header chooses which version answers a request.

```bash
curl https://api.flow.engineer/v0/conversations \
  -H "Authorization: Bearer $FLOW_MESSAGING_KEY" \
  -H "Flow-Version: 2026-11-01"
```

## Rules

* **The current version is `2026-11-01`**, also with the move to `/v0`.
* **Without the header**, the version pinned to your app when it was created is used (`app.api_version` in `GET /v0/app`).
* **Every answer echoes** the version that served it in `Flow-Version`, and webhook deliveries carry it too.
* **The SDKs send the version they were built for**, so their types always match the answers.
* **Closed lists:** error types, event types and message kinds (`MessageKind`) change only with a new dated version. Within a version you can switch on them exhaustively.
* **Beta:** the API is labelled beta while its shape settles. Breaking changes ship as a new dated version, never inside an existing one.

## Moving from `/v1`

The earlier shape, `POST /v1/conversations/{id}/messages` with `content`, `fallback` and `channel_options`, is replaced by one endpoint per message kind under `/v0` ([Message kinds](https://flow.engineer/docs/unified-messaging-api/concepts/content-types.md)). Every other route moves to `/v0` unchanged. The `flow-messaging-migrate` skill moves a project with your coding agent: `claude plugin marketplace add flow-engineer/sdk`, then `claude plugin install flow-messaging@flow-engineer` ([source](https://github.com/flow-engineer/sdk/tree/main/plugin/skills/flow-messaging-migrate)). Flow Framework users only upgrade the framework.