Versioning and deprecation

Everything is under /v1. Within a version, changes are additive only: new endpoints, new optional fields, new enum values and new event types. Your client must ignore fields, enum values and event types it does not know; a new one can arrive in any release.

Breaking changes

Removing or renaming a field or an endpoint, changing a type or a meaning, or making something required is a breaking change. Breaking changes go to a new major version, /v2, and /v1 keeps running beside it.

Notice

At least 6 months pass between announcing a deprecation and switching anything off. Production customers get an email and a note on the changelog.

Deprecation headers

A deprecated endpoint, or an endpoint answering with a deprecated field, says so on every answer: Deprecation (RFC 9745) with the date it was deprecated, Sunset (RFC 8594) with the date it stops, and a Link to its changelog entry. Watch for them in your logs. Nothing is deprecated today.

HTTP/1.1 200 OK
Deprecation: @1798761600
Sunset: Thu, 01 Jul 2027 00:00:00 GMT
Link: <https://final-frame.com/docs/changelog#2027-01-01-1>; rel="deprecation"; type="text/html"

The Sandbox

The Sandbox is pre-production and may change faster. A breaking change there gets at least 2 weeks' notice on the changelog.

The OpenAPI document

info.version in the OpenAPI document carries the API version and the date of the build, for example 1.0.0+20261013.v1446: the date, then the release.