Session Management

Session management is performed via the Session Storage API. API Reference

Introduction

Sessions are used to obtain the publisher access token and the webrtc_url / ws_url needed to connect to the Palabra Translation Server.

For WebSocket integrations you can skip manual session management entirely: 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. Manually created sessions are required for WebRTC connections.

Session lifecycle

  • Each session has an expires_at timestamp (available via Get session by ID). If you haven't connected before this time, the session is invalidated.
  • You can extend expires_at manually using the Update Session Expiration request.
  • While a connection is active, expires_at is automatically extended every minute.
  • There is a limit (based on your plan) on how many sessions you can keep open in parallel. 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 Streaming Session

Endpoint: POST /session-storage/session

Headers:

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

Request Body:

{
  "data": {}
}

Example Request:

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

{
  "data": {}
}

Response: HTTP 201 Created

{
  "ok": true,
  "data": {
    "publisher": "<publisher-jwt-token>",
    "webrtc_url": "https://api.palabra.ai/stream/",
    "ws_url": "wss://api.palabra.ai/stream/control/",
    "intent": "api",
    "id": "session-id"
  }
}
  • publisher — JWT token for the publisher (read/write).
  • webrtc_url — WebRTC Speech-to-Speech Translation API URL.
  • ws_url — WebSocket Speech-to-Speech Translation API URL.
  • intent — session intent.
  • id — session ID.

List Active Sessions

Endpoint: GET /session-storage/sessions

Headers:

  • Authorization: Bearer <API_KEY>

Query Params:

  • page_size (integer, optional): Number of items per page.
  • page_token (string, optional): Pagination token from the next_page_token field of the previous response.

Example Request:

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

Response: HTTP 200 OK

{
  "data": [
    {
      "id": "test-user.fec6b8fa.af4d2d22",
      "created_at": "2024-10-11T09:02:56Z",
      "updated_at": "2024-10-11T09:02:56Z",
      "expires_at": "2024-11-10T09:02:56Z"
    }
  ],
  "next_page_token": "eyJrZXkiOnsib ... c4NDlmIn0="
}

API Reference: Get user sessions

Get Session by ID

Endpoint: GET /session-storage/sessions/{session_id}

Headers:

  • Authorization: Bearer <API_KEY>

Path Params:

  • session_id (string): ID of the session.

Example Request:

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

Response: HTTP 200 OK

{
  "data": {
    "id": "58347ae0-8a5d-41cf-96d9-166b550b3335.b0327ccf.3c0742bc",
    "created_at": "2024-10-21T14:13:18Z",
    "updated_at": "2024-10-21T14:13:18Z",
    "expires_at": "2024-11-20T14:13:18Z"
  }
}

API Reference: Get user session by ID

Delete Session

Endpoint: DELETE /session-storage/sessions/{session_id}

Headers:

  • Authorization: Bearer <API_KEY>

Path Params:

  • session_id (string): ID of the session.

Example Request:

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

Response: HTTP 204 No Content

API Reference: Delete user session by ID

Update Session Expiration

Endpoint: POST /session-storage/sessions/{session_id}

Headers:

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

Path Params:

  • session_id (string): ID of the session.

Query Params:

  • ttl_seconds (integer): New time-to-live in seconds.

Example Request:

POST /session-storage/sessions/{session_id}?ttl_seconds=3600 HTTP/1.1
Host: api.palabra.ai
Authorization: Bearer <your-api-key>
Content-Type: application/json

Response: HTTP 204 No Content

API Reference: Update Session Expiration