Versioning
How we evolve the API without breaking your integration
The public surface is mounted at /api/... — unversioned in the URL. We
treat backwards compatibility as a contract: changes within a major version
will not break existing clients.
What counts as a breaking change
- Removing or renaming an endpoint, field, or query parameter.
- Changing a field's type (e.g.
string→number). - Tightening validation (a payload that worked yesterday returning
400). - Changing default behaviour of an existing parameter.
What is not a breaking change
- Adding new endpoints.
- Adding new optional fields to requests.
- Adding new fields to responses — always parse responses tolerantly.
- Adding new enum values to existing string fields — always handle unknown values.
- Adding new optional headers.
- Performance, error-message, or rate-limit-window tuning.
Code that does if (status === "pending" || status === "confirmed") { … } else { throw … }
will break when we introduce a new status. Write integrations to gracefully
fall through unknown enum values.
When we do need to break
A breaking change ships under a new version prefix (e.g. /api/v2/...). The
previous version remains available for a deprecation window (minimum 6 months)
with Deprecation and Sunset response headers, and an entry in the
changelog.
Detecting deprecations
HTTP/1.1 200 OK
Deprecation: true
Sunset: Wed, 01 Jan 2027 00:00:00 GMT
Link: </docs/api/changelog>; rel="deprecation"Monitor for the Deprecation header in your logs to surface upgrade work
before the sunset date.