API versioning and deprecation policy

Versions

The API major version is part of the URL path: /api/v1/…. The version in the path is what you code against — platform releases (v0.29, v0.30, …) never change the /v1 contract.

The unversioned /api/… routes are the legacy v0 surface: frozen, bugfix-only, and no longer documented for external integrators. New integrations start on /v1.

Compatibility within a major version

Within /v1, the following are non-breaking and can happen in any platform release:

• adding response fields,
• adding endpoints,
• adding optional request parameters,
• adding enum values.

Your client MUST be a tolerant reader: ignore unknown fields and unknown enum values instead of failing on them. This is a contract requirement, not a suggestion.

The following are breaking and only ever happen in a new major version (/v2): removing or renaming fields, changing types or the semantics of existing fields, changing status codes or error type identifiers.

Deprecation

When something in /v1 is deprecated:

• responses of the affected endpoint carry a Deprecation header (RFC 9745) and a Sunset date (RFC 8594) at least 6 months in the future,
• the deprecation is announced in the changelog,
• the endpoint keeps working until the sunset date, and removal itself only happens with the next major version.

Watch for these headers in your HTTP client and treat them as an early warning, not an outage.

Error taxonomy

v1 errors are application/problem+json with a stable type URI. The slug at the end of type (and the code extension member, when present) are part of the contract — switch on them, never on the human-readable detail text, which can be reworded or localized at any time.