Versioning

The v2 API is versioned as v2.MINOR.PATCH. The /v2 in the URL is the major version and is what your integration targets; it does not change between releases. The minor and patch numbers identify individual releases and are what the release notes are organised by.

What a release number means

• Patch (v2.6.15 → v2.6.16): fixes and behaviour improvements. Nothing you have to do.
• Minor (v2.5.x → v2.6.0): new capabilities, such as new endpoints, fields or webhook events. Existing calls keep working.
• Major (v1 → v2): a new API surface with its own base path. The previous major keeps running while you migrate; see the migration guide.

Changes we consider compatible

Your integration should tolerate these without a code change; they can appear in any release:

• New endpoints, and new optional request parameters or body fields
• New fields in responses and webhook payloads
• New values in enumerations such as bot status codes, error codes and webhook event types
• New webhook events (your handler should ignore events it does not recognise)
• Changes to the order of fields in a JSON object
• More specific error messages behind an unchanged HTTP status and error code

Changes we consider breaking

• Removing or renaming an endpoint, request parameter, response field or webhook event
• Changing a field's type, format or meaning
• Making an optional parameter required, or tightening validation so that previously accepted requests are rejected
• Changing the HTTP status or error code returned for an existing condition
• Changing authentication or rate-limiting rules in a way that rejects previously valid traffic

Every release carries a Breaking Changes section in its notes. When it is not "None", the entry says what changed, who is affected and what to do, and the release is flagged on the releases timeline.

Deprecations

When something is going away, it is announced under Deprecations in the release notes of the version that deprecates it, together with the replacement to use. The deprecated behaviour keeps working until the release that removes it, which lists the removal under Breaking Changes.

Staying informed

• The releases page reads the release notes straight from GitHub, so it reflects a new version within minutes of it shipping.
• The API reference and the OpenAPI specification always describe the currently deployed version.
• The TypeScript SDK is versioned independently of the API; SDK releases follow API releases that add or change surface.