Versioning

Versioning

Reference article: Part of the API reference.

The API is versioned by date. When we make a change that could break existing code, we release it under a new version, and requests pinned to an older version keep the old behaviour.

The current version is 2026-09-25.

Pinning a version

Send the version in the Nimbus-Version header. Every response echoes the version it was served with.

::: code-group

curl https://api.gonimbus.ai/v1/whoami \
  -H "Authorization: Bearer $NIMBUS_API_KEY" \
  -H "Nimbus-Version: 2026-09-25"

const response = await fetch('https://api.gonimbus.ai/v1/whoami', {
  headers: {
    Authorization: `Bearer ${process.env.NIMBUS_API_KEY}`,
    'Nimbus-Version': '2026-09-25',
  },
})
console.log(response.headers.get('Nimbus-Version')) // "2026-09-25"

response = requests.get(
    "https://api.gonimbus.ai/v1/whoami",
    headers={
        "Authorization": f"Bearer {os.environ['NIMBUS_API_KEY']}",
        "Nimbus-Version": "2026-09-25",
    },
)
print(response.headers["Nimbus-Version"])  # "2026-09-25"

:::

A request without the header is served with the newest version. That's convenient while you explore, but code you deploy should always pin a version, so a new release can't change what it receives.

A request naming a version the API doesn't know fails with 400 and the code invalid_api_version; it's never silently served a different version.

What counts as a breaking change

These need a new version:

  • Removing or renaming a field, parameter, or endpoint.
  • Changing a field's type or format.
  • Making an optional parameter required.
  • Changing the meaning of a status code or error type.

These don't, so write your code to tolerate them:

  • Adding endpoints, optional parameters, or response fields.
  • Adding values to an enum, such as a new event type or error code.
  • Changing error message text.
  • Changing the length or format of object IDs. Treat IDs as opaque strings up to 255 characters.

The /v1 in the path

The /v1 prefix is the major version of the API as a whole. Dated versions evolve within it; it would only change for a complete redesign.

FAQ

Which version should I use?

The current one, 2026-09-25, pinned in the Nimbus-Version header of every request.

How will I hear about new versions?

New versions and what changed in them will be listed in this reference. Pinned requests keep working unchanged, so you can upgrade when it suits you.

How do I upgrade to a new version?

Read what changed, update the code that depends on it, and change the Nimbus-Version header. Test against the new version before you deploy; you can send both versions from the same key side by side.

Does the version affect webhooks?

Every event carries the version it was rendered with in its api_version field. See The Event object.

Why isn't the version tied to my key or organization?

So you can see exactly which version a request used from the request itself, and upgrade one service at a time.