The API can change without notice. We aim to keep it stable, and we will try to warn you before a change that could break your tool. We cannot promise that. Build your tool so that a change fails loudly and you notice it.
What we aim for
We aim to change v1 only by adding things:
- new endpoints;
- new optional query parameters;
- new fields in a response;
- new values in a list of allowed values (an enum).
None of these should break a tool that follows the rules below.
- Ignore fields you do not know. A response can gain fields at any time.
- Treat an unknown enum value as “other”. For example, a new event
type should not crash your tool.
- Check for a field before you read it. Fields that a key’s scopes do not allow are left out.
- Check the status code of every response. Fail loudly on an error. Do not quietly write an empty sheet.
- Branch on the error
code, never on the message.
Where changes are listed
Every change to the API is in the changelog. The version of the API document (info.version in the OpenAPI file) goes up with each change.
Beta
The API is in beta. While it is in beta, changes may come more often. Tell us what you build and what breaks: contact us.