Session Management

API for manual session management. Optional for Websocket APIs, required for WebRTC API.

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.

Manage your API sessions manually: create a session and get the JWT access token which can be used to connect to the WebRTC and Websocket Palabra APIs, list and inspect active sessions, extend their lifetime, and delete them.

Manual session management is required for WebRTC connections — you must create a session first to get the JWT access token and use it to connect to WebRTC room at provided webrtc_url.

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/",
    "intent": "api",
    "id": "session-id"
  }
}

• publisher — JWT access token for the publisher.
• webrtc_url — WebRTC 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