Versioning
How the API changes, and what stays stable.
The API's major version is part of every path: /api/v1. These docs describe version 1.
What can change within v1
Expect these additions to v1 at any time, without notice:
- New endpoints.
- New optional request fields and parameters.
- New fields in responses.
- New values in fields that list values, such as
status,failureCodeor event types. - New webhook event types. An endpoint subscribed to
*starts receiving them.
Write your client to ignore an unknown field, and to skip an unknown value or treat it as a failure, never to crash on it.
What needs a new version
Anything that could break your client comes only in a new major version, such as /api/v2:
- Removing or renaming an endpoint, field or value.
- Making an optional field required.
- Changing what a field means or its type.
When a new version comes out, your version keeps working. Pick a version's docs from the version menu.