Skip to main content

​
Versioning

The API is versioned in the URL path. v1 is the current and only version:
  • Breaking changes ship as a new version path (/v2), never inside v1. A breaking change is anything that removes an endpoint or field, renames one, changes a type, tightens validation on existing input, or changes the meaning of an existing response value.
  • Additive changes land in v1 without notice: new endpoints, new optional request fields, new response fields, new enum values on fields documented as extensible. Build clients that ignore unknown response fields.

​
Deprecation policy

When an endpoint, parameter, or field is deprecated:
  1. It is marked deprecated: true in the OpenAPI specification — the spec is the source of truth.
  2. The deprecation is announced in the changelog.
  3. When an endpoint is scheduled for removal, its responses will carry a Deprecation header, and once a removal date is committed, a Sunset header (RFC 8594) with the removal timestamp. No endpoint is deprecated today, so no live response currently carries these headers.
  4. The deprecated surface keeps working alongside its replacement for at least 90 days after the Sunset date is announced. Nothing is removed silently.
An example already live today: phone_number_id on POST /projects is deprecated in favor of phone_number_ids[]; both are accepted while the migration window is open.

​
What agents should do

  • Check the spec’s deprecated flags before generating integration code; prefer the replacement surface whenever one is documented.
  • Watch for Deprecation and Sunset response headers and surface them to a human operator.
  • Treat unknown response fields as additive evolution, not an error.