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.

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:

• ClientID — unique client application identifier.
• ClientSecret — client application secret key.

See Obtaining API Keys to get your ClientID and ClientSecret.

---

Create Streaming Session

Endpoint: POST /session-storage/session

Headers:

• ClientID
• ClientSecret
• Content-Type: application/json

Request Body:

{
  "data": {
    "subscriber_count": 0
  }
}

• subscriber_count (integer, optional): Number of subscriber tokens to generate (default: 0, max: 10).

Example Request:

POST /session-storage/session HTTP/1.1
Host: api.palabra.ai
Content-Type: application/json
ClientID: <your-client-id>
ClientSecret: <your-client-secret>

{
  "data": {
    "subscriber_count": 2
  }
}

Response: HTTP 201 Created

{
  "ok": true,
  "data": {
    "publisher": "<publisher-jwt-token>",
    "subscriber": [
      "<subscriber-jwt-token-1>",
      "<subscriber-jwt-token-2>"
    ],
    "webrtc_room_name": "e0a14Cb7",
    "webrtc_url": "https://api.palabra.ai/stream/",
    "ws_url": "wss://api.palabra.ai/stream/control/",
    "ws_tts_url": "wss://api.palabra.ai/v1/text-to-speech/stream",
    "intent": "api",
    "id": "session-id"
  }
}

• publisher — JWT token for the publisher (read/write).
• subscriber — list of JWT tokens for subscribers (read-only).
• webrtc_room_name — WebRTC room name.
• webrtc_url — WebRTC server URL.
• ws_url — WebSocket streaming/management API URL.
• ws_tts_url — WebSocket URL for the Realtime TTS API.
• intent — session intent.
• id — session ID.

---

List Active Sessions

Endpoint: GET /session-storage/sessions

Headers:

• ClientID
• ClientSecret

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
ClientID: <your-client-id>
ClientSecret: <your-client-secret>

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:

• ClientID
• ClientSecret

Path Params:

• session_id (string): ID of the session.

Example Request:

GET /session-storage/sessions/{session_id} HTTP/1.1
Host: api.palabra.ai
ClientID: <your-client-id>
ClientSecret: <your-client-secret>

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:

• ClientID
• ClientSecret

Path Params:

• session_id (string): ID of the session.

Example Request:

DELETE /session-storage/sessions/{session_id} HTTP/1.1
Host: api.palabra.ai
ClientID: <your-client-id>
ClientSecret: <your-client-secret>

Response: HTTP 204 No Content

API Reference: Delete user session by ID

---

Update Session Expiration

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

Headers:

• ClientID
• ClientSecret
• 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
ClientID: <your-client-id>
ClientSecret: <your-client-secret>
Content-Type: application/json

Response: HTTP 204 No Content

API Reference: Update Session Expiration