Quickstart
withWorkspace / with_workspace sends the Thinnest-Workspace header on every request (see
Customers). The customers.* methods and usage.getCustomers ignore it, because those endpoints are always
called as you, never as one of your 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 for every method, waiting forRetry-After(up to 120 seconds; a longer wait is thrown rather than retried early).408,500,502,503,504and network errors are retried only forGETandHEAD, and for any request sent with anIdempotency-Key. APOST,PUT,PATCHorDELETEwithout one is never replayed, because replaying it could act twice.- Backoff is exponential with jitter, capped at 8 seconds; two retries by default (
maxRetries/max_retries). - These get an
Idempotency-Keygenerated when you give none:calls.place,calls.placeBatch,conversations.reply,messages.send,codes.send,customers.createandphoneNumbers.rent. The same key is sent on every retry, so a retry never places a second call. A key you pass — as theidempotencyKeyoption or theidempotencyKeybody field — is the one sent. 400,401,403,404and409are never retried.