Versioning and deprecation
Semver, 12-month breaking-change notice, Sunset and Deprecation headers.
Semver
API version is in the URL: /v1. Within v1, additive non-breaking changes ship at any time. Breaking changes require a major-version bump.
Deprecation policy
- Notice period: 12 months from announcement to removal.
- Headers: Deprecated endpoints and fields emit RFC 8594
Deprecationand RFC 8594Sunsetheaders on every response. - Changelog: Every deprecation lands in the changelog on the day it is announced.
Currently deprecated
| What | Deprecated | Sunset |
|---|---|---|
api_key body field (use X-API-Key header) | 2026-04-17 | 2026-07-15 |
SDKs
SDKs follow semver independently from the API. A new SDK minor version never requires a new API version.
What is not breaking
- Adding a new field to a response.
- Adding a new optional field to a request.
- Adding a new enum value.
- Adding a new endpoint.
- Tightening documentation without changing behavior.
What is breaking
- Removing a field.
- Renaming a field.
- Changing a field type.
- Removing an enum value.
- Changing the meaning of an existing response field.