Session Management

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

Introduction

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

Sessions lifetime cycle

• Each session has an expires_at timestamp (available via Get user session by ID). If you haven’t connected before this time, the session will be invalidated.
• You can extend expires_at manually using the Update Session Expiration request.
• Once connected, expires_at is set to the current time and automatically extended every minute while the connection is active.
• There's a limit (based on your plan) on how many sessions you can open in parallel. It's best to delete unused sessions instead of waiting for them to time out.

---

Authorization

All endpoints require the following headers:

• ClientID: Unique client application identifier.
• ClientSecret: Client application secret key.

Visit Obtaining API Keys to get ClientID and ClientSecret

---

Create Streaming Session

Endpoint: POST /session-storage/session

Headers:

• ClientID: Unique client application identifier.
• ClientSecret: Client application secret key.
• 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/",
    "intent": "api",
    "id": "session-id"
  }
}

• publisher: JWT token for 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 management API URL.
• intent: Session intent.
• id: Session ID.

---

List Active Sessions

Endpoint: GET /session-storage/sessions

Headers:

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

Response: HTTP 204 No Content

API Reference: Update Session Expiration