FIfish
Agent Sessions

Create Agent Session

Changed on

Start a conversation session with an agent and receive a join token for the session transport (currently LiveKit WebRTC). Authenticate with an API key to start sessions with any agent in your team; without credentials only agents published as public are reachable, and the request Origin must match the agent's allowed origins.

language (and overrides.language) accepts en, ja, zh, ko, es, fr, de, pt, it, nl; anything else is 422. Omit it to use the agent's configured speaking language.

overrides.asr.model picks the speech recognition model for this session, nested like the agent config's asr section and with the same values as asr.model. It needs an API key.

overrides.llm.fallback replaces the agent's llm.fallback for this session, with the same shape and rules; each custom model needs its api_key. It needs an API key and llm.fallback in the agent's overrides_allowed.

post/v1/agent/sessions

Request

  • Base URL
    https://api.fish.audio
  • URL
    https://api.fish.audio/v1/agent/sessions
  • Auth
    HTTP bearer

Headers

originstring nullable

Request body

agent_idstring required
namestring nullable
timezonestring nullable

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.

client_timezonestring nullable

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.

dynamic_variablesobject nullable
end_user_idstring nullable

Your identifier for the end user, stored verbatim. Returned on session reads and webhooks, and filterable with GET /v1/agent/sessions?end_user_id=.

metadataobject nullable
llm_extra_bodyobject nullable
tool_eventsboolean
record_audioboolean nullable

Response

Document created, URL follows

session_idstring required
expires_atstring required
max_duration_secondsinteger required
transport'livekit' required
livekit_urlstring required
tokenstring required

Changes