Solved Docs

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