API versioning and deprecation policy

Breaking changes arrive as a new version in the URL path. A published version's shape never changes under a client: fields are added, never removed or retyped.

A version being retired carries RFC 8594 Sunset and the Deprecation header on every response for at least 90 days before it stops answering, and the date is published on this page before the headers appear.

Where a new battery changes what a verdict MEANS rather than only what it checks, the old one keeps running through an overlap instead of being retired — a signed observation cites the criteria it was rendered under, and renaming those criteria retroactively would make a signature cover a claim nobody made.

The headers a retiring version carries

• Sunset: <http-date> — RFC 8594 §3, the day the version stops answering.
• Deprecation: <http-date> — the day the deprecation took effect.
• Link: <...>; rel="sunset" — RFC 8594 §4, pointing at this page.
• Link: <...>; rel="successor-version" — RFC 5829, the path to call instead.

Nothing is deprecated today, so nothing sends them today. The routes read the same table this page prints, so the headers appear the day a row below gains a date — there is no second place to remember to edit.

Every version currently served

What is not promised

Permanence. One operator and one key cannot honestly promise that any endpoint runs forever, and /wind-down says what happens to everything this store holds if the lights go off. What is promised is notice, in machine-readable form, at a stated minimum.

The contract is at /openapi.json; the rest of the developer documentation is at /developers. This page also serves JSON and markdown by Accept.