Skip to main content
The API is at /v1. Its changes are of two kinds. Additive changes are made without notice. A new field, endpoint, query parameter or event type can appear at any time, and is recorded in the changelog. So a client must ignore fields, event types and enum values it does not know. A client that fails on an unknown field breaks on a change that was never a break. A breaking change is a new version. Removing or renaming a field, changing a type or a meaning, or removing an endpoint ships as /v2. /v1 is never changed in a breaking way.

​
Deprecation and sunset

/v1 lives at least 12 more months after /v2 is announced. From the announcement, /v1 answers with a Deprecation header (RFC 9745). Once the shutdown date is set, it answers with a Sunset header (RFC 8594) carrying that date. Watch for both in your client and log them where somebody will read them:

​
Field groups are part of the contract

Which field group opens which field is part of the contract. A new field joins the group that fits it, so a key never starts reading a group it was not given. See Field groups.