Quickstart
withWorkspace / with_workspace sends the Thinnest-Workspace header on every request (see
Customers). To fix one workspace for a whole client, pass
workspace: "org_…" (TypeScript) or workspace="org_…" (Python) when you create it.
How methods are named
One namespace per group in this reference —agents, calls, customers, phoneNumbers
(phone_numbers in Python), webhooks, … — and a method per endpoint, named for what it does:
client.agents.list(), client.calls.place(…), client.customers.restore(id).
- Path parameters come first, then the request body.
- TypeScript takes query parameters as an object after the body, then
RequestOptions(idempotencyKey,headers,signal,timeoutMs,maxRetries). - Python takes query parameters as keyword arguments (
client.calls.list(status="completed")), plusextra_headers=,timeout=and, where the endpoint accepts one,idempotency_key=. - Binary answers (call recordings, voice previews) come back as a
Blob/bytes; text answers (a transcript as text, a CSV export) as a string.
Pagination
List endpoints answer one page,{ items, nextCursor }. Each has a companion that walks every page:
Errors
Any answer outside2xx raises ApiError, carrying status, message (the error sentence
from the error body), the response headers and the parsed body. No
answer at all — the network failed or the request timed out — raises ApiConnectionError.
Retries and idempotency
The clients follow the retry policy for you:429is retried, waiting forRetry-After.408,500,502,503,504and network errors are retried forGET,PUTandDELETE, and for aPOSTorPATCHonly when it carries anIdempotency-Key.- Backoff is exponential with jitter, capped at 8 seconds; two retries by default (
maxRetries/max_retries). - Endpoints that accept an
Idempotency-Key— placing a call, a batch of calls — get one generated when you give none, and the same key is sent on every retry, so a retry never places a second call. 400,401,403,404and409are never retried.