Versioning & deprecation
The version is in the path
This API is versioned in the URL path: every endpoint lives under /v1/. Your
integration pins the version by construction — nothing about a request opts into
behaviour it did not ask for.
What a breaking change looks like
A breaking change ships under a new version path (/v2/...), never inside the one
you are using. When a new version ships, the prior version remains supported for a
deprecation period of 90 days from the deprecation announcement, so an
integration has a full quarter to move at its own pace.
Error types and statuses are part of the contract
The type URI and the HTTP status of every documented error are stable identifiers
you can branch on. They never change without a documented deprecation. Adding a
new error to the reference is an additive, safe change; renaming or
re-statusing an existing one is a breaking change and is treated exactly like one.
The same holds for the response schema: members are added, not repurposed. A member documented as absent-when means exactly that, and its absence rule changes only with a version.