Skip to main content
The API is versioned in the URL. The current stable version is v1:
When a new major version is released, it is exposed at a new URL prefix (for example v2). The old version keeps working in parallel for a deprecation window of at least 12 months so you have time to migrate.

​
What counts as breaking

A change is breaking (and therefore requires a new major version) if it:
  • Removes an endpoint
  • Removes or renames a request or response field
  • Changes the type of an existing field
  • Changes the semantics of an existing parameter (for example inverting a boolean’s meaning)
  • Tightens validation so that previously valid requests now fail
  • Changes the URL structure of an existing endpoint

​
What counts as non-breaking

These changes can happen on the current major version without a version bump:
  • Adding a new endpoint
  • Adding a new optional field to a request
  • Adding a new field to a response (always treat unknown response fields as ignorable in your code)
  • Adding a new value to an enum (treat unknown enum values as a fallback case in your code, not a hard error)
  • Performance and bug fixes that do not change documented behaviour
When parsing responses, always tolerate unknown fields. JSON libraries do this by default in most languages. Just do not enable strict schema validation against an outdated copy of the spec, or you will break the next time we ship a non-breaking addition.

​
Deprecation process

When something on the current version is going to be removed in the next major version:
  1. We publish a deprecation notice in these docs and email account owners.
  2. The endpoint continues to work for at least 6 months after the notice.
  3. The next major version omits the deprecated surface entirely.
The OpenAPI specification behind the API reference is regenerated from the server on every release, so it always describes the current shape of v1. Pin your client to a copy of it and diff against the latest version when you upgrade.