API versioning and deprecation

You are asked to point your own scripts, integrations and Zendesk client libraries at ChaosDesk. This page is the promise that comes with that: what we may change, what we may not, and how much warning you get. It covers the REST API under /api, the Zendesk-compatible API under /zd/api/v2 and the webhook contract. Every change lands in the API changelog.

The short version

Notice before anything is removed	12 months
REST API versioning	None in the URL: /api only grows
Version number	info.version in openapi.json, semantic
Zendesk-compatible API	Frozen to the documented Zendesk shapes
Webhooks	version integer in the payload, pinned per webhook
How a deprecation is announced	Changelog, Deprecation and Sunset headers, deprecated in the OpenAPI document, e-mail

One living REST API, additive only

/api is not versioned in the URL and will not be. We add to it instead:

• new endpoints,
• new optional query and body parameters,
• new fields in responses.

Write your client so it ignores fields it does not know, and new fields are never a problem. In return, we never remove a field, never change a field’s type in place, and never make an existing parameter required.

The version you can quote in a bug report is info.version in the OpenAPI document. It is semantic: the patch number moves for fixes, the minor number for additions, and the major number only together with the rule below.

If something has to break

A breaking change ships beside the old shape, never through it. The new shape appears either as a new field or at a new path for the affected resources only (/api/v2/<resource>), and the old one keeps working for the full notice period below. We do not use a date-based version header: it multiplies behaviours per endpoint, and our generated client libraries pin paths, not headers.

The Zendesk-compatible API is frozen

/zd/api/v2 exists so that clients written for Zendesk keep working. The v2 there is Zendesk’s version, not ours. On that surface we only ever add endpoints and fields, and we never change a response another vendor’s client parses. Our commitment is to the shapes documented on the Zendesk-compatible API page, and contract tests guard them on every build. If Zendesk changes its own API, ours stays as documented and the difference is recorded in the changelog.

Webhook payload versions

Every webhook delivery and ping carries a version integer in its envelope. It is 1 today, and it is part of the public contract.

• An incompatible envelope gets a new integer, never a change to an existing one.
• The version is chosen per webhook subscription, so an existing webhook keeps the envelope it was built for.
• While a version is being retired, both are delivered for the full notice period.
• Event types are additive. A subscription to an event type you do not know about never fails.
• If the signature scheme ever changes, the new signature arrives in a new header and both are sent during the notice period.

12 months of notice

Removing an endpoint, a field, an event type or a webhook envelope version from any of the three surfaces is announced at least 12 months in advance.

“Announced” means all of these, not just the first:

1. an entry under Deprecated in the API changelog, with the date the removal is planned for;
2. Deprecation and Sunset response headers (RFC 8594) on the affected operations, so a client can see it without reading anything;
3. deprecated: true on the operation or field in the OpenAPI document;
4. an e-mail to workspace owners and to the owners of API tokens that have called the endpoint in the last 90 days.

The headers look like this:

HTTP/1.1 200 OK
Deprecation: Thu, 12 Mar 2026 00:00:00 GMT
Sunset: Fri, 12 Mar 2027 00:00:00 GMT
Link: <https://chaosdesk.io/developers/api-changelog>; rel="deprecation"; type="text/html"

Deprecation is when we announced it, Sunset is the earliest moment the operation can stop answering.

The one exception is a change forced on us by a security or legal problem. That gets as much notice as is safe to give, never less than 7 days, and always a direct e-mail as well as a changelog entry.

What is not covered

• The agent application’s own endpoints (/mobile-api) are internal to our apps and change with them. Do not build on them; the REST API has the same data.
• Beta endpoints, where we offer them, are marked as beta in the changelog and are not under the 12-month rule until the changelog says they are. Nothing is beta by default: anything in the API reference without a beta note is under the full policy.
• Behaviour that was always a bug. Fixing a response that contradicted this documentation is a fix, and it ships in a patch release with a changelog entry.

Keeping up

• Watch the API changelog, which is where every change is written down first.
• Re-generate or update your client library when the OpenAPI version’s minor number moves; the clients are generated from that document.
• Log the Deprecation and Sunset headers in your integration. They are the earliest machine-readable warning you will get.

Decision record: ADR 0014, API and webhook versioning and the deprecation policy.