Skip to navigation
Reference

API versioning & deprecation

View as Markdown

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 and announced in the changelog;
  • responses from a deprecated endpoint carry a Deprecation header (RFC 9745) and a Sunset header (RFC 8594) 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 and SDKs 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.