Skip to content
Flow Flow

Ask the docs

Answers come only from these docs and are written by an AI model (Gemini), so check the linked pages. Your question is not kept. Do not include personal details or keys.

API versions

Versioning · API versioning · Flow-Version header
▾

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.

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

Rules

Section titled “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

Section titled “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). 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). Flow Framework users only upgrade the framework.