Skip to main content
The Spotzee API uses date-based versions identified by the day a release shipped. Pin a version with the Spotzee-Version request header.
The current release is 2026-04-28.
Spotzee-Version validation and response echo are live on the Extended API today and rolling out to the Main API. Including the header on Main API requests is forward-compatible: today the value is accepted as a forward-looking declaration; once the rollout completes, unrecognised values return 400 version_unsupported.

​
How it works

  • Send the header: the request runs against that version.
  • Omit the header: the request runs against the current default release. The default moves forward only when a new dated release ships; pin a version explicitly if you want behaviour to stay stable across upgrades.
  • Every response echoes the version in a Spotzee-Version response header so you can confirm what you ran against.

​
Choosing a version pin

Pin to the latest version when you build, then schedule periodic upgrades. Once per quarter is a sensible cadence. Every breaking change earns a new dated release; the version you pinned keeps working until its deprecation window closes.

​
Version errors

​
Breaking vs non-breaking changes

A new dated release ships when we make a breaking change. Adding a new endpoint, response field, or enum value is non-breaking and lands in the current release without a new pin. Treat the following as breaking:
  • Removing or renaming a field
  • Tightening validation (rejecting input that previously succeeded)
  • Changing the type or shape of an existing field
  • Changing the meaning of an enum value
  • Changing default behaviour when a parameter is omitted

​
Deprecation windows

Endpoints, fields, or behaviours scheduled for removal carry a deprecated: true marker in the OpenAPI spec along with the date after which they stop working. Spotzee aims for a 12-month deprecation window.

​
Next steps

Errors

Status codes and the code catalogue.

Idempotency

Make retries safe.