Skip to content
Support
API

Versioning

The version in the path, the document version, what can change within a version, deprecation and the next version of the Platform API.

The version is part of the path, /api/v2, and of the API base URL. v1 is the legacy Sign In API, which has its own paths and the Legacy API key. It is frozen: nothing is added to it.

Within v2

Section titled “Within v2”
  • Changes are additive only: new operations, new response fields, new optional request fields, new enum values and new error codes. Nothing is renamed, no field changes its type or meaning, and nothing is removed without a deprecation first.
  • Clients ignore unknown response fields, enum values and error codes. An unknown errorCode is handled by its HTTP status.
  • The OpenAPI document carries the document version in info.version, 2.N: 2.0 is the first version, and every published change raises N. Each version is listed in Changelog.

Deprecation

Section titled “Deprecation”

An operation or field that is going to be removed is marked deprecated in the OpenAPI document at least 12 months before the removal, and the changelog names the version that deprecated it. Every response of a deprecated operation carries two headers:

HeaderValue
DeprecationWhen the deprecation began: @ followed by the time in seconds since 1970-01-01 UTC (RFC 9745), for example @1793404800.
SunsetWhen the operation is removed, as an HTTP date (RFC 8594), for example Sun, 31 Oct 2027 00:00:00 GMT.

A new version

Section titled “A new version”

A breaking change comes in a new version, /api/v3, published alongside v2. v2 stays available for at least 12 months after v3 is generally available.

Next

Changelog

The published versions of the OpenAPI document of the Platform API, newest first.

Organization

Base path, operations and permissions of the Organization API.