> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.getdial.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.getdial.ai/_mcp/server.

# API versioning & deprecation

> How the Dial REST API is versioned, what counts as a breaking change, and how much notice you get before anything is removed.

Agents integrate with Dial once and then run unattended, so the REST API makes a promise about when it can change underneath you and how you will hear about it.

## Versioning

The API version is part of the URL path. Every endpoint lives under `/v1` (`https://api.getdial.ai/v1/...`). There are no version headers and no dated versions to pin: the path is the version.

Within `/v1` we only make **backward-compatible** changes:

* adding a new endpoint, or a new optional request field or query parameter;
* adding a field to a response object (ignore fields you don't recognize);
* adding a new event type, error code, or enum value (handle unknown values gracefully);
* adding a response header.

A **breaking** change (removing or renaming an endpoint or field, changing a field's type or meaning, making an optional input required, changing an existing error code) is never made to `/v1` in place. It ships under a new version (`/v2`), and `/v1` keeps working through the deprecation window below.

## Deprecation

When an endpoint or field is deprecated:

* it is marked deprecated in the [API reference](/api-reference/rest-api) and announced in the [changelog](/documentation/changelog);
* responses from a deprecated endpoint carry a `Deprecation` header ([RFC 9745](https://www.rfc-editor.org/rfc/rfc9745)) and a `Sunset` header ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594)) with the date it stops working, plus a `Link` header with `rel="deprecation"` pointing at the migration notes;
* it keeps working for **at least 6 months** after the deprecation is announced. The `Sunset` date is never earlier than that.

Nothing in `/v1` is deprecated today.

The [CLI](/documentation/cli/install-and-onboarding) and [SDKs](/documentation/sdks/overview) follow the same rule: a breaking change to a command, flag, or method ships in a new major version, and the previous major keeps working against the API for the same window.

## Long-running requests

A request that finishes its work after responding returns `202 Accepted` with the resource it started and a `Location` header pointing at where to read its progress. Today that is provisioning an iMessage number: `POST /v1/numbers` returns `202` with the number in `setupStatus: provisioning` and `Location: https://api.getdial.ai/v1/numbers/{id}`. Poll that URL, or wait for the `number.status_changed` event, until `status` is terminal.