Session Management

Create and manage sessions. A session is one authorization to connect to a Palabra real-time product: Speech-to-Speech translation, Speech-to-Text or Text-to-Speech, over WebSocket or WebRTC.

Introduction

tip

For WebSocket integrations this API is optional: only use it when you need to control sessions manually, otherwise connect to the Speech-to-Speech, Speech-to-Text, or Text-to-Speech WebSocket endpoints directly with your API Key, and a session is created (and cleaned up) for you automatically.

Manual session management is required for WebRTC: create a session first, then join the room at webrtc.url with the returned token.

Sessions for your users' devices

A session created on this page is a general-purpose session for your own backend. When its token will leave your servers, for example to a mobile app, a browser or a device of your user, add the limits described in Temporary Sessions: a connect window, a duration cap, single use and your own reference id.

Session lifecycle

Status	Meaning
`pending`	Created, no stream opened yet
`active`	At least one stream is running
`idle`	The session has been used, no stream is running, it can open a new one
`used`	A single-use session whose stream has finished
`expired`	The connect window has passed and no stream is running
`revoked`	Deleted by you

A session can open a stream until connect_by. By default the window is one hour; change it with expires_in_seconds when creating the session.
A stream that is already running is not interrupted when the window closes. It ends when the client disconnects, when you delete the session, or when the duration cap set for the session is reached.
Running streams of all your sessions count toward the concurrent session limit of your plan. Delete unused sessions instead of waiting for them to expire.

Authorization

All endpoints require the following headers:

Authorization: Bearer <API_KEY> — your Palabra API Key.

See Authentication to get your API Key.

Create Session

Endpoint: POST /session-storage/v2/sessions

Headers:

Authorization: Bearer <API_KEY>
Content-Type: application/json

Request Body:

Field	Type	Required	Description
`intent`	string	yes	Product: `s2s` (Speech-to-Speech translation), `stt` (Speech-to-Text) or `tts` (Text-to-Speech)
`connection_type`	string	no	`ws` (default) or `webrtc`. `webrtc` is available for `s2s` only
`subscriber_count`	integer	no	Number of listener tokens to issue, 0–100. WebRTC only

Optional limits (expires_in_seconds, max_session_duration_seconds, single_use, client_reference_id) are described in Temporary Sessions.

Example Request:

POST /session-storage/v2/sessions HTTP/1.1
Host: api.palabra.ai
Content-Type: application/json
Authorization: Bearer <your-api-key>

{
  "intent": "s2s",
  "connection_type": "webrtc"
}

Response: HTTP 201 Created

{
  "ok": true,
  "data": {
    "id": "ses_k3v9x2m7q4t8w1z5b6n0c2d4",
    "token": "<session-token>",
    "intent": "s2s",
    "connection_type": "webrtc",
    "single_use": false,
    "status": "pending",
    "created_at": "2026-10-05T10:00:00Z",
    "connect_by": "2026-10-05T11:00:00Z",
    "first_connected_at": null,
    "active_stream_count": 0,
    "webrtc": {
      "url": "https://api.palabra.ai/livekit/",
      "room_name": "6bbcf900"
    }
  }
}

id — session ID. Use it to inspect or delete the session.
token — the token the client connects with. Treat it as an opaque string. It is returned here and in Get Session by ID only.
connect_by — moment after which the token can no longer open a new stream.
webrtc — present for connection_type: webrtc only: the room URL, the room name and, when subscriber_count is set, the listener tokens in subscriber_keys (returned on creation only).

Connecting with a session

Use the session token wherever the product documentation asks for the token.

`intent`	`connection_type`	Where the client connects
`s2s`	`ws`	Speech-to-Speech Translation over WebSockets
`s2s`	`webrtc`	Speech-to-Speech Translation over WebRTC, using `webrtc.url` and `webrtc.room_name`
`stt`	`ws`	Realtime Speech-to-Text API
`tts`	`ws`	Realtime TTS API

A token presented to another product or over another transport is refused; the codes are listed in Connection errors.

List Sessions

Endpoint: GET /session-storage/v2/sessions

Headers:

Authorization: Bearer <API_KEY>

Query Params:

page_size (integer, optional): Number of items per page, 1–100. Default 50.
page_token (string, optional): Pagination token from the next_page_token field of the previous response.
status (string, optional): pending, active, idle, used, expired or revoked.
client_reference_id (string, optional): Return sessions with this label only.
created_from, created_to (date-time, optional): Creation time range.

Example Request:

GET /session-storage/v2/sessions?page_size=10&status=active HTTP/1.1
Host: api.palabra.ai
Authorization: Bearer <your-api-key>

Response: HTTP 200 OK

{
  "ok": true,
  "data": {
    "sessions": [
      {
        "id": "ses_k3v9x2m7q4t8w1z5b6n0c2d4",
        "intent": "s2s",
        "connection_type": "webrtc",
        "single_use": false,
        "status": "active",
        "created_at": "2026-10-05T10:00:00Z",
        "connect_by": "2026-10-05T11:00:00Z",
        "first_connected_at": "2026-10-05T10:01:12Z",
        "active_stream_count": 1
      }
    ],
    "next_page_token": null
  }
}

The list never includes token. next_page_token is null on the last page.

Get Session by ID

Endpoint: GET /session-storage/v2/sessions/{id}

Headers:

Authorization: Bearer <API_KEY>

Path Params:

id (string): ID of the session.

Example Request:

GET /session-storage/v2/sessions/ses_k3v9x2m7q4t8w1z5b6n0c2d4 HTTP/1.1
Host: api.palabra.ai
Authorization: Bearer <your-api-key>

Response: HTTP 200 OK with the same object as Create Session, including token. A session that does not exist or belongs to another account returns HTTP 404 with error_code 200090.

Delete Session

Endpoint: DELETE /session-storage/v2/sessions/{id}

Headers:

Authorization: Bearer <API_KEY>

Path Params:

id (string): ID of the session.

Example Request:

DELETE /session-storage/v2/sessions/ses_k3v9x2m7q4t8w1z5b6n0c2d4 HTTP/1.1
Host: api.palabra.ai
Authorization: Bearer <your-api-key>

Response: HTTP 204 No Content

The token stops working for new connections at once. Streams that are already running receive session_revoked (error_code 202103) and close within a minute. The session keeps the status revoked in the list.

Errors

A refused connection tells the client why.

Before the connection is established, the client receives an HTTP status and a JSON body:

{
  "ok": false,
  "errors": [
    {
      "error_code": 202106,
      "reason": "session_limit_reached",
      "message": "concurrent session limit reached"
    }
  ]
}

On a running stream, the client receives one error message, then the connection closes with code 1008:

{
  "message_type": "error",
  "data": {
    "code": 202103,
    "reason": "session_revoked"
  }
}

Over WebRTC the participant receives the same error message as a data packet and is then removed from the room.

`error_code` / `reason`	HTTP	What happened and what to do
202100 `session_already_used`	409	A single-use token is presented a second time. Request a new session.
202101 `connect_window_expired`	410	The token is presented after `connect_by`. Request a new session.
202102 `max_duration_reached`	410	The stream reached `max_session_duration_seconds`. Request a new session for a new stream.
202103 `session_revoked`	410	The session was deleted, or the account ran out of balance or was blocked. Stop using this token.
202104 `intent_mismatch`	403	The token is presented to a different product. Connect to the product the session was created for.
202105 `connection_type_mismatch`	403	The token is presented over the other transport. Use the transport the session was created for.
202106 `session_limit_reached`	429	The account concurrent session limit is reached. Wait for a stream to end or delete unused sessions.
202107 `session_verification_unavailable`	424	The token could not be checked right now. Retry with the same token after a short pause.
202108 `pending_sessions_limit_reached`	429	Too many unused sessions on the account (returned on creation only). Delete unused sessions.
202109 `languages_limit_reached`	403	The translation task asks for more target languages than the plan allows. Reduce the number of target languages.
400001 `insufficient_balance`	402	Not enough balance on the account. Top up the balance.
400020 `account_blocked`	403	The account is blocked. Contact support.
200030 `billing_unavailable`	424	Account state could not be checked right now. Retry after a short pause.
200010 `validation_error`	422	A field is out of range or the token is malformed. Fix the request or create a new session.
200090 `not_found`	404	The session does not exist or is no longer available. Create a new session.

Branch on error_code, not on message.

Previous session API

Sessions created with POST /session-storage/session and the /session-storage/sessions endpoints keep working; there is no shutdown date. The stream protocol (set_task, audio, events) is the same for both APIs.

Previous session API (still supported)

POST /session-storage/session — body {"data": {}}; returns publisher (JWT access token), webrtc_url, intent, id.
GET /session-storage/sessions — page_size, page_token; items have id, created_at, updated_at, expires_at.
GET /session-storage/sessions/{session_id}, DELETE /session-storage/sessions/{session_id}.
POST /session-storage/sessions/{session_id}?ttl_seconds=3600 — extends expires_at.

All endpoints take Authorization: Bearer <API_KEY>. Reference: Get user sessions, Get user session by ID, Delete user session by ID.

Introduction​

Session lifecycle​

Authorization​

Create Session​

Connecting with a session​

List Sessions​

Get Session by ID​

Delete Session​

Errors​

Previous session API​

Introduction

Session lifecycle

Authorization

Create Session

Connecting with a session

List Sessions

Get Session by ID

Delete Session

Errors

Previous session API