Versions and changes
What we may change at any time, what counts as a breaking change, and how much notice you get before one.
The API version is in the path: /api/v1/. Within a version, a change never
breaks a client that follows the rules on this page. A breaking change gets
notice first, and the old behaviour keeps working until the date in that notice.
Changes we make at any time
These are not breaking. They appear in the changelog, with no notice period.
- A new endpoint, or a new method on an existing path.
- A new field in a response body, a webhook payload or the changes feed.
- A new optional request field or query parameter.
- A new value in an enum: a status category, an activity action, a webhook
event type, an error
code. - A new response header.
- A better error
message. Thecodeis the contract; the message is for people.
So a client must ignore fields and enum values it does not know. It must not fail on them.
Breaking changes
- An endpoint, field, query parameter or enum value is removed or renamed.
- A field changes type or format: a number becomes a string, a date gets a time.
- An optional request field becomes required, or a default changes.
- A request that worked starts to fail: new validation, a new required scope.
- A webhook payload loses or renames a field, or an event stops being sent.
How a breaking change is made
- The new form ships first, next to the old one. A new field next to the
old field, a new endpoint next to the old endpoint. When that is not
possible, the whole change waits for the next version (
/api/v2/). - The old form is marked. Every response from a deprecated endpoint or
field carries the
Deprecationheader (RFC 9745) and aSunsetheader (RFC 8594) with the date it stops. The reference marks it deprecated. - You are told. The changelog lists it, and the owner of every active API token and webhook endpoint in the affected workspaces gets an email.
- The old form keeps working for the notice period:
| Change | Notice |
|---|---|
| A field, enum value, parameter or endpoint inside a version | 90 days |
A whole version (/api/v1/ after /api/v2/ ships) | 12 months |
The exception: security
A change that closes a security hole can ship at once, with the notice sent the same day. Example: a field that showed data a token should never have read.
Webhooks
Payloads follow the same rules. A new field or event type can arrive at any time, so a receiver must ignore what it does not know. A breaking change to an event ships as a new event type next to the old one, and the old one is sent for the notice period.