Skip to Content
CallMitraDocs

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:

  1. Announce it on this site, on the affected reference pages.
  2. Add the Deprecation: true and RFC 8594 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.

On this page