Sign in
app

Rtvi Connect

post/connect

Headers

X-API-Keystring nullable
API-AUTH-TOKENstring nullable

Request body

character_idstring nullable

Single-character UUID, optionally followed by -draft, -latest, or a major.minor[.patch] version. Roster entries currently accept bare UUIDs only.

connection_type'audio' | 'video' | 'text'
llm_provider'gemini-live' | 'gemini-live-beta' | 'gemini-baml' | 'dynamic'
blendshape_provider'not_provided' | 'ovr' | 'neurosync'
state_of_mindstring nullable
narrative_template_keysobject nullable
video_track_namestring
vision_prompt_mode'auto' | 'disabled'

Controls Core-owned vision instructions and visual-input tooling for this session. 'auto' preserves legacy runtime behavior; 'disabled' omits the vision prompt and suppresses visual input while retaining scene metadata and other text context.

thinking_modeboolean
room_namestring nullable
room_session_idstring uuid nullable
mode'create' | 'join'
spawn_agentboolean
shared_session_keystring nullable

Client-provided grouping key used to deterministically place participants into the same shared session/room.

connect_attempt_idstring nullable

Client-generated idempotency key for one logical connection attempt. Retries with the same key and payload replay the original response.

max_num_participantsinteger
end_user_idstring nullable
end_user_metadataobject nullable
default_tts_enabledboolean
default_stt_enabledboolean
disable_live_fallbackboolean
stt_providerstring nullable
debugboolean
debug_row_capinteger nullable
use_response_lifecycle_contractboolean nullable

Example request

{
  "character_id": "00000000-0000-4000-8000-000000000001"
}

Response

Successful Response

session_idstring required

Unique session token

request_trace_idstring required

Server-side request trace ID for correlating client events, logs, telemetry, and session records for this /connect request

character_session_idstring required

Interaction session id

room_urlstring required

URL of the room to connect to

room_namestring nullable

Room name (only for LiveKit transport)

tokenstring required

Authentication token for the room

end_user_idstring nullable

The end_user_id associated with this session when provided

end_user_metadataobject nullable

Metadata associated with the end user

room_session_idstring uuid nullable
active_membership_idstring uuid nullable
route_epochinteger nullable
roster_epochinteger nullable
partial_dispatchboolean

Changes