# Versioning (/versioning)

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](https://google.aip.dev/180). Code you write against v1 today keeps working.

## Changes we may make inside v1 [#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](/errors).
- New webhook event types (you only receive events you subscribe to).
- New response headers.

<Callout title="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`.
</Callout>

## Changes we never make inside v1 [#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) [#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](/changelog) lists every change and what to update. The rules above apply to every release after that one.

## `/platform/v1` [#platformv1]

`/platform/v1` is not part of the public API. API keys are refused there with `403` [`api_key_route_forbidden`](/errors/api_key_route_forbidden). Use `/api/v1`.

## Deprecation [#deprecation]

If we ever retire an endpoint or the alias, we will:

1. Announce it on this site, on the affected reference pages.
2. Add the `Deprecation: true` and [RFC 8594](https://www.rfc-editor.org/rfc/rfc8594) `Sunset: <HTTP-date>` response headers to the affected endpoints.
3. Keep it working for **12 months** after the `Sunset` header 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.