API reference

Build against capability-specific endpoint guides.

Use these guides when you need production context around the OpenAPI contract: required credentials, operational behavior, pagination, webhook delivery, and rollout boundaries.

Request API key Start building Endpoint guides Authentication Production readiness

Runtime APIBearer tenant keys

Admin APIx-admin-key

TelephonyTwilio signatures

SpecsOpenAPI 3.1

Endpoint groups

POST/api/v1/make-call

Outbound call creation for a tenant voice agent.

POST/api/v1/incoming-call

Signed inbound Twilio callback and TwiML response.

GET/api/v1/voice-sessions

Persisted conversation sessions, transcripts, tags, and metadata.

GET/api/v1/call-logs

Operational call history and aggregate call statistics.

Calls

Start and receive calls

POST /api/v1/make-call starts an outbound call. POST /api/v1/incoming-call receives Twilio inbound traffic and returns TwiML.

Sessions

Inspect active and historical conversations

GET /api/v1/voice-sessions, call logs, active session controls, evaluations, and live logs support operations and QA workflows.

Admin

Configure tenants and agent runtime

Admin endpoints manage tenant config, API keys, agents, versions, phone routes, rollout governance, and diagnostics.

Operations

Run operator follow-up

Callback tasks, queues, supervisor actions, DNC controls, and automation endpoints connect the voice runtime to business processes.

Authentication by surface

Surface	Credential	Use
Tenant runtime	`Authorization: Bearer`	Calls, sessions, call logs, operations, and automation endpoints.
Admin platform	`x-admin-key`	Tenant config, API keys, agents, versions, phone routes, and rollout governance.
Twilio callback	`X-Twilio-Signature`	Inbound calls and call status webhooks from Twilio.
Media stream	`stream_token`	Short-lived access during realtime media stream setup.

Outbound call flow

Resolve the tenant API key for the environment and phone route you are using.
Submit POST /api/v1/make-call with E.164 phone numbers and the target agent key or route context.
Store the returned call identifier and reconcile it against call logs and voice sessions.
Review transcripts, function calls, outcomes, and evaluations before expanding traffic.

curl -sS -X POST "https://voice.stateset.app/api/v1/make-call" \
  -H "Authorization: Bearer ${STATESET_VOICE_API_KEY}" \
  -H "content-type: application/json" \
  -d '{
    "to": "+15555555678",
    "from": "+15555551234",
    "agent_key": "support_primary"
  }'

Endpoint deep dives

Use these first-party endpoint notes with the OpenAPI schemas. They capture the behavior developers need most often when building production clients.

Endpoint	Request contract	Success response	Operational notes
`POST /api/v1/make-call`	E.164 `to`, optional `from`, `agent_key`, `agent_version_id`, and greeting.	Call acceptance with `call_sid`, status, destination, and source number.	Persist the call identifier and reconcile against call logs before retrying business workflows.
`POST /api/v1/incoming-call`	Twilio form callback with `From`, `To`, `CallSid`, and `X-Twilio-Signature`.	TwiML that connects the caller to the realtime media stream for the resolved tenant and agent.	Validate the exact public URL Twilio signed and keep fallback routing configured.
`GET /api/v1/call-logs`	Optional `limit`, `offset`, status, direction, and time-window filters.	Page of call records with status, duration, escalation, summary, and tenant metadata.	Use for reconciliation, support audit, analytics exports, and duplicate-call investigation.
`GET /api/v1/voice-sessions`	Optional pagination and filters for persisted conversation sessions.	Session records with transcript, function calls, tags, QA metadata, and model/voice context.	Use for prompt iteration, evaluation, compliance review, and launch-governance evidence.
`PUT /api/v1/admin/tenants/{tenant_id}/runtime-config`	Admin-scoped runtime settings for model, voice, prompt key, telephony defaults, and webhook URL.	Updated tenant runtime configuration with admin audit context.	Change through reviewed platform automation, not from customer-facing runtime code.

Canonical error handling

Failure class	Client action	Example causes
`400`	Fix payload and do not retry automatically.	Invalid E.164 number, missing route, unsupported agent key.
`401`/`403`	Rotate, scope, or reissue credentials before retrying.	Expired tenant key, wrong admin key, failed Twilio signature.
`404`	Reconcile identifiers and tenant scope.	Unknown session, call log, callback task, or tenant resource.
`409`	Resolve state conflict before retrying.	Duplicate queue claim, stale rollout update, or conflicting tenant config.
`429`	Back off with jitter and honor `Retry-After`.	Tenant or IP rate limit exceeded.
`500`/`502`/`503`	Retry only safe operations and alert on repeated failure.	Provider outage, database issue, or transient runtime failure.

Reference documents

Document	Use when	URL
Public OpenAPI	You are building a tenant runtime integration.	`/api-docs/public.json`
Admin OpenAPI	You are automating tenant, agent, phone route, or rollout configuration.	`/api-docs/admin.json`
Full OpenAPI	You need the complete platform contract for internal tooling or audit.	`/api-docs/openapi.json`
Swagger UI	You want to inspect schemas and issue exploratory requests.	`/swagger-ui`

Generate typed clients

GET /api-docs/public.json

Use for tenant runtime integrations where applications make calls, read logs, and inspect sessions.

GET /api-docs/admin.json

Use for platform automation where internal services manage tenants, phone routes, agents, and rollout policy.

# TypeScript
npx openapi-typescript https://voice.stateset.app/api-docs/public.json \
  -o stateset-voice-public.d.ts

# OpenAPI Generator
openapi-generator-cli generate \
  -i https://voice.stateset.app/api-docs/public.json \
  -g typescript-fetch \
  -o generated/stateset-voice-public