The promise
/v1 is stable. A response only ever gains fields, enum values or endpoints; nothing is renamed, removed or re-typed inside /v1. Anything that would break a correctly written client ships under /v2, and /v1 keeps working alongside it.
"Correctly written" means: ignore fields you do not know, accept new enum values gracefully (treat an unknown status as "not one I handle"), and branch on status and the type slug of an error, never on detail.
What may change without notice
- New optional fields in responses and webhook payloads.
- New webhook event types (you only receive the ones you subscribed to).
- New endpoints and new optional request fields.
- The wording of
detailandtitlein errors. - Rate-limit numbers going up.
- Default page sizes staying within the documented bounds.
What we treat as breaking
- Removing or renaming a field, endpoint or event type.
- Changing a field's type or units.
- Making an optional request field required.
- Tightening validation on input we used to accept.
- Changing an HTTP status for a documented situation.
We have made such changes inside /v1 only to fix behaviour that was wrong or unsafe, and each is in the changelog: on 2026-09-21 the voucher endpoint's 402 became 422 balance-insufficient; on 2026-09-28 the member ledger started answering 422 for a bad limit or cursor (it used to clamp the limit or answer 404), and adjust started answering 202 for an adjustment waiting for approval and 409 for a reused Idempotency-Key.
Deprecation
Nothing in /v1 is deprecated today. When something is:
- It is announced in the changelog with a sunset date at least 6 months out.
- Responses on the affected path carry
Deprecation: trueandSunset: <date>headers. - Owners of keys that still use it get an email at 90, 30 and 7 days.
- After the sunset date it returns
410 Gonewith atypepointing at the migration note.
Keeping up
The changelog is the record. The OpenAPI document at /openapi/cvos.v1.yaml carries info.version; diff it against the copy you built with.