StateSet API Docs

Interactive documentation is served by the running instance at /swagger-ui, with the OpenAPI 3.0 document at /api-docs/openapi.json.

Every tenant endpoint below also has a generated reference page with a live playground under the Voice API tab — 65 operations, built from the OpenAPI document the server publishes. This page is the narrative map; use the tab to make calls.

Service

Endpoint	Purpose
`GET /`	Service metadata, timestamp, org id
`GET /health`	Health information, active sessions, uptime
`GET /health/live`	Kubernetes liveness probe
`GET /health/ready`	Kubernetes readiness probe
`GET /metrics`	Prometheus metrics
`GET /swagger-ui`	Interactive OpenAPI documentation
`GET /api-docs/openapi.json`	OpenAPI 3.0 specification

Calls

Endpoint	Purpose
`POST /make-call`	Place an outbound call via Twilio REST
`POST /voice/web-calls`	Mint a signed browser voice session
`POST /call-status`	Twilio status callbacks, signature-validated
`GET /media-stream` (WebSocket)	Twilio media bridge

POST /make-call supports an Idempotency-Key with 24-hour replay protection, a transient per-call config (custom tools included) for prototyping, and persisted metadata.

Browser calls run the same media protocol and pipeline as phone calls, so anything configured for telephony — agents, tools, transfers, evals — applies unchanged.

Media stream authentication

The WebSocket handshake authenticates a tenant by Authorization: Bearer … or a short-lived signed ?stream_token=….

Raw tenant-token query transport is opt-in via LEGACY_QUERY_AUTH_ENABLED=true and exists for migration only. It defaults to off. Configure STREAM_AUTH_SECRET to issue signed stream_token values instead.In NODE_ENV=production, startup fails fast if legacy auth is off and STREAM_AUTH_SECRET is not configured — so you cannot accidentally deploy with neither.

# Place a call. POST /voice/calls is the same flow with idempotency and retries.
curl --request POST "https://api.voice.stateset.com/api/v1/make-call" \
  --header "Authorization: Bearer $STATESET_VOICE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "agent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "to": "+14155550123"
  }'

Translation calls

A translation call bridges two people who do not share a language: the platform dials both, and each hears the other translated in near real time.

Endpoint	Purpose
`POST /voice/translation-calls`	Dial both participants into a translated room
`GET`/`POST` `/translation-call-intake/start`	Start one from an inbound intake flow
`GET`/`POST` `/translation-call-leg`	Twilio leg callback
`GET /translation-media-stream` (WebSocket)	The bridged media path

curl --request POST "https://api.voice.stateset.com/api/v1/voice/translation-calls" \
  --header "Authorization: Bearer $STATESET_VOICE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "participant_a": "+15551230001",
    "participant_b": "+15551230002",
    "language_a": "en",
    "language_b": "es"
  }'

Response

{
  "ok": true,
  "room_id": "8f1f7d28-0ea9-4531-95d7-8d8f0fd72516",
  "participant_a_call_sid": "CA123",
  "participant_b_call_sid": "CA456"
}

language_a and language_b default to en and es. Omitting them does not mean “detect the language” — it means English and Spanish. A call between two other languages that leaves them out will be translated into a pair neither participant is speaking.

ok: true means both legs were placed, not that both were answered — the call_sid values are how you follow each leg’s actual outcome. When Twilio is not configured the response carries error instead of the sids.

Sessions and supervision

Endpoint	Purpose
`GET /sessions`	Enumerate active sessions
`POST /sessions/:id/actions/:action`	Supervisor action
`GET /logs` (WebSocket)	Real-time broadcast logs

Supervisor actions: monitor, whisper, barge, escalate, end.

# Whisper to the agent mid-call without the caller hearing it
curl --request POST "%(b)s/voice/sessions/$STREAM_SID/actions/whisper" \
  --header "Authorization: Bearer $STATESET_VOICE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "message": "Offer the replacement, not the refund." }'

Supervisor actions address a session by its stream_sid, not the call record id — a live session and its call log are different handles for the same call. Take the stream_sid from GET /voice/sessions; a supervisor action sent with a call id silently addresses nothing.

Functions and automations

Endpoint	Purpose
`GET /tools`	Function registry definitions, for OpenAI tool priming
`POST /test-function`	Execute a function manually with a JSON payload
`POST /automations/...`	Automation endpoints backed by the function registry

Human handoff

/transfer-call dials a human with a bounded ring timeout (twilio.human_agent_timeout_seconds, default 25s). If nobody answers, /transfer-complete reconnects the caller to the AI with a message-taking greeting rather than Twilio’s default hangup. A failed background escalation likewise speaks a recovery prompt — counted by escalation_bridge_failed_total — instead of leaving the caller on a silent line.

Admin

Admin routes require ADMIN_API_KEY, passed as x-admin-key.

Endpoint	Purpose
`GET /admin/sessions`	Active sessions across cached tenants
`GET /admin/auth/transport`	Auth transport diagnostics
`GET /admin/alerts/auth-transport`	Rollout alert evaluation — `ok`/`warn`/`error` with alert codes
`GET /admin/tenants/cached`	Cached-tenant runtime summary
`GET /admin/tenants/audio-providers`	Configured vs effective audio provider, fallback state and reason
`GET /admin/tenants/cache-metrics`	Entries, hits, misses, reloads, evictions
`GET /admin/tenants/cache-metrics/by-token`	Top token-level cache counters
`POST /admin/tenants/reload-cached`	Reload cached tenants, preserving live session and log state
`POST /admin/tenants/evict-idle`	Evict idle cache entries (`max_idle_secs`)
`GET /admin/twilio/webhook-diagnostics`	Tenant-resolution diagnostics — hint-cache size, counters, hit rates
`POST /admin/twilio/webhook-diagnostics/cache/clear`	Clear hint-cache entries for incident recovery
`POST /admin/twilio/webhook-diagnostics/counters/reset`	Reset diagnostics counters

GET /metrics on the main port requires x-admin-key. The dedicated METRICS_PORT is unauthenticated and must be network-restricted.

Admin tenant responses redact secrets, and updates can preserve existing values by sending the <redacted> placeholder. Tenant reads expose deterministic config ETags, so writes can use If-Match to avoid lost updates.

Next steps

Configuration

Tenant settings, audio providers and turn behaviour.

Webhooks

Signature verification, shared with custom tool calls.

Voice SDKs

TypeScript, Python and the browser Web SDK.

Quickstart

First agent, number and call, end to end.

Last modified on August 31, 2026

Get started

Platform

Using the APIs

StateSet Response

StateSet ResponseCX

Temporal Engine

StateSet iCommerce Engine

StateSet iCommerce EDI Engine

StateSet Mail

StateSet iCommerce Voice Engine

StateSet iCommerce NSR Engine

AI Agents

StateSet Agents

StateSet iCommerce Sandbox Engine

StateSet ACP

StateSet UCP

StateSet ICP

StateSet Sequencer

StateSet Set L2

StateSet Cloud

Apps & Consoles

Tools

Voice API

Service

Calls

Media stream authentication

Translation calls

Sessions and supervision

Functions and automations

Human handoff

Admin

Next steps

Configuration

Webhooks

Voice SDKs

Quickstart

​Service

​Calls

​Media stream authentication

​Translation calls

​Sessions and supervision

​Functions and automations

​Human handoff

​Admin

​Next steps

Configuration

Webhooks

Voice SDKs

Quickstart

Service

Calls

Media stream authentication

Translation calls

Sessions and supervision

Functions and automations

Human handoff

Admin

Next steps