Versioning and deprecation

The version promise

/v1 does not break. A breaking change means a new version, and /v1 keeps working as documented. Every response names the contract version it was served under in the velrim-version header; the current version is 2026-08-10. The header is the reserved version selector for the day a second version exists; today there is exactly one.

What is not a breaking change

New fields

New keys can appear in any response body or webhook body.

New enum values

String enums (for example meta.tier or a reason) can gain values.

New event types

Webhooks can gain event types beyond job.completed and job.failed.

Opaque strings

Ids, keys and tokens can change format or length. Treat them as opaque; never parse them.

The client side of the same promise: ignore unknown fields, unknown enum values and unknown webhook event types. The SDKs already do; if you parse responses yourself, never reject on an unknown key.

Stability tiers

GA

At least 90 days notice before any breaking change, announced on /changelog and by email to the owners of affected keys.

Beta

At least 30 days notice, the same channels.

Experimental

Can change at any time. Always labeled in the docs.

Every documented endpoint is GA. The one experimental surface is meta.warnings: its element shape is not specified yet and the array is currently always [].

Scheduled deprecations

None. No deprecation is scheduled for any GA surface. When one is, it appears here with a not-sooner-than date, on /changelog, and by email to affected keys.

Scope

The promise covers Velrim’s API contract: the request and response shapes documented here survive upstream model swaps. A model or calibration change never changes the wire shape; it gets a /changelog entry with regenerated curves at /reliability, and meta.calibrator_version names the stack that produced each response. Upstream model lifetimes are not ours to promise; the contract is.