Docs · API Policy

Versioning & Deprecation

What you can build on without watching us: how the API is versioned, how you find out about changes before they affect you, and how long a deprecated operation keeps working.

Versioning

The API is versioned in the URL path. Every endpoint lives under the /v1 segment:

https://sonicvox.ai/api/v1/text-to-speech
https://sonicvox.ai/api/v1/voices
https://sonicvox.ai/api/v1/account/webhooks

Breaking changes ship only in a new version path. Within /v1, a response field never changes meaning or disappears, a required parameter is never added, and an error's type/code contract stays as the error catalog documents it. Additive changes — new endpoints, new optional parameters, new response fields, new error codes, new webhook event types — arrive inside /v1 and are announced in the changelog. Write clients that ignore fields they don't recognize.

Deprecation

When an operation is deprecated, it is announced in the changelog and — from the moment it is marked — announces itself in-band on every response, per RFC 8594:

Deprecation: true
Sunset: Sat, 28 Nov 2026 00:00:00 GMT   (example — an HTTP-date 90 days out)
  • •Deprecation: true is set on the operation's responses, alongside the rate-limit headers — check for it on your successful calls.
  • •Sunset carries the earliest date the operation may be removed, as an HTTP-date, set 90 days from the moment the operation was marked deprecated. Until that date the operation keeps working unchanged — deprecation adds headers, it does not degrade behaviour.
  • •After removal, calls to the retired path return unknown_endpoint (404).

The practical move: log a warning whenever a response you receive carries Deprecation: true, and alert on the Sunset date. That single check means you hear about every deprecation that touches your integration without reading a word of ours.

Not the same thing: disabled endpoints

An operationally disabled endpoint (maintenance, incident response) returns endpoint_disabled (503) and comes back when the condition clears. It carries no Sunset and implies nothing about the operation's future — do not treat a 503 as a deprecation, or a deprecation as an outage.

Webhook payload versioning

Webhook deliveries carry their own schema version in the envelope's version field (currently 2026-07-11). It is bumped only when a payload field changes meaning; receivers can branch on it to handle old and new shapes side by side.