Versions and deprecation
The API is versioned by date and the SDKs by semver. Nothing you rely on changes until you choose to move.
The API: dated versions
Section titled “The API: dated versions”Your account is pinned to the version current when it was created (2026-09-20). Every request
uses it unless you send Tuppence-Version: <date>. Every response says which version answered.
| Change | Needs a new version? |
|---|---|
New endpoint, optional parameter, response field, event type or error code | No. Write code that ignores what it doesn’t know |
| Removing or renaming a field, changing a default, changing what an error means | Yes. Only in a new version, and you move when you choose |
Test against the new version, then send it with your requests:
curl https://api.tuppence.ai/v1/balance \ -H "Authorization: Bearer $TUPPENCE_SECRET_KEY" \ -H "Tuppence-Version: 2026-09-20"const tuppence = new Tuppence(process.env.TUPPENCE_SECRET_KEY, { apiVersion: "2026-09-20" });tuppence = Tuppence(os.environ["TUPPENCE_SECRET_KEY"], api_version="2026-09-20")The SDKs: semantic versions
Section titled “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); a patch 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,
never from a laptop.
Deprecation
Section titled “Deprecation”| What | Notice |
|---|---|
| An API version | Supported for at least 12 months after a newer one is released |
| Anything deprecated | Announced in the changelog and these docs at least 6 months before removal. Until then, responses that use it carry a Deprecation header |
| An SDK method | Keeps working, with a warning, for at least one minor release before removal |