Versioning
All routes live under/api/v1/.... We never break a v1 endpoint; breaking changes ship as /api/v2/... alongside the existing version.
What counts as a breaking change
- Removing a field from a response.
- Changing a field’s type.
- Adding a required request field.
- Tightening a validation rule (e.g. shorter max length).
- Changing the semantics of an existing field.
What’s additive (safe)
- Adding new endpoints.
- Adding new optional request fields.
- Adding new fields to a response.
- Adding new enum values only if the field is one the client is documented to ignore-on-unknown (rare; we instead bump the version).
Deprecation
When we plan to retire an endpoint:- We add a
SunsetandDeprecationHTTP response header for at least 90 days before removal. - The endpoint’s reference page is moved to a
Deprecatedsection in the nav. - The replacement endpoint links back, and the old endpoint links forward.
SDKs vs. raw HTTP
Mobile clients consume our generated TypeScript SDK; the SDK pins to a specific OpenAPI version. New SDK majors are released only when the API ships a newvN.