Documentation
Versioning and deprecation
What you can rely on when you integrate against the Voxplo Agent calling API: how it is versioned, what will never change without notice, and exactly how a deprecation is signalled.
Current version
The API is versioned in the URL path. The current version is v1 and every path is relative to https://api.voxplo.ai/v1. There is no version header to send; the path is the version.
What counts as a breaking change
Breaking changes only ever ship under a new major version (/v2). They are:
- Removing or renaming an endpoint, a request field, or a response field.
- Changing the type or meaning of an existing field, or making an optional request field required.
- Changing an HTTP status code for an existing condition, or an error code string.
- Tightening a guardrail in a way that rejects requests that used to be accepted.
These are not breaking and can appear in the current version at any time. Build clients that tolerate them:
- Adding an endpoint, an optional request field, or a new response field.
- Adding a new enum value where the docs say the set may grow (call status, outcome, error code).
- Adding a response header.
- Raising a limit or a cap.
How a deprecation is announced
When a route or a version is scheduled for removal we announce it at least 90 days before the sunset date, in three places at once: by email to every account holding an agent API key, in the changelog below, and on the API itself, where the deprecated route starts carrying these headers on every response:
| Header | Example | Meaning |
|---|---|---|
Deprecation | Deprecation: @1767225600 | RFC 9745. The moment the route was, or will be, deprecated, as an @ followed by Unix seconds. Present only on deprecated routes, and announced as soon as the date is decided, even if it is in the future. |
Sunset | Sunset: Thu, 01 Apr 2027 00:00:00 GMT | RFC 8594. The date after which the route may stop answering. At least 90 days after the Deprecation date. |
Link | Link: <https://www.voxplo.ai/docs/agent-api/versioning>; rel="deprecation"; type="text/html", <https://api.voxplo.ai/v2/agent/calls>; rel="successor-version" | RFC 8288 relations. rel="deprecation" points at this policy; rel="successor-version" points at the replacement route when one exists. |
The prior version keeps working through the whole sunset window. A route that is not deprecated carries none of these headers, so their presence is the signal: an agent that sees Deprecation on a response should read the Link header and plan the move.
Rate-limit headers
Every /v1/agent response, including a 401, carries the standard rate-limit headers so a client can throttle itself without guessing:
| Header | Meaning |
|---|---|
RateLimit-Limit | Requests permitted per window for this API key (10 per minute by default). |
RateLimit-Remaining | Requests left in the current window. |
RateLimit-Reset | Seconds until the window resets. |
RateLimit-Policy | The policy in one field, for example 10;w=60: ten requests per sixty seconds. |
Retry-After | Only on a 429: seconds to wait before retrying. |
Pinning and staying informed
- Pin the major version in the path and read the
Deprecationheader on every response. - Keep the email on your account current; deprecation notices go to the address on the account that owns the API key.
- The machine-readable spec at /openapi.json carries the version and links this page under
x-versioning-policy. - See the API reference for idempotency, polling and error conventions.
Changelog
- 2026-09-14: Every /v1/agent response now carries RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and RateLimit-Policy, including 401 responses; a 429 carries Retry-After. Deprecated routes will announce themselves with Deprecation, Sunset and Link headers as described here. This page published.
- 2026-06-18: v1 of the Agent calling API: POST /v1/agent/calls, GET /v1/agent/calls/{id}, GET /v1/agent/calls, webhooks, MCP server, Node and Python SDKs.