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-05-28-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-05-28-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. Previously shipped versions are permanent snapshots. They don't change as the API evolves, so the reference for a version you've pinned stays accurate.

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.