---
title: "Create a session"
method: POST
path: "/session-storage/v2/sessions"
tags: ["Sessions v2"]
---

# Create a session

`POST /session-storage/v2/sessions`

## Request

- Base URL: `https://api.palabra.ai`
- URL: `https://api.palabra.ai/session-storage/v2/sessions`
- Auth: API key in header `Authorization`

Creates a session and returns its `token`.
The token is returned here and in `GET /v2/sessions/{id}`.
List responses do not include it.

Repeating the call with the same `client_reference_id` creates an independent session.
Each session has its own `id`, `token` and lifetime.

## Request body

- V2CreateSessionRequest
  - `intent` 's2s' | 'stt' | 'tts', required: Product the session token is valid for: - `s2s`: speech-to-speech translation - `stt`: speech-to-text - `tts`: text-to-speech A token presented to a different product is refused.
  - `connection_type` 'ws' | 'webrtc': Transport the end user will connect with. `webrtc` is available for `s2s` only. A token issued for one transport cannot be used with the other.
  - `expires_in_seconds` integer: Connect window: how long after creation the token can open a new stream. Streams already running are not affected when the window closes. To extend, issue a new session.
  - `max_session_duration_seconds` integer: Maximum duration of any single stream opened with this token, counted from that stream's own start. The stream is closed when it is reached. When omitted, streams are limited only by your account limits.
  - `single_use` boolean: `true`: the token opens exactly one stream in its lifetime. A second connection while that stream is running is refused, usually with HTTP 409 `session_in_use`. After the stream ends, every connection is refused with HTTP 409 `session_already_used`. In both cases the application must request a new session; connecting again with the same token does not help. `false`: the token can open several streams, one after another, until the connect window closes. One connection is live at a time. Over `ws` a second connection while the first one is live is refused with HTTP 409 `session_in_use`; connect again after the first one ends. Over `webrtc` a new connection replaces the previous one. The live stream counts toward your concurrent session limit.
  - `client_reference_id` string: Your own identifier for the customer, device or order this session belongs to. Stored as is, not unique, and used to filter sessions and usage. Set it from your server; end users cannot change it.
  - `subscriber_count` integer: Number of listener tokens to issue alongside the publisher token. Available for `s2s` over `webrtc` only. Listener tokens can join the room and receive the translation but cannot publish audio or change the translation task. Listeners do not count toward your concurrent session limit.

## Response `201`

Session created.

- V2SessionResponse
  - `ok` true, required
  - `data` V2Session, required
    - `id` string, required: Session identifier. Use it to inspect, revoke and report on the session.
    - `token` string: Credential the end user connects with. Returned by `POST /v2/sessions` and `GET /v2/sessions/{id}` only.
    - `intent` 's2s' | 'stt' | 'tts', required: Product the session token is valid for: - `s2s`: speech-to-speech translation - `stt`: speech-to-text - `tts`: text-to-speech A token presented to a different product is refused.
    - `connection_type` 'ws' | 'webrtc', required: Transport the end user will connect with. `webrtc` is available for `s2s` only. A token issued for one transport cannot be used with the other.
    - `single_use` boolean, required: `true` if the token opens only one stream in its lifetime.
    - `client_reference_id` string: Your identifier from the create request.
    - `status` 'pending' | 'active' | 'idle' | 'used' | 'expired' | 'revoked', required: - `pending`: issued, no stream opened yet, connect window still open - `active`: at least one stream is running - `idle`: reusable token that has been used before, no stream running, connect window still open - `used`: single-use token whose stream has finished; cannot be used again - `expired`: connect window has passed and no stream is running - `revoked`: revoked by you
    - `created_at` string, date-time, required: When the session was created.
    - `connect_by` string, date-time, required: Moment after which the token can no longer open a new stream.
    - `max_session_duration_seconds` integer: Duration cap applied to each stream, if one was set.
    - `first_connected_at` string, date-time, nullable: When the first stream was opened with this token, or `null` if none yet.
    - `active_stream_count` integer, required: Number of streams running with this token.
    - `webrtc` V2WebRtcDetails: Present for `connection_type: webrtc` only.
      - `url` string, required: WebRTC endpoint the publisher and listeners connect to.
      - `room_name` string, required: Room the session runs in.
      - `subscriber_keys` string[]: Listener tokens, one per requested subscriber. Returned on creation only.

## Other responses

- `401` (unresolved $ref)
- `402` (unresolved $ref)
- `403` (unresolved $ref)
- `422` (unresolved $ref)
- `424` (unresolved $ref)
- `429` (unresolved $ref)
- `500` (unresolved $ref)

## Changes

- **2026-11-03** `d4a64c9469d4`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/palabra/apis/palabra-api/changes/session-storage/v2/sessions/post.md)

---

[API](https://skmtc.dev/palabra/apis/palabra-api.md) - [All operations](https://skmtc.dev/palabra/apis/palabra-api/llms.txt) - [OpenAPI document](https://skmtc.dev/palabra/apis/palabra-api/revisions/d4a64c9469d4?raw)