Versions and deprecation
The /v1 path, additive changes, deprecation windows.
The major version lives in the path — /v1 — and stays there for the life of that version. Within v1,
only additive changes happen: new operations, new optional request fields, new response fields, new enum
values (on fields documented as open-ended), new error codes, new event types, looser validation. None of
these should break a well-written client — if your code throws on an unrecognized JSON field or enum value,
that's a client-side bug, not a contract break.
Breaking changes wait for v2. When v2 ships, v1 keeps working for at least 12 months, with a
deprecation banner on its docs and a Sunset signal on its responses. Removing or renaming an error code
counts as breaking, same as removing a field.
Where to watch for change: the API reference is generated from the live specs, so it always shows the current contract — don't rely on the API silently staying the same between reads of the same endpoint.
Next: Errors