API Reference

ScaiVoice exposes a thin REST surface for session lifecycle plus one WebSocket that drives the entire conversation.

Choosing your integration shape (Phase 3a)#

ScaiVoice is intentionally agnostic about how you manage conversation memory and tool execution. Two integration patterns, picked at session-create via history_mode:

The 'client' mode is the "bring your own LLM ecosystem" path. Your existing agent code in ScaiBot / ScaiWave / wherever continues to own the cognition; ScaiVoice wraps mic/STT on the way in and TTS/audio on the way out. Every text frame carries the full messages array (i.e. the conversation the agent is currently driving) plus the tools definition list. When the LLM emits tool calls, ScaiVoice forwards them as agent_tool_call events; you execute the tools in your environment and reply with tool_result frames; ScaiVoice continues the agent loop.

Phase 3b adds a second toggle, cognition_mode. With cognition_mode: 'delegated' and a cognition_callback_url set at session-create, ScaiVoice doesn't talk to any LLM — it POSTs each user utterance to your URL with {session_id, tenant_id, user_id, user_input, turn_index, request_id} and pipes the streaming response body straight into TTS. Optional cognition_callback_auth_token is forwarded as Authorization: Bearer … so your endpoint can verify the call. Tools, history, RAG, persona, error-handling — all on your side.

Most ScaiBot / ScaiWave integrations will pair history_mode: 'client' with cognition_mode: 'delegated' and own the entire agent layer in their own infrastructure. Simpler demos can stick with the all-server defaults.

Sessions REST#

All endpoints under /v1/modules/scaivoice/sessions. Permission: scaivoice:use.

POST /sessions#

Create a voice session. Body:

Voice defaults merge chain#

TTS parameters resolve through a three-level precedence chain:

1. Engine default -- built-in values (speed 1.0, cfg ~2.0, no instructions, no trim).
2. Voice default -- default_instructions, default_speed, default_cfg_value, default_warmup_trim_ms on the voice row, set via PATCH /voices/{id} in ScaiSpeak.
3. Session override -- instructions, speed, cfg_value, warmup_trim_ms on POST /sessions.

Each level overrides the one before it. A session that omits a field inherits the voice default; a voice that omits a default inherits the engine default. This lets voice owners bake in per-voice tuning while still allowing session-level control when needed.

Returns 201 Created:

1
2
3
4
5

{
  "session_id": "ses_abc123",
  "ws_url": "/v1/modules/scaivoice/sessions/ses_abc123/stream",
  "state": "idle"
}

GET /sessions/{session_id}#

Returns the full session row including state, timestamps, turn count, and char counters. 404 on cross-tenant lookups (info-leak prevention).

DELETE /sessions/{session_id}#

Marks the session terminated. Doesn't disconnect any in-flight WS — that's the WS handler's responsibility on the next state check. Idempotent.

Session WebSocket#

1

WS /v1/modules/scaivoice/sessions/{session_id}/stream?token=<jwt>

Authentication: bearer token via ?token= query param. Browsers can't set headers on the WS upgrade, so query is the only browser-direct option. Query params matching token are redacted in access logs.

Open handshake#

First client frame must be:

1

{"type": "open"}

Server responds with:

1

{"type": "ready", "session_id": "ses_abc123", "voice_id": "vc_..."}

then transitions the state machine to listening and emits a state event.

Client → Server frames#

Server → Client frames#

Close codes#

Timeouts#

• listening with no client frames for 30 s --> close with code 1000 (idle_timeout). The idle timeout only fires in the listening state -- sessions in thinking or speaking are actively working (LLM inference, delegated callback, TTS streaming) and are not subject to the idle timer.
• thinking for >60 s --> error close (LLM stuck).
• speaking for >120 s --> error close (TTS stuck).

State machine#

Five states. Transitions you'll see in {"type":"state"} events:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

   ┌─────────┐  open    ┌───────────┐  user utterance end  ┌──────────┐
   │  idle   │ ───────► │ listening │ ──────────────────►  │ thinking │
   └─────────┘          └───────────┘                      └────┬─────┘
                              ▲                                  │
                              │ ready_for_next                   │ first TTS frame
                              │                                  ▼
                        ┌─────┴───────┐                    ┌──────────┐
                        │ interrupted │ ◄───────interrupt──│ speaking │
                        └─────────────┘                    └──────────┘
                              │                                  │ agent_done
                              ▼                                  ▼
                        ┌───────────┐                      ┌───────────┐
                        │ listening │ ◄────────────────────│ listening │
                        └───────────┘                      └───────────┘

State events carry a reason field for non-default transitions. Common values: opened, utterance_end, agent_first_frame, agent_done, interrupted_by_user, interrupted_by_error, idle_timeout, caller_terminated, protocol_close, error_<code>.