Versioning
How the v1 API changes, what counts as breaking, and how deprecations are announced.
The API version is part of the path: every endpoint lives under /api/v1. Within v1 we only make additive changes, following Google AIP-180. Code you write against v1 today keeps working.
Changes we may make inside v1
These are not breaking, so build your client to accept them:
- New endpoints and new optional request parameters or body fields.
- New fields in response bodies and webhook payloads.
- New values in enums that are documented as open (for example call outcomes or
endedReason). - New error codes, always within the existing error types.
- New webhook event types (you only receive events you subscribe to).
- New response headers.
Write tolerant clients
Ignore JSON fields you do not recognise, handle unknown enum values with a sensible default, and switch on error.type before error.code.
Changes we never make inside v1
- Removing or renaming a field, parameter or endpoint.
- Changing a field's type or meaning.
- Making an optional field required, or tightening validation on existing input.
- Changing the status code an endpoint returns for a given outcome.
A change like that would ship as a new major version (/api/v2), with v1 kept running alongside it.
Pre-GA changes (2026-11-15)
Before the public API reached general availability, one release on 2026-11-15 made breaking changes inside v1. Examples: new dedicated error codes with corrected status codes, the WhatsApp API moving to /api/v1/whatsapp, and API keys losing access to /auth/*. The changelog lists every change and what to update. The rules above apply to every release after that one.
/platform/v1
/platform/v1 is not part of the public API. API keys are refused there with 403 api_key_route_forbidden. Use /api/v1.
Deprecation
If we ever retire an endpoint or the alias, we will:
- Announce it on this site, on the affected reference pages.
- Add the
Deprecation: trueand RFC 8594Sunset: <HTTP-date>response headers to the affected endpoints. - Keep it working for 12 months after the
Sunsetheader first appears.
No endpoint is deprecated today, so no response carries these headers yet. Logging any Sunset header you receive is a cheap way to get early warning.