Skip to content

Versioning and deprecation

The version in the path, non-breaking changes and the deprecation process.

Developer documentation

The version is in the path

This documentation describes /api/v1. The version is carried only in the path; no version is selected by header or query.

Non-breaking changes

The following can happen within v1 without prior notice. Your client should tolerate them:

  • a new endpoint or method,
  • a new field in a response (ignore fields you do not recognise),
  • a new optional query filter or body field,
  • a new value in an enum (treat values you do not recognise as unknown),
  • a new event type or a new error code,
  • a new response header.

Every change is checked by machine: the published contract in the repository is compared with the new OpenAPI document, and a change that removes a field, a path or an enum value, or adds a new required input, is not published.

Breaking changes

Removing a field, changing its type or meaning, removing an endpoint or adding a new required input is breaking and needs a new version (/api/v2). When a new version is published, v1 keeps working.

Deprecation

  • A deprecated endpoint is marked with deprecated: true in the OpenAPI document and written to the Changelog.
  • Every response of that endpoint carries the Deprecation (RFC 9745) and Sunset (RFC 8594) headers; when there is one, Link: <...>; rel="deprecation" points to the migration guide.
  • The Sunset date is at least 12 months after the deprecation is announced. Until then the endpoint works as it does.

We recommend that your client logs the Deprecation header: that way the calls that need migrating show up by themselves.