Realtime API | BeatAPI API Documentation

curl -X POST https://api.beatapi.io/v1/realtime/sessions \
     -H "Idempotency-Key: rts-create-cus_123-01" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "max_duration_seconds": 60,
  "allowed_origins": [
    "https://app.example.com"
  ],
  "metadata": {
    "customer_id": "cus_123"
  }
}'

{
  "data": {
    "id": "rts_8K2qA",
    "object": "realtime.session",
    "status": "ready",
    "expires_at": "2026-08-12T10:01:00.000Z",
    "max_duration_seconds": 60,
    "allowed_origins": [
      "https://app.example.com"
    ],
    "credits": {
      "reserved": 1.2,
      "settled": 0,
      "refunded": 0
    },
    "request_id": "req_abc123",
    "created_at": "2026-08-12T10:00:00.000Z",
    "connected_at": null,
    "closed_at": null,
    "client_secret": "brt_live_example_short_lived_secret"
  }
}

Create a short-lived Realtime API browser session and receive a client secret for the BeatAPI realtime SDK.

Create the Session on your trusted server, pass only client_secret to the browser, connect with @beatapi/realtime, and close the Session when the experience ends. See the Quick Guide for the security and lifecycle checklist.

Create a short-lived Realtime API browser session and receive a client secret for the BeatAPI realtime SDK. Create the Session on your trusted server, pass only `client_secret` to the browser, connect with `@beatapi/realtime`, and close the Session when the experience ends. See the [Quick Guide](/quick-guide) for the security and lifecycle checklist.

Authentication

AuthorizationBearer

Send your API key as Authorization: Bearer <BEATAPI_API_KEY>.

Request

This endpoint expects an object.

max_duration_secondsenumRequired

Required maximum live session duration in seconds. The USD amount is reserved for the selected 15, 60, or 300 second tier.

Allowed values:

allowed_originslist of stringsRequired

Exact browser origins allowed to use the short-lived session secret.

metadatamap from strings to stringsOptional

Optional server-defined string metadata for your own correlation. Up to 20 keys; keys are at most 64 characters and values at most 256 characters.

Response

Realtime session created

dataobject

Created Realtime Session including the one-time short-lived browser credential.

Errors

400

Bad Request Error

401

Unauthorized Error

402

Payment Required Error

409

Conflict Error

429

Too Many Requests Error

503

Service Unavailable Error

Authentication

Headers

Request

Response

Errors