Versioning and deprecation
AI moves quickly, and the platform behind this API keeps pace. That only benefits you if the API itself stays stable, so the two are deliberately separated: new capability arrives as it becomes available, while the endpoints you already call keep behaving as they did the day you wrote against them.
In practice, almost everything we ship is additive: it appears, and nothing you depend on changes underneath you. Anything that could break a working client is announced first, dated, and carried on headers your code can read.
The version is in the URL:
Code
Summary
- Additive changes ship whenever they are ready, without notice. In practice that means capability appearing rather than existing behavior changing.
- Anything that could break a working client is announced first, on a schedule your code can read off the response headers.
- Minimum notice is 90 days for a stable endpoint, 30 days for beta, and none for
preview. Retiring
/api/v1altogether would carry 12 months.
What ships without notice
The following are all additive. They ship continuously and are not announced:
- New endpoints and new resources
- New fields in responses
- New optional request fields, query parameters and headers
- New values in an enum a request may send
- New error
codevalues on a failure path that could already fail - New response headers
- Relaxed validation, so a request that used to fail now succeeds
- Anything under the hood: performance, infrastructure, model routing
Five habits that keep a client compatible
Nearly every integration that breaks on an additive change breaks for one of these reasons. All five are cheap to get right now and difficult to retrofit later:
- Ignore fields you do not recognize. A response gaining a field is routine. A
client that rejects unknown fields (a strict parser, or a schema with
additionalProperties: false) will break on a change we ship as a matter of course. - Handle enum values you have not seen. Fall back to a default rather than throwing. We will not add a value to an existing response field within a version, but new endpoints and new fields carry values your code has not encountered.
- Branch on
code, never on prose.title,detailand validationmsgkeys are written for people, and they are rewritten for people. See errors. - Read limits from
RateLimit-Policyrather than hard-coding the numbers in the rate limits table. - Do not depend on ordering you did not request. That covers JSON key order and
the order of a collection fetched without a
sort.
Not part of the contract
The reference is the boundary. Anything not in it is unpublished and can change or disappear on any deploy:
- Endpoints outside
/api/v1 - Fields you can observe in a response but that no operation's schema declares
- Prose:
title,detail, and translation keys - The order of a collection returned without an explicit
sort - Rate limit quotas, which are tuned as traffic changes and published in a header for that reason
- The
errorIdformat, response header order, and latency - Beta and preview endpoints, described below
Stability levels
Most of the surface is stable. The other two levels exist so a new capability can reach you while it is still changing, rather than being withheld until it is finished:
| Level | Marked in the reference | If it has to change |
|---|---|---|
| Stable | nothing (the default) | Announced, with a Sunset date at least 90 days out |
| Beta | beta | Announced, at least 30 days |
| Preview | preview | May change or be withdrawn at any time |
No marker means stable, and everything on this page applies to it. Preview is for evaluation rather than for a production path you cannot change quickly.
What counts as a breaking change
On a stable endpoint, none of the following happen without going through the deprecation process below:
- Removing an endpoint, or changing its method or path
- Removing a field from a response, or changing its type
- Adding a required request field, or making an optional one required
- Removing a value from an enum a response can return
- Removing an error
code, or reusing one to mean something else - Tightening validation so a request that worked now fails
- Changing the success status an endpoint answers with
- Narrowing the permission or the plan an endpoint requires
The deprecation process
-
It is marked in the reference. The operation is labeled deprecated and the entry names its replacement.
-
We announce it, with the replacement and the removal date, to the contacts we have for affected integrations.
-
Every response says so. The endpoint returns
DeprecationandSunsetheaders (RFC 9745, RFC 8594) on every call, so a client can pick it up without anyone reading an email:CodeDeprecationis when it was deprecated,Sunsetis when it stops answering, and theLinkpoints at the replacement. -
It keeps working until the
Sunsetdate, at least 90 days from the announcement for a stable endpoint and 30 for a beta one. -
After that it answers
410 resource_gone, not404, so you can tell "removed on purpose" from "wrong URL".
Log those two headers wherever you log responses. They are the earliest warning available, they arrive on every call, and they do not depend on an email reaching the right person at your end.
The notice period is measured against your integration. Announcements go to the integrations a change affects, so what you are promised is about the operations you call: if one of them has to change, you get the full period for it. We do not hold an endpoint still on behalf of callers who are not there.
An endpoint enters the guarantee the first time you call it. There is no separate list of protected operations, and nothing you build on is provisional because of how anyone else happens to use it.
The notice periods are minimums rather than targets. A deprecation usually runs longer,
and the Sunset header on the endpoint is always the authoritative date.
Shortened notice periods
Four circumstances can shorten or remove a notice period:
- A security vulnerability that cannot be fixed compatibly
- A legal or regulatory obligation
- An endpoint returning incorrect data, where continuing to serve it is worse than withdrawing it
- Abuse
In those cases we make the change as soon as necessary and notify you as soon as we can. This exception is for emergencies rather than for convenience, and we treat it that way.
A future /api/v2
/api/v1 is not being retired. A second version would appear only if something had to
break for everyone at once, and the separation described above means most changes never
require that. If a second version does appear:
/api/v2appears alongside/api/v1rather than in place of it. Both stay in the reference, behind a version selector./api/v1keeps working for at least 12 months after/api/v2is stable, withSunsetheaders tracking the countdown.- You migrate endpoint by endpoint. There is no cutover date.