Versioning and Deprecation

URL Major Versioning

Public API routes are versioned in the URL. The first public major is /api/v1/:

https://api.voiceagent.example/api/v1/agents

API keys are version-neutral. A vak_ key authenticates the workspace; the URL path selects the API major.

Legacy Path Sunset

Legacy unversioned public paths such as /api/agents are compatibility aliases only. They are scheduled to sunset on 2026-11-04.

Responses on legacy public aliases include deprecation headers:

Deprecation: true
Sunset: Sun, 04 Nov 2026 00:00:00 GMT

New partner integrations should use /api/v1/ and should not build against unversioned /api/... paths.

Deprecation Policy

Tier A public API breaking changes require at least 183 calendar days of notice. During the notice period, deprecated behavior remains available unless an approved security, legal, abuse, vendor-shutdown, or data-integrity exception applies.

A breaking change includes removing or renaming documented paths, fields, statuses, error codes, authentication requirements, the error envelope, or the pagination contract.

Header Mechanics

Deprecation responses use the standard Deprecation header from RFC 9745 and the Sunset header from RFC 8594. Future formal deprecations should also include a Link header to migration or changelog documentation.

Deprecation: @1780272000
Sunset: Tue, 01 Dec 2026 00:00:00 GMT
Link: <https://api-docs.voiceagent.example/changelog.html>; rel="deprecation"; type="text/html"

Changelog

The public changelog will record release notes, deprecations, sunset dates, replacements, and breaking-change notes. See Changelog.