API Principles

Breaking Changes

We do our absolute best to avoid breaking changes in our API. However, sometimes we need to make changes to our API that will break existing clients. Here’s how we recommend thinking about breaking changes from us:

  1. Endpoints marked as Beta are subject to breaking changes without notice.
  2. Endpoints marked as Available or Deprecated are generally not subject to breaking changes, only being done in rare cases when no other options exist.
  3. Any breaking changes that we do make will be clearly documented in the Breaking Changes page in our API documentation along with a date, so there is always a historical record.
  4. We try to notify you of breaking changes as early as possible. We do this by sending an email to a breaking changes email list we keep. If you would like to be added to this list, please contact our Support team.

What is a breaking change

We consider a break any change that meets one of the two following criteria:

  • A schema change to a request shape that leads to a previously valid client request shape becoming invalid.
  • A schema change to a response shape that leads to a previously valid client response parser becoming invalid.

Here are some examples of changes that we consider non-breaking:

  • Adding a new field to an existing response shape
  • Making a required field on a request shape optional
  • Removing an optional field on a response shape

Here are some examples of changes that we consider breaking:

  • Removing a required field on a response shape
  • Changing the data type of a field

A note on enums and unions

Enums and unions are types in our API that represent a set of possible types. A single type is called an enum member or union member.

We consider adding enum and union members to request and response shapes to be non-breaking. Clients are expected to write integration code that handles unknown enum and union members gracefully.

We consider removing enum and union members from response shapes to be non-breaking. Clients that handle more cases than we document should not be broken by this change.

We only consider removing enum and union members from request shapes to be breaking.

Built with