API Reference

REST endpoints and WebSocket protocols for the FastAPI backend.

Health & Monitoring

Endpoint	Method	Description
/health	GET	Liveness check. Returns 200 when server is running. Use for K8s liveness probes.
/ready	GET	Readiness check. Returns 200 when warmup tasks (MCP, pools) are complete.
/readiness	GET	Deep health check. Validates all Azure service dependencies.
/pools	GET	Resource pool metrics — TTS/STT client availability and utilization.
/appconfig	GET	Azure App Configuration provider status.
/appconfig/refresh	POST	Force refresh App Configuration cache.

Example

# Check if backend is ready to serve calls
curl https://your-backend.azurecontainerapps.io/api/v1/ready

# Response
{
  "status": "ready",
  "mcp": "connected",
  "pools": { "tts": 5, "stt": 5 }
}

---

Call Management

Endpoint	Method	Description
/calls/initiate	POST	Start an outbound call. Body: { "phone_number": "+1..." }
/calls/	GET	List active/recent calls with pagination.
/calls/terminate	POST	End an active call. Body: { "connection_id": "..." }
/calls/answer	POST	Handle inbound call from ACS Event Grid webhook.
/calls/callbacks	POST	Process ACS callback events (call state changes, DTMF, etc.)

Initiate a call

curl -X POST https://your-backend/api/v1/calls/initiate \
  -H "Content-Type: application/json" \
  -d '{"phone_number": "+18165019907", "scenario": "banking"}'

---

Media Streaming

Endpoint	Type	Description
/media/status	GET	Media streaming configuration and active stream count.
/media/stream	WebSocket	ACS bidirectional audio stream. See WebSocket protocol.

---

Genesys AudioConnector

AudioHook v2 bridge for Genesys Cloud telephony. See the Genesys Cloud Integration guide for setup, the simulator, and troubleshooting.

Endpoint	Type	Description
/genesys/health	GET	Liveness check — returns {"status":"ok","service":"genesys-audiohook"}.
/genesys/stream	WebSocket	AudioHook v2 audio + control stream (subprotocol audiohook-v2, µ-law 8 kHz). Bridges Genesys Cloud AudioConnector to Azure VoiceLive.

---

Browser Conversations

Endpoint	Type	Description
/browser/status	GET	Active browser connections and service status.
/browser/conversation	WebSocket	Browser-based voice conversation. See WebSocket protocol.
/browser/dashboard/relay	WebSocket	Real-time dashboard events (audio levels, transcripts, agent state).

---

Agent Management

Endpoint	Method	Description
/agents	GET	List all loaded agents with their configuration.
/agents/{name}	GET	Get specific agent details (prompt, tools, handoff trigger).
/agents/{name}	PUT	Update agent runtime configuration (model, temperature, etc.).
/agents	POST	Create a new agent at runtime (session-scoped).

---

Sessions

Endpoint	Method	Description
/sessions/{id}	GET	Get session state (scenario, active agent, conversation history).
/sessions/{id}/reset	POST	Reset session — new ID, clear state, fresh conversation.

---

Scenarios

Endpoint	Method	Description
/scenarios	GET	List available scenarios (built-in + session-created).
/scenarios	POST	Create a session-scoped scenario from the Scenario Builder.
/scenarios/{name}	GET	Get scenario details (agents, handoffs, start agent).

---

Demo Profiles

Endpoint	Method	Description
/profiles/generate	POST	Generate a random demo customer profile (name, accounts, MFA).
/profiles/{id}	GET	Retrieve a generated profile by ID.

---

WebSocket: Media Stream

wss://your-backend/api/v1/media/stream

Bidirectional audio streaming for ACS. The backend receives raw audio from ACS and sends synthesized audio back.

Message types (server → client)

Type	Payload
audio	Base64-encoded PCM audio chunk
transcript	STT recognition result (interim or final)
agent_response	LLM text response before TTS
handoff	Agent handoff notification (from, to, type)
tool_call	Tool invocation event (name, args, result)

---

WebSocket: Browser Conversation

wss://your-backend/api/v1/browser/conversation?session_id=...

Browser-based voice conversation using the Web Audio API. Same orchestration pipeline as phone calls.

Message types (client → server)

Type	Payload
audio_data	Base64 PCM audio from browser microphone
control	Start/stop/pause/reset commands
config	Session configuration (scenario, agent overrides)

Message types (server → client)

Type	Payload
audio	Base64 PCM audio for playback
transcript	User speech recognition
response	Agent text response
event	Session events (handoff, tool call, state change)
audio_levels	Input/output amplitude for visualization

---

Configuration Reference

All configuration via environment variables. azd up generates a .env.local with all values.

Core

Variable	Description	Default
ACS_STREAMING_MODE	Orchestration mode: MEDIA, TRANSCRIPTION, or VOICE_LIVE	MEDIA
BASE_URL	Public callback URL ACS uses to reach the backend (dev tunnel URL for local dev)	—
ENVIRONMENT	development or production	development

Azure Services

Prefix	Service	Key variables
ACS_*	Communication Services	ACS_ENDPOINT, ACS_PHONE_NUMBER
AZURE_OPENAI_*	Azure OpenAI	AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_DEPLOYMENT
AZURE_SPEECH_*	Speech Services	AZURE_SPEECH_REGION, AZURE_SPEECH_KEY
REDIS_*	Azure Redis	REDIS_HOST, REDIS_PORT
AZURE_COSMOS_*	Cosmos DB	AZURE_COSMOS_ENDPOINT, AZURE_COSMOS_DATABASE

Voice settings

Variable	Description	Default
TTS_VOICE	Azure neural voice name	en-US-AvaMultilingualNeural
TTS_STYLE	Voice style (chat, friendly, etc.)	chat
TTS_RATE	Speech rate adjustment	+3%
STT_LANGUAGE	Recognition language	en-US
VAD_SILENCE_TIMEOUT	Silence before turn end (ms)	500