API stability policy

A predictable contract, in writing

A public commitment to how versions ship, deprecate, and sunset. Breaking changes are rare, scheduled, signaled, and reversible. Every schema change is logged in plain text on this page.

Current default

v2.4 GA

All new tokens, all SDKs

Min support window

≥ 12 months

From deprecation to sunset

Breaking changes (12m)

v2.1 → v2.2 cursor format

Schema diffs (90d)

Logged below, in plain text

Version status

Version	Stage	Released	Sunset	Notes
v2.4	GA	2026-02-11	—	Stable. Default for all new tokens. Adds /pacing-windows resource and signed-decision webhook.
v2.3	GA	2025-11-04	2027-02-11 (≥ 12 months)	Stable. Receives security patches; no new feature work. Full additive parity with v2.4 except pacing-windows.
v2.2	Deprecated	2025-06-19	2026-06-19	Deprecated. 410 with `Sunset` header on every response. Migrate to v2.4.
v2.1	Sunset	2025-01-22	Reached 2026-01-22	Sunset. Returns 410 Gone permanently.
v3.0 (preview)	Beta	2026-02-25	—	Preview. Cursor-based pagination, typed errors per RFC 9457, signed responses. Stability not guaranteed before GA.

Schema diff log (90 days)

Additive

POST /v2.4/budgets/{id}/locks

2026-03-04

New endpoint for budget locks; mirror of /budget-locks dashboard.

Additive

GET /v2.4/pacing-windows

2026-02-26

Pacer plan resource; supports filters by scope, mode, state.

Behavior

GET /v2.4/transactions

2026-02-18

Pagination default page size increased 100→250. Behavior is opt-in via Accept-Profile header until 2026-04-01.

Additive

Webhook · payout.signed

2026-02-04

New event; payload includes ed25519 signature header.

Breaking

v2.1 sunset

2026-01-22

v2.1 removed (announced 12 months prior). Returns 410 Gone permanently.

Additive

GET /v2.4/anomalies

2025-12-09

Adds `confidence` field as decimal 0–1; backward-compatible.

Our commitments

Minimum 12 months between deprecation and sunset on any GA endpoint.
Every deprecated response carries a Sunset and Link rel="deprecation" header.
Breaking changes require a new major version. We do not silently change existing endpoints.
SDKs ship with version pinning; integrations are tested on every release in /policy-tests.

What counts as a breaking change

Removing a field, endpoint, or webhook event.
Tightening a validator (rejecting input previously accepted).
Changing pagination, authentication, or rate-limit semantics.
Reducing the strength of a returned signature, key, or audit identifier.