{"templateId":"markdown","versions":[{"version":"v2025-07-01","label":"2025-07-01","link":"/docs/v2025-07-01/versioning","default":false,"active":false,"folderId":"a2557b8d"},{"version":"v2025-08-01","label":"2025-08-01","link":"/docs/v2025-08-01/versioning","default":false,"active":false,"folderId":"a2557b8d"},{"version":"v2025-09-01","label":"2025-09-01 (Latest)","link":"/docs/versioning","default":true,"active":true,"folderId":"a2557b8d"}],"sharedDataIds":{"sidebar":"sidebar-docs/@v2025-07-01/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Versioning"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"versioning","__idx":0},"children":["Versioning"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Convoy API is versioned. Our API versions are named for the date the version is released, for example, our latest version is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2025-09-01"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You set the version by including a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Convoy-Api-Version"]}," header."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"method\": \"get\",\n  \"url\": \"https://developer.convoy.com/operation-name\",\n  \"headers\": {\n    \"Content-Type\": \"application/json\",\n    \"Authorization\": \"Bearer <BEARER_TOKEN>\",\n    \"X-Convoy-Api-Version\": \"2025-09-01\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Convoy-Api-Version"]}," header is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A new API version is released when we introduce a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All webhook APIs must be registered with a specified API version."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"upgrading-to-a-new-api-version","__idx":1},"children":["Upgrading to a new API version"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When you update your integration to specify the new API version in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Convoy-Api-Version"]}," header, you'll also need to make any changes required for your integration to work with the new API version."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once your integration is updated, test your integration to verify that it works with the new API version."]}]},"headings":[{"value":"Versioning","id":"versioning","depth":1},{"value":"Upgrading to a new API version","id":"upgrading-to-a-new-api-version","depth":1}],"frontmatter":{"seo":{"title":"Versioning"}},"lastModified":"2026-08-10T16:41:50.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/versioning","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}