Skip to main content
POST
Create Session

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

origin
string | null

Body

application/json
agent_id
string
required
name
string | null
Maximum string length: 128
timezone
string | null

IANA timezone (like Asia/Tokyo) for the agent's sense of local date and time in this session. Overrides the agent's configured timezone, which defaults to UTC. Invalid names are rejected with 422.

Maximum string length: 64
client_timezone
string | null

The end user's device timezone as an IANA name (like Asia/Tokyo), used as a fallback hint: it applies only when neither timezone nor the agent's configured timezone is set, and invalid values are ignored rather than rejected. The Web SDK fills it automatically from the browser for public agents. When your backend creates the session, forward the value from your client.

Maximum string length: 64
world_context
boolean
default:true
overrides
AgentSessionOverridesPayload · object | null

Wire twin of @fishaudio/agent-protocol SessionOverrides (session.ts).

Every field must be allow-listed in Agent.overrides_allowed; unauthorized fields fail session creation loudly rather than being silently dropped.

dynamic_variables
Dynamic Variables · object | null
end_user_id
string | null
Maximum string length: 256
metadata
Metadata · object | null
llm_extra_body
Llm Extra Body · object | null
tool_events
boolean
default:true
record_audio
boolean | null

Response

Document created, URL follows

Wire twin of @fishaudio/agent-protocol SessionToken (session.ts); keep in sync.

session_id
string
required
expires_at
string
required
max_duration_seconds
integer
required
transport
string
required
Allowed value: "livekit"
livekit_url
string
required
token
string
required