Versioning and deprecation
The API version is part of the URL: https://api.oryvox.ai/v1. Within /v1 we only make
API version
The API version is part of the URL: https://api.oryvox.ai/v1. Within /v1 we only make
backwards-compatible changes:
- adding endpoints, optional request fields, response fields, headers, event types,
error
types and models; - changing the order of JSON keys, the length of ids, or the content of error
messages.
Build clients that ignore unknown fields and events. Breaking changes ship as a new version
(/v2), and /v1 keeps working for at least 12 months after /v2 is released.
Every /v1 response carries X-Oryvox-Api-Version (currently 2026-10-04), the date of the
API release that answered it. Log it with your errors.
Deprecations
When an endpoint is scheduled for removal it gets a deprecated_at date, a sunset_at date at
least 6 months later and, usually, a replacement. Every response from it then carries:
Deprecation: @1798761600
Sunset: Wed, 30 Jun 2027 00:00:00 GMT
Link: <https://api.oryvox.ai/v1/responses>; rel="successor-version"Deprecation (RFC 9745) is the Unix time the endpoint was deprecated; Sunset (RFC 8594) is
when it stops working; Link points at the replacement. Deprecations are also announced in
the changelog. No endpoint is deprecated today.
Notice periods:
| Item | Minimum notice before sunset |
|---|---|
API version (/v1) | 12 months |
| Endpoint or parameter | 6 months |
| Model retired by its provider | As much as the provider gives; routing profiles move to the replacement automatically. |
Routing profiles (oryvox-*) never break when models are retired: they route to the
replacement. Pinned model ids fail with 404 model_not_found once the model is removed from
GET /models, so prefer profiles for long-lived code.
SDK versions
The SDKs follow semantic versioning. A new major SDK version is released only for breaking changes to the SDK's own interface or for a new API version. Each SDK release lists the API features it supports in the changelog.