Versioning
The API’s version is in its path, /v1. Within a version, we only make
changes that don’t break a correctly written integration. The same promise
covers the CLI and the tools agents use, because they’re named after the
API’s operations.
Changes we may make at any time
Section titled “Changes we may make at any time”- New endpoints.
- New optional request parameters and fields.
- New fields in responses.
- New error codes, webhook event types and scopes.
- New commands, and new tools for agents.
Write your integration so these don’t break it:
- Ignore response fields you don’t recognise.
- Treat an error
codeyou don’t recognise asinternal_error. - Branch on
code, never onmessage. - Treat cursors and ids as opaque strings.
Changes we never make within /v1
Section titled “Changes we never make within /v1”- Removing or renaming an endpoint, a field or an operation. That includes the command or agent tool named after it.
- Changing the type or meaning of an existing field.
- Making an optional parameter required.
- Changing how requests authenticate, or which error a given failure returns.
Changes like these only ship in a new version, /v2, which runs
alongside /v1 while integrations move over.
Deprecations
Section titled “Deprecations”Before we retire anything in /v1, we announce it in the changelog,
mark it deprecated in the API reference, and
say what to use instead. Deprecated endpoints keep working for as
long as /v1 exists.