The version in the path groups endpoints, but each endpoint declares its own stability. Check the stability of the endpoints you call, not the version number.
Versions#↑
| Prefix | What it is |
|---|---|
/v0 |
Internal endpoints that expose internal state. No promise of any kind. |
/v1 |
The first public API. Stability varies per endpoint. |
/v2 |
The newer API, in beta. |
A version can hold endpoints of more than one stability. For example, /v1 has stable, beta, internal and deprecated endpoints side by side.
Stability levels#↑
| Stability | What you can expect |
|---|---|
stable |
Every change is checked against the published spec. A breaking change is refused unless it is explicitly signed off. |
deprecated |
Same protection as stable. A replacement exists; move to it. |
beta |
No stability guarantee. Fields, parameters and behaviour can change in incompatible ways. |
internal |
Built for our own tooling. Can change at any time, without notice or a deprecation window. |
On every level, a new value in a response enum is not treated as a breaking change. Handle values you don't recognise instead of failing on them.
Where to see it#↑
- In the API reference, each operation summary starts with its stability, for example
(stable). - Responses from versioned endpoints carry
X-API-Version(such asv1) andX-API-Stability(such asstable). See response headers.
Deprecation#↑
A deprecated endpoint has stability deprecated, says so in its summary, and its description names the replacement. Related series, for example, points to relationships.
A deprecated field is marked deprecated: true in the spec, and its description says what to use instead.
Where changes are announced#↑
The API changelog lists every change to the spec by date, grouped by operation. Each change is labelled Breaking, Warning or Info.
Subscribe to the RSS feed to get new entries as they land.