Versioning

The OmiCloud API is versioned by date. The current version is 2026-09-01.

Pinning a version

Send the version you built against on every request:

Omi-Version: 2026-09-01

If you omit the header, the version your API key is pinned to applies. Keys are pinned to the current version when they are created, so a new key always speaks the newest API. You can change a key's pinned version in the console.

Every response echoes the version that served it in an Omi-Version response header.

What is and is not a breaking change

OmiCloud adds to the API freely without a new version. Your integration must tolerate:

• new fields on any response object,
• new values in declineReason, gatewayState, and error.code (treat unknown ones by category),
• new event types on webhook endpoints subscribed to all events,
• new gateways appearing in GET /v1/gateways and GET /v1/routes,
• new optional request fields.

Anything else — removing or renaming a field, changing a type, changing the meaning of a state, tightening validation — ships as a new dated version. Old versions keep working; OmiCloud translates between them at the edge.

Webhooks

Each delivery carries version in its body — the version the payload follows. A webhook endpoint follows the version of the key that created it. Upgrading the key's pinned version upgrades the events that endpoint receives from that point on, so upgrade the receiver first.

Upgrading

1. Read the changelog entry for the new version.
2. Deploy code that sends Omi-Version: <new> explicitly and handles the changes.
3. Once every caller sends the header, move the key's pinned version in the console. This only matters for callers that omit the header.

Deprecation

A version is supported for at least 12 months after the next one is released. OmiCloud emails the operator's technical contact at announcement, 90 days, and 30 days before retirement. Requests to a retired version return 400 VALIDATION_FAILED with errors[0].field = "Omi-Version".