Versioning

The API is versioned in its path: /v1. Within a version we only make changes that do not break a correct integration — and the same promise covers the command line and agent tools built from the API, whose 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, new webhook event types, new scopes.
• New commands and tools for the command line and agents.

Build your integration to tolerate these:

• Ignore response fields you do not recognize.
• Treat an unknown error code like 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 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 ships only in a new version (/v2), served alongside /v1 while integrations move.

Deprecations

Before anything in /v1 is retired, it is announced in the changelog and marked deprecated in the API reference, with the replacement to use. Deprecated endpoints keep working for the life of /v1.