This API has no keys and no accounts, which means there is no mailing list to warn you through. The contract has to be legible from the responses themselves, so everything below is something you can observe by making a request.
What is current
| version | base path | status | since | sunset |
|---|---|---|---|---|
| v1 | /api/v1 | current | 2026-07-01 | none scheduled |
The same table as JSON, for anything that would rather not parse HTML: /developers/versioning.json. Every response under /api/* also carries an API-Version header naming the contract it was produced under.
The rules
- 1
Versions live in the URL path
Every endpoint is served at both /api/* and /api/v1/*. The two are byte-identical today. Pin the versioned prefix and the shape of what you get back cannot move under you.
- 2
Breaking changes get a new prefix
Removing a field, renaming one, changing its type, or changing the meaning of an existing value is breaking, and ships as /api/v2/* rather than as an edit to v1.
- 3
Additive changes land in place
A new endpoint, or a new optional field on an existing response, is not breaking and does not wait for a version bump. Parse defensively and ignore fields you do not recognise.
- 4
A superseded version serves for at least 180 days
From the day a replacement ships, the old prefix keeps working for a minimum of 180 days. The clock starts at announcement, not at your next deploy.
- 5
Retirement is announced in the response itself
Once a version is scheduled for removal its responses carry Deprecation (RFC 9745) and Sunset (RFC 8594) headers naming the date, plus a Link rel="deprecation" pointing back at this page. You do not have to poll a changelog to find out.
The headers to watch
API-Version — on every /api/* response. Record it with whatever you cache; if it changes, so did the contract.
Deprecation (RFC 9745) — an IMF-fixdate naming when the version was deprecated. Absent while a version is current.
Sunset (RFC 8594) — an IMF-fixdate naming when the version stops responding. Never less than 180 days after the Deprecation date.
Link: rel="deprecation" — points at this page, so a client that sees the header can fetch the reasoning without being told where to look.
Nothing is deprecated today, so no Deprecation or Sunset header is being sent. That absence is the signal: if you are not seeing them, you are on a version with no end date.
What is not covered
The content itself is not versioned. Articles get edited, digests get added, the health panel gets a new draw — those are data changes, not contract changes, and they happen without notice. Version numbers describe the shape of a response, not its contents. If you need a fixed snapshot of the writing, cache it.
Back to the developer portal for the full surface list, or /openapi.json for the spec.