Versioning
The version is in the URL. v1 only changes in ways that don't break a careful client.
Base URL: /api/v1. Webhook bodies carry "apiVersion": "v1".
What can change in v1
- New endpoints, new optional parameters, new response fields.
- New values in lists that aren't closed:
kind,source,decidedVia, a new event type. - The wording of
message, titles and texts.
So ignore fields you don't know, treat an unknown value as "other", and branch on code, not message.
What can't
- Removing or renaming a field, endpoint, parameter or error code.
- Changing a field's type or meaning.
- Tightening what a request accepts, except to close a security hole.
A breaking change ships as /api/v2. v1 keeps running for at least 6 months after that, with notice to the owner of every key in use.
Where changes are announced
In the changelog. The OpenAPI document is always the current contract.