Versioning & Deprecation

The API uses path-based major versioning. This page is the compatibility contract: what we guarantee won't change within a major version, what counts as a breaking change, and how deprecations are announced and timed.

Versioning Model

The major version lives in the path (/api/2.0). A new major version (e.g. /api/3.0) is introduced only for changes that cannot be made additively. Everything else ships within 2.x. (Note: the API is served at /api/2.0; this documentation lives at /api-docs/v2/, same version, different host path.)

Stability & the 2.0 Line

API v2 is declared stable from 1 January 2027. From that date the contract below is enforced and breaking changes follow the deprecation cycle. Before that date the surface may still be refined as it settles.

The Compatibility Contract

Within a major version, these will not change: the success/data/meta response envelope, existing field names and types, existing error code values, the authentication scheme, and scope semantics.

Non-breaking changes ship at any time (announced in the changelog, no version bump): new endpoints, new optional request parameters, new response fields, new enum values, and new error codes.

Breaking changes require a deprecation cycle (or a new major version): removing or renaming a field or endpoint, changing a type, making an optional field required, or removing an enum value or error code.

Build Forward-Compatible Clients.
Tolerate unknown response fields and unknown enum values, and don't hard-fail on error codes you don't recognise (branch on the HTTP status). Clients that follow this rule are unaffected by non-breaking changes.

Deprecation Lifecycle

A capability moves through three states: Active → Deprecated → Removed (sunset). When something is deprecated it keeps working and is flagged in three places: an entry in the changelog, deprecated: true on the affected operation in the OpenAPI document, and Deprecation / Sunset response headers (with a Link to the migration note) on the affected endpoint.

Notice Periods

Endpoint or field: at least 6 months between the deprecation announcement and removal.
A whole major version (e.g. retiring 2.0 once 3.0 exists): at least 12 months, with the sunset date stated in the changelog when the successor ships.

Breaking changes and sunsets are also emailed to the businesses that own affected API keys: once when announced and again ahead of the sunset date. Additive changes are changelog-only.

Where Changes Are Announced

Channel	Covers
Changelog	Every change (the canonical record).
OpenAPI `deprecated` + `Deprecation`/`Sunset` headers	Machine-detectable deprecations.
In-app notice (Business → Settings → API)	Deprecations affecting your key.
Email to key owners	Breaking changes and sunsets only.