Deprecation & Versioning
The promise behind a frozen v1: how the API changes, how you hear about it, and how much notice you get before anything you depend on goes away.
Versioning
The API is versioned in the path. Everything you build against lives under /api/v1, and that path is not going anywhere. v1 is stable: inside it, nothing is removed, renamed, retyped, or made required that used to be optional.
Two rules hold, and between them the version stops moving under you:
- Non-breaking additions can land in v1 anytime. New endpoints, new optional request fields, new fields on existing responses — and new values in closed enums. Write your client so that an unknown field is ignored and an unknown enum value is treated as opaque, never as an error.
- Breaking changes ship as a new major. Removing a field, renaming a field, changing a type, or tightening validation means a new path, e.g.
/api/v2. The old version keeps working through its sunset window so you can migrate on your own schedule.
Every response carries an X-API-Version header so you can confirm which major served your request.
X-API-Version: v1
How deprecation is signalled
When a major version is on its way out, the API tells you in the response headers, following RFC 8594. You do not have to poll anything — the signal rides along on the calls you are already making. Watch for these headers in your client and surface them in your own logs.
| Header | Description |
|---|---|
| X-API-Version | The API major version that served this response. Always v1 today. |
| Deprecation | Set to true once this major version is scheduled for retirement (RFC 8594). |
| Sunset | The date after which the retired major may stop responding (RFC 8594). |
| Link | A link to the note explaining the change, with rel="deprecation". Today that is this page. |
A deprecated response looks like this — the body is unchanged, only the headers are added:
HTTP/1.1 200 OK X-API-Version: v1 Deprecation: true Sunset: Wed, 31 Dec 2026 23:59:59 GMT Link: <https://developers.madless.com/deprecation>; rel="deprecation"
There is no changelog to link to, and that is deliberate: a page listing every change is a feed. The Link header carries the note for the change itself — today this page, and a specific migration note when a major is retired. That note also reaches you by email, so nothing depends on you finding a page.
Notice window
Nothing gets pulled out from under you. Before anything reaches its Sunset date, you get at least six months’ notice — both in the Sunset header on live responses and by email, in advance, to the address on your account.
Nothing inside v1 is ever deprecated on its own — deprecation applies to v1 as a whole, once v2 exists. A single operation does not get its own sunset date; the major does.
When a breaking change moves to a new major, the previous major stays online for the whole notice window so you can migrate without a hard cutover. The notice will name the replacement and what changed.