Versioning & Deprecation Policy
This page states what we change without notice, and what we announce before changing. Please read it before you build against the API — it is what keeps your integration working.
How versions are expressed
The major version is part of the URL path (currently /v1).
| Kind of change | How we handle it | Examples |
|---|---|---|
| Backward-compatible additions | Shipped to the current version without notice | New endpoints / new response fields / new enum values / new error codes |
| Breaking changes | Released as a new major version (/v2) | Removing or renaming a field, changing a type, changing default behaviour |
When a new major version is released, the previous one stays available for at least 6 months.
What your client must do (important)
Because backward-compatible additions ship without notice, please build your client so that:
- Unknown fields are ignored. A new key in a response must not cause a failure.
- Unknown enum values are accepted. Values such as
statuswill grow over time. Clients that validate enums strictly and throw — the default in many generated SDKs — break the moment a single value is added. Keep the received value as-is and treat unknown ones as "other". - Unknown error codes are handled. Branch primarily on the HTTP status, and only secondarily
on
error.code. - Array order is not relied upon. Unless a response explicitly documents an order, none is guaranteed.
How deprecation works
When we retire an endpoint or a field, we follow this sequence.
How we announce
| Channel | What it carries |
|---|---|
| Registered email address | We notify the address registered with your client |
| Developer console notice | Shown at the top of the console after you sign in |
Deprecation response header | Present on responses from a deprecated path (RFC 9745) |
Sunset response header | States when the path stops being served (RFC 8594) |
Grace periods
We allow at least 6 months from announcement to removal — the same for an entire major version (/v1 → /v2) as for an individual endpoint or field.
| Scope | Minimum time from announcement to removal |
|---|---|
An entire major version (/v1 → /v2) | 6 months |
| An individual endpoint or field | 6 months |
Urgent security fixes are the exception. Even then, we announce as soon as the issue is known.
Current status
/v1 is available. Nothing is currently scheduled for deprecation.