Skip to content
Relay Port

More

Versioning and the changelog

The API is versioned by date in the X-Api-Version header. Additive changes ship at any time, and breaking changes only under a new date.

The API has no version in its URLs. A version is a date, sent in the X-Api-Version header, and the API reference shows the current one.

Which version a request uses

  • Each API key is pinned to the version that was current when the key was created, so your integration keeps working the same way when a new version is released.
  • Send X-Api-Version with a date to use another version for one request, for example to try a new version before you move to it.
  • Every response carries X-Api-Version with the version it used.

Changes without a new version

These ship at any time, because a well-built client keeps working:

  • New operations and new event types.
  • New optional request fields and new query parameters.
  • New fields in responses and event payloads.
  • New error codes.

Build your client to ignore response fields it does not know, and to handle an error code it does not know by its HTTP status.

Changes that need a new version

Removing or renaming a field, changing its type or meaning, adding a required request field, or changing what an operation does ships only under a new date. Keys pinned to an older date keep the old behaviour.

Where changes are announced

Every change is listed in the changelog, newest first, with an RSS feed you can subscribe to, and a new version is announced there with what it changes.