Skip to main content

API versioning

The Ceros API is versioned so integrations stay stable as the API evolves.

Version identifiers​

Versions are timestamped, in the form YYYY-MM-DD-HH-MM, for example 2026-08-06-09-00. A new version is introduced when a change would otherwise break existing integrations.

Selecting a version per request​

Send the version you want in the x-ceros-api-version request header:

x-ceros-api-version: 2026-08-06-09-00
  • Omit the header and your request is served against the latest version. This is convenient for exploration but means behavior can change under you when a new version ships.
  • Pin an explicit version for production integrations, so upgrades happen on your schedule, not ours.

Browsing versions in the reference​

Each API reference (Public and, internally, Full) has a version selector. Pick a version to see that version's exact endpoint surface. A shipped version's reference is a snapshot: it doesn't change as the API evolves, so the reference for a version you've pinned stays accurate for as long as that version is offered.

Retired versions​

Versions are retired once they are no longer in use. A retired version disappears from the version selector, and a request that still sends it in x-ceros-api-version is rejected with 400 Invalid API version rather than being served a differently shaped response. If you pin a version, make sure it is one the selector still lists.

Upgrading​

When you're ready to adopt a newer version:

  1. Review the newer version's reference for the endpoints you use.
  2. Update your integration to match any changed request/response shapes.
  3. Change the x-ceros-api-version header to the new version.