Versions

We version our API. This page describes the versioning strategy, version history, and how to specify a version in your requests.

The API version name matches the date of the release of the API. This is often referred to as calendar versioning. The first and current API version is 2024-12-01.

Non-breaking changes will be released across all active versions. For example:

• adding optional fields to request schemas
• adding fields to response schemas
• adding new endpoints
• adding response headers
• adding new response status codes to an endpoint
• adding new error types to response schemas
• extending enum types in the request and response schemas, i.e., adding new values

Breaking changes will be released in a new version. These are changes that might break the existing interface or potentially the way you are using the API. For example:

• removing or renaming fields in the request schemas
• adding required fields to request schemas
• removing or renaming fields in the response schemas
• removing endpoints

Generally we try to avoid breaking changes and rather extend the API in a compatible way.

​

Specifying a version

Use the x-shiftkeeper-api-version request header to specify the API version, for example, x-shiftkeeper-api-version: 2024-12-01.

If no version is specified, the latest version will be used. We recommend always specifying the version in your requests to avoid any breaking changes.

​

Version history