How Versioning Works

Everything you need to know about API versioning at Convictional


Stay informed on breaking changes

Make sure to subscribe to End Of Life announcements to stay in the loop!


You can see all supported API Versions in the top-left corner of this page, e.g. v2022-03-03. Versions are named after their date of release in YYYY-MM-DD format. The v prefix is always left out of the version when using it in the API.

To put a version in your request, include an Accept header like this:

Accept: application/vnd.convictional.2021-01-01

We confirm the version that was used with the Convictional-Version header in every response:

Convictional-Version: 2021-01-01

Ending Support for Old Versions

We support API versioning in order to help you predict and plan for changes. As we release new versions, we will also deprecate and end support for old versions. Your willingness to work with us by staying up-to-date allows us to build better products and incorporate your feedback faster. We will always strive to make each upgrade as simple as possible. Make sure to subscribe to our End of Life announcements to stay in the loop.

Fall Forward

You should always be sure to upgrade your API client as old versions are deprecated and removed. However as a safeguard, if your API client requests a version that is no longer supported we will attempt to fall forward to the oldest supported version instead.

Version Pinning

When you send a request without a version, we use your pinned version instead. Your pinned version is the latest API version in use at the time of your first unversioned request.

What does this mean? Well, if you build an API client that doesn't specify a version then the latest version will be used and pinned to you. Suppose we release a second version some time later, your API client won't be impacted: it will still use the original version. However anyone building a new API client at that time will be pinned to the second version instead.

Your pinned version is set once and never changed afterwards. However, you can override your pinned version at any time by specifying a version in your request.

How can I know my pinned version? Just send an unversioned request to any Convictional API endpoint (that you have permissions for), and check the Convictional-Version header that gets returned. This is your pinned version.

Tip: It's highly recommended to always specify a version in your requests. By doing so, you can disregard version pinning entirely.

Did this page help you?