Versioning
What counts as a breaking change, and how changes to /v1 are announced.
The API is versioned by its path. Everything documented here is /v1.
What we change without a new version
These are not breaking, and can ship to /v1 at any time:
- a new endpoint;
- a new optional request field;
- a new field in a response;
- a new value in an enum you read (write your client to tolerate unknown values);
- a new event type on webhooks.
Write your client to ignore fields it does not know.
What counts as breaking
A change is breaking when a request that worked before can fail after it — a removed or renamed field, a field that becomes required, a narrower accepted format. Every breaking change is listed in the changelog with its date and exactly what to change. A breaking change is announced, never discovered.
The OpenAPI document
/docs/openapi.json is generated from the same schemas the API validates requests and serializes responses with, so it cannot drift from what the API does. It is safe to generate a client from it.