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 will be exposed at a new URL prefix (e.g. v2). The old version continues to work 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/response field
  • Changes the type of an existing field
  • Changes the semantics of an existing parameter (e.g. inverting a boolean’s meaning)
  • Tightens validation in a way 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 warning:
  • 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 don’t change documented behaviour
When parsing responses, always tolerate unknown fields. JSON libraries do this by default in most languages — just don’t enable strict schema validation against an outdated copy of the spec, or you’ll 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 the changelog and email account owners.
  2. The endpoint continues to work for at least 6 months after the notice.
  3. During that window, responses include a Deprecation header pointing at the replacement.
  4. The next major version omits the deprecated surface entirely.

​
Checking the version

Every response includes:
If you want to assert at request time that you’re hitting the version you expect, check this header in your client.