Versions and deprecation

The API: dated versions

The API is versioned by date (2026-09-20). Your account is pinned to the version that was current when it was created, and every request is answered in it — unless you send Tuppence-Version: <date> to choose another. Every response says which version answered.

• Additive changes never need a new version: a new endpoint, a new optional parameter, a new field in a response, a new event type, a new error code. Write code that ignores what it does not know.
• Breaking changes only ever arrive in a new version: removing or renaming a field, changing a default, changing what an error means. You move when you choose: send the new version with your requests (every SDK lets you pin one) once you have tested against it.

The SDKs: semantic versions

@tuppence/node, @tuppence/http402, @tuppence/mcp, @tuppence/agent-tools and tuppence (Python) follow semantic versioning. Before 1.0, a minor release may break (0.3.0 → 0.4.0) and a patch release never does. Each SDK pins the API version it was built for, so upgrading the API version and upgrading the SDK are separate decisions. Every package is published from our CI with provenance (npm) or trusted publishing (PyPI): you can check a release was built from this repository.

Deprecation

• An API version is supported for at least 12 months after a newer one is released.
• Anything deprecated is announced in the changelog and these docs at least 6 months before it is removed, and responses that use it carry a Deprecation header meanwhile.
• In the SDKs, a deprecated method keeps working, and warns, for at least one minor release before it is removed.