Skip to main content
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: 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.