Sessions API

Sessions represent conversations between an agent and a user.

Create a session

POST /sessions

Required fields:

Field	Type	Description
agent_id	string	Agent to run.
user_id	string	Stable user ID from your application.

Optional fields:

Field	Type	Description
modality	voice, voice+text, or text	Defaults to voice.
dynamic_variables	object	String variables bound to the session token.
ttl_seconds	integer	Token TTL, capped at 3600 seconds.
overrides	object	Per-session agent overrides.
voice_stack_override	object	Per-session voice stack override.

Example:

curl -X POST "https://api.hyponema.ai/sessions" \
  -H "Authorization: Bearer $HYPONEMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_...",
    "user_id": "user_123",
    "modality": "voice+text"
  }'

The response includes:

• id: the session ID.
• status: pending, in_progress, completed, or failed.
• ws_url: signed voice WebSocket URL.
• chat_url: signed chat WebSocket URL.
• token: signed token, returned only on session creation.
• expires_at: token expiry, returned only on session creation.

Get a session

GET /sessions/{session_id}

Returns the current lifecycle view of the session. Tenant scope is enforced by the API key.

End a session

POST /sessions/{session_id}/end

Request body:

{
  "status": "completed",
  "reason": "User closed the widget."
}

status can be completed or failed. Ending a session is idempotent; an already closed session returns its current state.