API reference

The TelVox Connect REST API lets you place and control calls, manage recordings, route through queues and conferences, assign numbers and subscribe to lifecycle events — all over HTTPS with JSON. This page covers the base URL, authentication, errors, pagination and rate limits, then indexes every resource.

Developer previewConnect is in developer preview. Every endpoint, field, enum and JSON sample in this reference is illustrative — it conveys shape, not a finalized contract, and may change before general availability. Watch the changelog for breaking changes.

Base URL

All requests go to a single host over HTTPS. Paths are flat and versioned by the leading /v1 segment; HTTP is not accepted.

base URL

illustrative

https://api.telvox.dev/v1

Authentication

Authenticate every request with an API key passed as a Bearer token in the Authorization header. A key is conceptually a SID plus a secret; treat it like a password, keep it server-side, and never ship it to a browser or mobile client. For browser and mobile WebRTC, your server mints a short-lived access token instead. See the authentication concept for the full key model. Self-serve key issuance is on the roadmap; in the preview, sandbox credentials are provisioned with the TelVox team.

GET/v1/calls

illustrative

# illustrative — shape may differ at GA
curl https://api.telvox.dev/v1/calls \
  -H "Authorization: Bearer $TELVOX_API_KEY"

200 ok

Errors & status codes

Connect uses conventional HTTP status codes and returns a consistent JSON error envelope on every failure. The request_id is the fastest way for us to trace a problem, so capture it in your logs.

error response

illustrative

// illustrative — shape may differ at GA
{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "The 'to' parameter must be a valid E.164 number.",
    "param": "to",
    "status": 400,
    "request_id": "req_3kf9c2a1ze"
  }
}

400 bad request

Field	Type	Description
type	string	Broad class of error — e.g. invalid_request_error, authentication_error, rate_limit_error, api_error.
code	string	Stable machine-readable code for the specific failure (e.g. parameter_invalid).
message	string	Human-readable explanation, safe to log. Not intended for end users.
param	string	Present on validation errors — the request parameter that caused the failure.
status	integer	The HTTP status code, mirrored in the body for convenience.
request_id	string	Identifier for this request. Include it when contacting support.

Status codes

Code	Meaning
200 OK	The request succeeded.
201 Created	A resource was created (e.g. a call was placed).
202 Accepted	The request was accepted for asynchronous processing.
204 No Content	The request succeeded and there is no response body (e.g. a delete).
400 Bad Request	A parameter was missing, malformed, or invalid.
401 Unauthorized	The API key was missing, revoked, or invalid.
403 Forbidden	The key is valid but not permitted to perform this action.
404 Not Found	No resource exists at the requested path or SID.
409 Conflict	The request conflicts with the current state of the resource.
422 Unprocessable Entity	The request was well-formed but failed a semantic validation.
429 Too Many Requests	A rate or concurrency limit was exceeded — back off and retry.
500 Server Error	Something went wrong on our side; the request_id helps us trace it.

Pagination

List endpoints return a paginated object. Use limit to set the page size (default 50, max 100) and cursor the results with starting_after / ending_before, passing a SID or the next_cursor from the previous page. When has_more is false you have reached the end.

list response

illustrative

// illustrative — shape may differ at GA
{
  "object": "list",
  "url": "/v1/calls",
  "has_more": true,
  "next_cursor": "cur_9aZ2k1Qp",
  "data": [
    { "object": "call", "sid": "CA8f0e1d…" }
  ]
}

200 ok

Rate limits

Requests are rate limited per API key, and outbound call placement is additionally governed by a calls-per-second (CPS) concurrency cap scoped to your account. Both protections surface as 429 Too Many Requests; inspect the rate-limit headers and honor Retry-After with exponential backoff. The exact limits are set per account during the preview — talk to the team about higher ceilings.

Header	Type	Description
X-RateLimit-Limit	integer	The request ceiling for the current window on this key.
X-RateLimit-Remaining	integer	Requests left in the current window.
X-RateLimit-Reset	integer	Unix epoch seconds when the window resets.
Retry-After	integer	On a 429, the number of seconds to wait before retrying.

Resources

Each resource has its own reference page with properties, endpoints, language-tabbed samples and callback sub-sections.