Skip to main content
The major version is in the path: /v1. Within /v1 the contract changes only additively:
  • new endpoints;
  • new optional query parameters;
  • new fields in responses;
  • new error codes for new situations.
Build your client so these never break it: ignore response fields you don’t know, and handle an unknown error code by its HTTP status.

​
Breaking changes

Anything else is a breaking change: removing or renaming a field or endpoint, changing a field’s type or meaning, adding a value to an existing enum such as status, or making a parameter required. A breaking change gets at least 6 months’ notice on the changelog, with what changes, what you need to do and the earliest date the old behaviour goes away. Where possible it ships as a new major version (/v2) while /v1 keeps working until that date.

​
Where changes are announced

Every published change to the API gets a dated changelog entry. Production and staging change together, and staging is updated first.