API Versioning & Deprecation
How the Coherence API is versioned, what changes are considered breaking, and how deprecations are announced
The Coherence API is versioned in the URL. All current endpoints live under the
/v1 prefix:
https://api.getcoherence.io/v1
Breaking changes only ever ship under a new version prefix (e.g. /v2). Within
a version, the API evolves additively — your integration will not break because
we shipped something new.
Non-breaking (additive) changes
The following can happen at any time within /v1, without notice:
- New endpoints
- New optional request parameters or body fields
- New fields in response objects
- New values in the error code catalog
Build tolerant clients: ignore unknown response fields and unknown error codes rather than failing on them. A client that rejects a response because it contains a field it doesn't recognize will break on routine additive changes.
For unknown error codes, fall back to the statusCode field (or the HTTP
status) to decide how to handle the error.
Breaking changes
We treat the following as breaking, and they only ship under a new version prefix:
- Removing or renaming endpoints
- Removing or renaming request or response fields
- Changing a field's type or meaning
- Changing the status code or error code of an existing failure mode
- Tightening validation so previously accepted requests are rejected
The error code catalog is additive-only: codes are never renamed or removed once shipped.
Deprecation policy
When we deprecate behavior (including retiring an old version prefix once a successor exists), we give at least 90 days notice before it is removed. Deprecations are announced:
- In the changelog
- On the affected documentation pages
During the notice period the deprecated behavior keeps working as documented, so you have the full window to migrate.
Subscribe to the changelog Atom feed at
/changelog/feed.xml to get deprecation notices and
API announcements in your feed reader or tooling.
Related: API Overview | Errors | Changelog