TokenJam API deprecation policy

How the TokenJam website content API is versioned, how a deprecation is announced, and the minimum notice you get before anything stops answering.

Current version

v1 is current and stable. The version lives in the URL path, as in /api/v1/posts.json.

What counts as breaking

Breaking changes ship as a new version segment (/api/v2/), never in place. Within a version, fields may be added but existing fields are not removed, renamed, or retyped.

Additive changes ship without notice: new endpoints, new fields on existing responses, and new optional parameters. Write your clients to ignore fields they don't recognise.

How a deprecation is announced

Four ways, all at once, from the day the deprecation is decided:

Deprecation header (RFC 9745) — Set on every response from a deprecated endpoint, carrying the date the deprecation was announced.
Sunset header (RFC 8594) — Set alongside Deprecation, carrying the date the endpoint stops responding.
deprecated: true in the OpenAPI document (OpenAPI 3.1) — Marked on the operation as soon as the deprecation is announced.
A note on the API page and in the changelog — Written explanation of what replaces the endpoint.

A deprecated endpoint's responses carry both headers:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Deprecation: @1780272000
Sunset: Wed, 03 Jun 2026 00:00:00 GMT
Link: <https://tokenjam.dev/api/v2/posts.json>; rel="successor-version"

Deprecation follows RFC 9745 and carries the moment the deprecation was announced. Sunset follows RFC 8594 and carries the moment the endpoint stops responding. When a replacement exists, a Link header with rel="successor-version" points at it.

The notice guarantee

A deprecated endpoint keeps responding for at least 90 days after the Deprecation header first appears. No endpoint is removed without that notice. If you are integrating against this API, that window is what you can plan around.

Machine-readable

The same policy, for agents rather than people:

curl -s https://tokenjam.dev/api/v1/index.json | jq .lifecycle

What this covers

This policy governs the public website content API under /api/v1/. It does not govern the TokenJam CLI, whose releases follow semantic versioning on PyPI, or the local API that tj serve runs on your own machine.

Questions, or notice that something changed without warning: support@tokenjam.dev. A silent breaking change is a bug, and we would want to hear about it.