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.
Both APIs echo Spotzee-Version in responses. Strict validation is enabled on the Extended API; the Main API accepts unsupported values while strict validation is disabled. Do not use an unsupported version as a compatibility guarantee. When strict validation is enabled, unrecognised dates 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

The OpenAPI spec can mark an operation with deprecated: true; that flag does not include a removal date.

​
Next steps

Errors

Status codes and the code catalogue.

Idempotency

Make retries safe.