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

# Versioning and deprecation

> Published stability guarantees for the Flow9 public API, MCP server, and webhooks, so integrators can build with confidence.

Published stability guarantees for the Flow9 public API, MCP server, and webhooks, so
integrators can build with confidence.

## Versioning

* The API is versioned in the **path**: `/v1/...`. The MCP server advertises its
  protocol version in `initialize`.
* **`v1` is stable.** Within `v1` we only make **additive, backward-compatible**
  changes.

## What is a backward-compatible (allowed within v1) change

* Adding a new endpoint, or a new **optional** request field.
* Adding a new field to a response object.
* Adding a new enum value **only** where the consumer is documented to tolerate unknown
  values (otherwise it's breaking).
* Adding a new optional response header.
* Loosening a validation rule; making a required field optional.

Consumers **must** ignore unknown response fields and tolerate additional headers — do
not hard-code an exhaustive field set.

## What is a breaking change (requires a new major version)

* Removing or renaming an endpoint, field, or enum value.
* Making an optional request field required, or tightening validation.
* Changing a field's type or a default.
* Changing authentication, scopes, or error `code` semantics.

Breaking changes ship under a new path version (e.g. `/v2`); `v1` continues per the
deprecation window below.

## Deprecation window

* A deprecated endpoint keeps working for **at least 12 months** from the day it is
  marked deprecated (the **Sunset** date).
* During that window, responses carry:
  * **`Deprecation:`** — HTTP-date it became deprecated.
  * **`Sunset:`** — HTTP-date it stops responding (≥ 12 months after `Deprecation`).
  * **`Link: <url>; rel="deprecation"`** — the migration guide.
* Deprecations are announced in the changelog and to registered integrators before the
  headers appear.

The mechanism is `deprecationHeaders()` in
`supabase/functions/_shared/deprecation.ts` — a deprecated route spreads its headers
onto the response.

**Currently deprecated:**

| What                                    | Since      | Sunset     | Migrate to                                                                         |
| --------------------------------------- | ---------- | ---------- | ---------------------------------------------------------------------------------- |
| `offset` paging on `GET /v1/activities` | 2026-09-04 | 2027-10-01 | `cursor` / `next_cursor` — [conventions.md](/api-reference/conventions#pagination) |

The headers appear only on responses to requests that actually use the deprecated
form (an `offset` parameter), so a caller already on cursors is never warned.

## Status page (managed service — ops)

A public **status page** (managed, e.g. the Better Stack page from the health
work) exposes three components — **REST API**, **MCP server**, **Webhooks** — with
uptime + incident history. Incidents and maintenance windows are posted there. This is
an operational setup, coordinated with the system-health monitoring, not application
code.

## MCP & webhooks

* **MCP** follows the same additive rule; tool removals/renames are breaking and follow
  the window. Protocol-version negotiation is handled in `initialize`.
* **Webhooks**: event **payloads** follow the additive rule (consumers ignore unknown
  fields); the signature scheme and header names are covered by this policy.