Skip to main content

​
Client API Versioning and Changelog

​
Version model

  • Base path versioning: /v1/...
  • Optional request pin: Omni-Version header
  • Response echoes selected Omni-Version

​
Omni-Version format

Omni-Version is a date-based pin: 
YYYY-MM-DD
Example: 
Omni-Version: 2026-02-17
If you omit Omni-Version, you get the current default behavior for /v1.

​
When to pin

Pin when you want deterministic behavior across time, especially during beta when the API surface is evolving. Recommended posture:
  • Production integrations: always pin.
  • Prototypes: omit pinning, but expect drift.

​
Change categories

  • Additive: new endpoints/fields, non-breaking
  • Behavioral: semantics clarified, may require migration note
  • Breaking: removed/renamed fields, auth or error-contract changes

​
Beta policy

  • Internal beta may introduce breaking changes with migration notes
  • Public beta requires deprecation notice windows before breaking changes

​
Changelog format

For each release:
  • Release date (UTC)
  • Affected endpoints
  • Contract changes
  • Migration steps
  • Sunset dates (if applicable)