API
API versioning
Path-based versioning, additive change policy, and how we communicate every breaking shift.
The current version is v1. Non-breaking changes (new endpoints, new optional fields, new enum values) are introduced within v1. Breaking changes get a new major version with at least 12 months of overlap.
What we consider breaking#
- Removing or renaming a field
- Changing the type of an existing field
- Making an optional field required
- Changing the meaning of an existing enum value
What we consider additive (non-breaking)#
- New endpoints
- New optional fields in responses or requests
- New event types
- New enum values in existing fields
Build your enum handling defensively — treat unknown values as unrecognised and surface them gracefully rather than crashing.