The Convoy API is versioned. Our API versions are named for the date the version is released, for example, our latest version is 2025-09-01.

You set the version by including a X-Convoy-Api-Version header.

{
  "method": "get",
  "url": "https://developer.convoy.com/operation-name",
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "Bearer <BEARER_TOKEN>",
    "X-Convoy-Api-Version": "2025-09-01"
  }
}

The X-Convoy-Api-Version header is required for all requests. If you do not specify a valid API version or if you specify an API version that is no longer supported, you will receive a 400 error.

A new API version is released when we introduce a backwards-incompatible change to the API. Versioning is only for backwards incompatible changes. For new features and additions to the API, such as adding a new API endpoint, or adding a new optional input field, or including a new field in an existing API endpoint's response, there won't be a new version. You'll be able to take advantage of any new functionality on the version of the API you're currently using.

All webhook APIs must be registered with a specified API version.

Before upgrading to a new REST API version, you should read the changelog of breaking changes for the new API version to understand what breaking changes are included and to learn more about how to upgrade to that specific API version.

When you update your integration to specify the new API version in the X-Convoy-Api-Version header, you'll also need to make any changes required for your integration to work with the new API version.

Once your integration is updated, test your integration to verify that it works with the new API version.