API versioning and deprecation
Learn which REST API changes are backward compatible and how a breaking change is announced at least 6 months ahead with Deprecation and Sunset headers.
The REST API carries its major version in the path: /api/v1. Within a major version, the API changes only in ways that keep existing clients working. A change that could break a client is announced at least 6 months before it takes effect: in the API reference, in the API changelog, and in the headers of every response of the affected operation.
This policy is in effect from 2026-10-18. The changes made before general availability weren't subject to the notice period. They're listed in the API changelog.
Version in the path
https://<api-host>/api/v1<api-host>: the host name of the API.
A new major version is served under its own path, such as /api/v2, alongside v1. v1 stays available, and a breaking change to v1 still needs a notice of at least 6 months.
Backward-compatible changes
These changes can be made in v1 at any time. Build your client so that it keeps working when they happen:
| Change | What your client must do |
|---|---|
| A new operation | Nothing. |
| A new optional query parameter or header | Nothing. Requests without it work as before. |
| A new optional field in a request body | Nothing. |
| A new field in a response | Ignore response fields that you don't know. |
| A new value in an enum of a response | Handle values that you don't know, for example with a default branch. |
| A new response header | Ignore headers that you don't know. |
| Relaxed validation, such as a larger maximum length or a higher limit | Nothing. |
Breaking changes
These changes are never made to an operation without the deprecation process that follows:
- Removing an operation or a path.
- Adding a required parameter or a required request field, or making an optional parameter or field required.
- Changing the type of a field or a parameter.
- Removing a value from an enum of a request, or tightening validation, such as a shorter maximum length, a smaller maximum, fewer items, or a new pattern.
- Removing a response field, or making it optional or nullable.
- Removing a success status code or a media type.
- Requiring a token scope that the operation didn't require before, or removing scopes from a set of which any one is enough.
- Refusing API tokens and service account keys on an operation that accepted them, so that it works only in a console session.
How a breaking change is announced
At least 6 months before a breaking change takes effect:
- The operation is marked deprecated in the API reference and in the OpenAPI document at
https://<api-host>/openapi.json. It hasdeprecated: true,x-deprecation-date, the date of the announcement, andx-sunset, the earliest date on which the operation can stop working. Both dates are in the RFC 3339 format. - An entry in the API changelog describes the change and what to use instead.
- Every response of the operation carries the headers in the following table.
| Header | Value |
|---|---|
Deprecation | The date of the announcement: @ followed by the Unix time in seconds (RFC 9745). |
Sunset | The earliest date on which the operation can stop working, as an HTTP date (RFC 8594). |
Link | The address of the API changelog, with rel="deprecation". |
Deprecation: @1792281600
Sunset: Sun, 18 Apr 2027 00:00:00 GMT
Link: <https://docs.cloud.example/docs/developers/rest-api/changelog/>; rel="deprecation"; type="text/html"In this example, the operation was deprecated on 2026-10-18 and can stop working after 2027-04-18.
The headers are on every response of the operation, error responses such as 401, 403, and 429 included. Log the Deprecation header in your client or raise an alert on it, so that you learn about a deprecation from the responses themselves.
After the sunset date
Until the date in Sunset, a deprecated operation keeps working as documented. After that date, it can be removed or changed. The changelog entry says what to use instead.
How the policy is checked
Every change to the public API contract is compared automatically with the contract that was published before it. A breaking difference stops the change from being released, unless the operation was deprecated and its sunset date has passed.