Versioning

‍

We use date-based versioning (for example ‘2022-02-22’) to track breaking changes to the API (read more about these in the 'Breaking changes' section at the bottom of this page). These versions are released independently of the Cutover Core version that you are running (for example ‘v2024.5.2’).

‍

Follow the steps below to view and access the API’s different available versions:

‍

1. Click on My Profile in the bottom-left corner of the app.

2.Under where it says 'View API endpoint documentation with credentials:' in the My Details panel, click either On the Developer Portal or On your API instance.

3. Click on the version dropdown menu in the top left of the documentation.

‍

‍

By default, your API requests will be sent as the earliest available version of the API (which is the first in your list - the one you are initially provisioned on). 

If you wish to make use of functionality that is featured in a newer or older API version than your default version, you will need to pass it in an ^Api-Version header in your request.

‍

‍

All of the latest endpoints and parameters will be available in the most recent date-based version.

‍

Endpoint availability relative to Cutover Core version

Our Updates page records when and what changes are made to the API. To make successful calls to new endpoints that have been added to an API version, you will need the minimum version of Cutover Core that supports the endpoint.

Here is a failure scenario:

• You are running Core v2024.4.2.
• You use a new endpoint in the API that requires Core v2024.5.2.
• An HTTPS response code of ^{405 Method Not Allowed} will be returned, containing a message that says your Core version does not support the endpoint.

Note: In the API Portal, the minimum Core version required for a parameter is provided in the parameter’s description.

‍

‍

Breaking changes

We consider the following to be breaking changes which will result in a new API version:

‍

• Changing the URL of an endpoint 
• Changing the name of a parameter
• Making an optional parameter required
  

Note: Any other changes to the API are considered to be backwards-compatible (non-breaking) changes and will not necessarily result in a new API version.