URL versioning
The API is versioned in the URL. All v1 endpoints live under/v1 (and the token endpoint under
/oauth). A future major version would be served under a new prefix (/v2), leaving /v1 intact.
Backward compatibility
Within/v1 we make additive, non-breaking changes freely — new endpoints, new optional
request fields, and new response fields. Every change to the API is checked by an automated
breaking-change gate against the published contract, so a backward-incompatible change to /v1
cannot ship by accident.
Breaking changes include: removing an endpoint, removing or renaming a field, narrowing a type, or
making a previously optional request field required.
Deprecation signals
When an endpoint is eventually retired, it advertises it with standard RFC 8594 response headers before removal:
No v1 endpoint is deprecated today. Watch for these headers and migrate before the
Sunset date.