Skip to content

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.

  • 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.
  • Branch on code, never on message.
  • Treat cursors and ids as opaque strings.
  • 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.

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.