Sessions API

Sessions are the entry point for every WebSocket conversation. You must create a session before opening a WebSocket connection.

Create session

POST/api/sessionsBearer JWT

Create a chat session and receive a short-lived WebSocket token.

Headers: Authorization: Bearer <token> OR X-Api-Key: <key>

Response 201 Created:

{
  "session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ1c2VyLTEiLCJzZXNzaW9uX2lkIjoiM2ZhODVmNjQ…",
  "ws_url": "wss://api.example.com/ws/user-agent/3fa85f64-5717-4562-b3fc-2c963f66afa6?token=eyJ…"
}

Fields:

| Field | Type | Description | | ------------ | --------------- | ---------------------------------------------- | | session_id | string (UUID) | Unique session identifier | | token | string (JWT) | Short-lived token for WebSocket auth (5 min) | | ws_url | string | Pre-built WebSocket URL with token query param |

Token lifetime

The token expires 5 minutes after issue. If your client hasn't connected to ws_url by then, call this endpoint again to get a fresh token.

Connect WebSocket

Use the ws_url from the session creation response directly:

const ws = new WebSocket(ws_url);

Or construct it manually:

wss://api.example.com/ws/user-agent/{session_id}?token={token}

Close codes:

| Code | Reason | | ------ | ---------------------------------------------- | | 4001 | Token invalid, expired, or session ID mismatch | | 4004 | Session not found in database | | 1000 | Normal closure |

List sessions

GET/api/sessionsBearer JWT

List your recent sessions (paginated, newest first).

Get session

GET/api/sessions/{session_id}Bearer JWT

Retrieve a single session with its current phase and metadata.

Agents

Marketplace