API Versioning & Deprecation Policy

Current Versions

Nothing is deprecated today. Build on /api/v1/ rather than the unversioned alias, which always follows the newest version.

What Can Change Within a Version

• New fields in a response object, and new files under the same version path.
• New values in free-text fields, and corrected data that mirrors a change on the published pages (a price, a review date, an FAQ answer).
• Clients must ignore fields they don't know about.

What Counts as a Breaking Change

• Removing or renaming a field or a file, or changing a field's type.
• Changing what an existing field means, or narrowing the values it can take.

Breaking changes ship only as a new version path (for example /api/v2/). The old version keeps working, unchanged, until its sunset date.

Notice Period

A version is announced as deprecated at least 180 days before it can be removed. The sunset date is never earlier than the deprecation date plus 180 days.

How a Deprecation Is Signaled

• openapi.json: the version's operations get deprecated: true, and info.x-api-lifecycle.deprecated_versions lists its deprecation and sunset dates.
• HTTP headers on every response from the deprecated version: Deprecation (RFC 9745) with the deprecation time, Sunset (RFC 8594) with the earliest removal date, and Link to this page (rel="deprecation") and to the successor version (rel="successor-version").
• Dated notices in llms.txt, on the API documentation and in the changelog below.

For example, a version deprecated on 4 January 2027 would answer with:

Deprecation: @1799020800
Sunset: Mon, 05 Jul 2027 00:00:00 GMT
Link: <https://confined-space.com/api-docs/deprecation-policy/>; rel="deprecation"; type="text/html", <https://confined-space.com/api/v2/>; rel="successor-version"

After the Sunset Date

A removed version's paths return 404 with an RFC 9457 problem details body (code: not_found) that links to openapi.json.

Changelog