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 command line and the tools agents use, because their names come from the API’s operations.

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 code you don’t recognise as internal_error, and branch on code, never on message.
• Treat cursors and ids as opaque strings.

Changes we never make within /v1

• Removing or renaming an endpoint, a field or an operation, and so a command or an agent’s tool.
• 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.

A change like these only ships in a new version, /v2, which runs alongside /v1 while integrations move over.

Deprecations

Before we retire anything in /v1, we announce it in the changelog and mark it deprecated in the API reference, with what to use instead. Deprecated endpoints keep working for as long as /v1 exists.