StateSet API Docs

The end-to-end path: mint a key, configure a tenant, create an agent with a custom tool, attach a phone number, register a webhook, place a test call, and watch it live.

Prerequisites

A running voice server — see Overview for the Docker Compose stack
Twilio credentials and a phone number
An OpenAI key (and an ElevenLabs key if you want its TTS)

Everything below runs against https://api.voice.stateset.com/api/v1, or http://localhost:5050/api/v1 against a local server.

1. Mint a tenant API key

Tenant credentials are the unit of access. Every subsequent call uses one as a Bearer token. Create your first key in the console; after that, a key can mint further keys for itself:

curl --request POST "https://api.voice.stateset.com/api/v1/api-keys" \
  --header "Authorization: Bearer $STATESET_VOICE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "name": "front-desk-prod" }'

Response

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "front-desk-prod",
  "token": "stsk_acme_01H8_9f2c…"
}

export STATESET_VOICE_API_KEY="stsk_acme_01H8_9f2c…"

The key is returned once. Store it before moving on — it can be revoked and reissued, not retrieved.

2. Configure the tenant account

Set the tenant’s provider credentials and defaults — audio output provider, VAD tuning, and handoff workflow. See Configuration.

curl --request PATCH "https://api.voice.stateset.com/api/v1/voice/account" \
  --header "Authorization: Bearer $STATESET_VOICE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "greeting": "Thanks for calling Acme Dental. How can I help?",
    "handoff_number": "+14155550100"
  }'

3. Create the agent

An agent version carries its prompt, model settings, and tools[]. Each tool is a JSON-schema function plus your HTTPS endpoint.

curl --request POST "https://api.voice.stateset.com/api/v1/voice/agents" \
  --header "Authorization: Bearer $STATESET_VOICE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "agent_key": "front-desk",
    "name": "Front Desk",
    "publish": true,
    "config": {
      "agent_name": "Front Desk",
      "greeting": "Thanks for calling Acme Dental. How can I help?",
      "instructions": "Answer questions, book appointments, escalate urgent concerns.",
      "realtime_model": "gpt-4o-realtime-preview",
      "voice": "alloy",
      "tools": [
        {
          "name": "get_order_status",
          "description": "Look up an order.",
          "parameters": {
            "type": "object",
            "required": ["order_id"],
            "properties": { "order_id": { "type": "string" } }
          },
          "endpoint": {
            "method": "POST",
            "url": "https://api.acme.example/voice/get-order-status",
            "timeout_ms": 3000
          }
        }
      ]
    }
  }'

Unknown keys in config are rejected with a 400 rather than ignored, and a PATCH mints a new version that is not live unless you publish it. If an edit appears to have no effect, check which version is published before looking at the prompt.

How your tool endpoint is called

Mid-call, the server POSTs to your endpoint with:

Authorization passthrough
An X-Webhook-Signature HMAC over the raw body — the same scheme as webhooks

Your JSON reply becomes the tool result the model sees.

Verify that signature with the same helper you use for webhooks. One implementation covers both — see Verifying signatures.

4. Attach a phone number

Route a number to the agent with direction and agent_id. Inbound calls to that number now reach this agent.

curl --request POST "https://api.voice.stateset.com/api/v1/voice/phone-numbers" \
  --header "Authorization: Bearer $STATESET_VOICE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "phone_number": "+14155550123",
    "direction": "inbound",
    "agent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }'

5. Register a webhook for call results

Point an endpoint at the events you care about. For a first agent, voice.call.started, voice.call.ended, and voice.session.completed are enough — the last one carries persisted transcripts.

curl --request POST "https://api.voice.stateset.com/api/v1/webhooks/endpoints" \
  --header "Authorization: Bearer $STATESET_VOICE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "url": "https://example.com/hooks/voice",
    "secret": "whsec_…",
    "events": ["voice.call.started", "voice.call.ended", "voice.session.completed"]
  }'

6. Place a test call

Test in the browser first — a web call runs the same pipeline with no number and no charges:

curl --request POST "https://api.voice.stateset.com/api/v1/voice/web-calls" \
  --header "Authorization: Bearer $STATESET_VOICE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "agent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }'

When that sounds right, dial for real:

curl --request POST "https://api.voice.stateset.com/api/v1/voice/calls" \
  --header "Authorization: Bearer $STATESET_VOICE_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: appointment-reminder-88213" \
  --data '{ "to": "+14155550123", "agent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }'

This dials a real phone. DNC and TCPA quiet-hours checks apply, evaluated in the called party’s timezone, and a blocked call returns 403 rather than ringing. Send an Idempotency-Key derived from the thing you are calling about: the same key inside 24 hours replays the stored outcome instead of dialling again.

7. Read the transcript

# Find the call
curl "https://api.voice.stateset.com/api/v1/call-logs?call_sid=CA9f2c…" \
  --header "Authorization: Bearer $STATESET_VOICE_API_KEY"

# Full transcript and summary
curl "https://api.voice.stateset.com/api/v1/call-logs/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  --header "Authorization: Bearer $STATESET_VOICE_API_KEY"

If replies feel laggy, start at GET /call-logs/latency for p50/p95 rather than guessing — then drill into the individual call log.

See the full event catalog.

6. Place a test call

Either call the number, or place an outbound call with POST /make-call.

Faster still: POST /voice/web-calls gives you a browser call with no phone number needed, on the same pipeline. It’s the tightest loop while iterating on a prompt.

Send an Idempotency-Key on make-call — 24-hour replay protection means a retried request won’t place a second real call.

7. Inspect the session afterwards

Session records and transcripts are persisted. voice.session.completed delivers them to your webhook, and the session APIs let you fetch them directly.

8. Watch a live call

Route	Use
`GET /sessions`	Enumerate active sessions
`GET /logs` (WebSocket)	Real-time log broadcast
`POST /sessions/:id/actions/:action`	`monitor`, `whisper`, `barge`, `escalate`, `end`

monitor listens; whisper speaks to the agent only; barge joins the caller; escalate hands to a human; end terminates.

Troubleshooting

Symptom	Check
Twilio webhooks rejected	Signature validation — credentials must match the account sending them
Media stream fails to authenticate	`STREAM_AUTH_SECRET` is set, or legacy transport is explicitly enabled. Production fails fast with neither
No audio from the agent	`GET /admin/tenants/audio-providers` — compare configured vs effective provider and the fallback reason
Agent talks over the caller	Per-tenant VAD threshold and silence padding
First audio feels slow	Try `turn_response_mode: streaming` for that tenant

SDKs

TypeScript, Python, browser calls.

Configuration

Auth transport, providers, VAD, readiness.

Webhooks

Events and signature verification.

MCP server

Build and tune agents from Claude.

​Prerequisites

​1. Mint a tenant API key

​2. Configure the tenant account

​3. Create the agent

​How your tool endpoint is called

​4. Attach a phone number

​5. Register a webhook for call results

​6. Place a test call

​7. Read the transcript

​6. Place a test call

​7. Inspect the session afterwards

​8. Watch a live call

​Troubleshooting

​Next

SDKs

Configuration

Webhooks

MCP server

Prerequisites

1. Mint a tenant API key

2. Configure the tenant account

3. Create the agent

How your tool endpoint is called

4. Attach a phone number

5. Register a webhook for call results

6. Place a test call

7. Read the transcript

6. Place a test call

7. Inspect the session afterwards

8. Watch a live call

Troubleshooting

Next