Documentation

Build voice agents for real business operations.

StateSet Voice combines telephony, realtime AI, workflow tools, operator handoff, and governance APIs so teams can launch production voice agents without building the voice runtime from scratch.

Request API key Start building Endpoint guides Authentication Production readiness

Runtime APIBearer tenant keys

Admin APIx-admin-key

TelephonyTwilio signatures

SpecsOpenAPI 3.1

StateSet Voice API Documentation

A practical map for business teams building Voice AI Agents: start with authentication and a first call, then wire inbound telephony, observe sessions, and launch with governance.

Base URLhttps://voice.stateset.app

AuthAuthorization: Bearer ...

SpecOpenAPI 3.1

Recommended path: request a tenant API key, start with the runtime API, add webhook signature verification, then introduce admin automation only after the agent contract and launch gates are approved.

Access

Request an API key

Tell us about your Voice AI Agent workflow, volume, timeline, and launch requirements so the team can provision access.

Start

Get started

Authenticate, verify readiness, make the first call, connect inbound webhooks, and inspect outcomes.

Guide

Build voice agents

Design the agent contract, configure runtime behavior, connect tools, and launch with governance.

Tutorial

First voice agent

Build a production-shaped integration from agent contract to calls, inbound routing, telemetry, and launch criteria.

Reference

Endpoint guides

Understand calls, sessions, admin automation, operations workflows, and scoped OpenAPI documents.

Architecture

Runtime architecture

Understand the runtime plane, control plane, trust boundaries, and operational data model.

Clients

SDKs and client generation

Generate typed runtime and admin clients from the scoped OpenAPI contracts.

TypeScript

TypeScript client

Generate types, wrap fetch, handle API errors, and keep client changes contract-reviewed.

Python

Python client

Build backend integrations with timeouts, retries, request IDs, and typed response handling.

Examples

Code examples

Copy working cURL, Node.js, Python, and Go examples for common integration paths.

Security

Authentication

Separate tenant bearer tokens, admin keys, browser sessions, Twilio signatures, and stream tokens.

Launch

Production readiness

Use a launch checklist for security, runtime behavior, operations, monitoring, and business approval.

Core API surfaces

POST /api/v1/make-call

Create outbound calls for tenant-scoped voice agent workflows.

POST /api/v1/incoming-call

Receive signed Twilio inbound traffic and return the realtime media setup.

GET /api/v1/voice-sessions

Inspect session history, transcripts, function calls, tags, and QA state.

GET /api/v1/call-logs

Query operational call history, status, duration, escalation, and summaries.

POST /api/v1/access-requests

Submit a reviewed API key access request for prospective business integrations.

PUT /api/v1/admin/tenants/{id}/runtime-config

Configure model, voice, prompt key, and telephony defaults with admin auth.

POST /api/v1/admin/rollout-governance/sweep

Evaluate launch controls before expanding production traffic.

Build path

Step	What to implement	Primary docs
1. Authenticate	Create runtime and admin credentials with clear environment boundaries.	Authentication
2. Call	Use `POST /api/v1/make-call` for outbound voice workflows.	Getting started
3. Receive	Configure Twilio to POST signed inbound calls to `/api/v1/incoming-call`.	Webhooks
4. Observe	Read call logs, active sessions, transcripts, outcomes, and evaluations.	Endpoint guides
5. Govern	Stage agent versions, phone routes, rollout policy, and launch approval.	Production readiness

Reliability and operating model

Errors and retries

Status codes, retry guidance, and structured error response shape.

Rate limits

Headers, 429 recovery, and operational throttling practices.

Pagination

Use limit, offset, and stable export patterns.

Idempotency

Prevent duplicate calls, queue work, and webhook processing.

Webhooks

Inbound call webhook flow, event model, and Twilio integration shape.

Webhook events

Event catalog, payload examples, delivery headers, and deduplication rules.

Webhook signatures

Verify X-Twilio-Signature with exact URL reconstruction and HMAC-SHA1.

Specs and lifecycle

Surface	Use	Link
Swagger UI	Explore the interactive API reference.	/swagger-ui
Public OpenAPI	Generate clients for tenant runtime integrations.	/api-docs/public.json
Admin OpenAPI	Generate clients for platform and tenant administration.	/api-docs/admin.json
Full OpenAPI	Audit the complete API contract.	/api-docs/openapi.json
Versioning	Understand compatibility, release cadence, and deprecation behavior.	/docs/versioning
Changelog	Review API and documentation changes.	/docs/changelog

Generate clients

Use the scoped OpenAPI documents to generate tenant runtime clients separately from admin automation clients. Keeping those clients separate makes credentials and deployment ownership easier to reason about.

Runtime client

Tenant integrations

curl -sS "https://voice.stateset.app/api-docs/public.json" \
  -o stateset-voice-public.openapi.json

Admin client

Platform automation

curl -sS "https://voice.stateset.app/api-docs/admin.json" \
  -o stateset-voice-admin.openapi.json