Deprecation & Versioning

This page is the promise behind the beta label. It tells you exactly how the Madless API changes over time, how you will hear about it, and how much notice you will get before anything you depend on goes away.

The API is versioned in the path. Everything you build against today lives under /api/v1. That major version is stable: breaking changes never ship into it.

• Non-breaking additions can land in v1 anytime. New endpoints, new optional request fields, and new fields on existing responses may appear without a new version. Write your client so that unknown response fields are ignored, not fatal.
• 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

When an operation 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.

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://docs.madless.com/changelog>; rel="deprecation"

We will not pull anything out from under you. Before any operation reaches its Sunset date, you get at least 90 days’ notice — both in the Sunset header on live responses and as a dated entry in the Changelog.

For breaking changes that move to a new major, the previous major stays online for the whole notice window so you can migrate without a hard cutover. The changelog entry will name the replacement and what changed.