Create a realtime browser session

POST

/v1/realtime/sessions

Reserve credits and allocate a short-lived BeatAPI realtime session. Send a unique
Idempotency-Key; retries with the same user, key, and body return the same session
and deterministic short-lived client_secret without reserving credits or capacity
twice. The browser receives only that BeatAPI secret and connects with
@beatapi/realtime.

Billing is fixed by the selected maximum duration. The BeatAPI browser runtime sends its
first billing heartbeat only after the first remote output frame is rendered. When that
accepted BeatAPI billing heartbeat succeeds, the Session becomes active and the selected
duration is fully settled. A Session that closes or expires without an accepted billing
heartbeat is fully refunded. Billing activation comes from the trusted transport lifecycle,
not a caller-supplied browser event.
Production availability remains gated until the documented commercial and capacity launch
checks pass.

Request

Authorization

Bearer Token

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Header Params

Body Params application/jsonRequired

Examples

Responses

🟢201

application/json

Realtime session created

Bodyapplication/json

🟠402

🟠409

🔴503

🟠400BadRequest

🟠401Unauthorized

🟠429RateLimited

Request Example

Shell

JavaScript

Java

Swift

curl --location 'https://api.beatapi.io/v1/realtime/sessions' \
--header 'Idempotency-Key;' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
    "max_duration_seconds": 60,
    "allowed_origins": [
        "https://app.example.com"
    ],
    "metadata": {
        "customer_id": "cus_123"
    }
}'

Response Example

201 - Example 1

{
    "data": {
        "id": "string",
        "object": "realtime.session",
        "status": "ready",
        "client_secret": "string",
        "expires_at": "2019-08-24T14:15:22.123Z",
        "max_duration_seconds": 15,
        "allowed_origins": [
            "http://example.com"
        ],
        "credits": {
            "reserved": 0,
            "settled": 0,
            "refunded": 0
        },
        "request_id": "string",
        "created_at": "2019-08-24T14:15:22.123Z",
        "connected_at": "2019-08-24T14:15:22.123Z",
        "closed_at": "2019-08-24T14:15:22.123Z"
    }
}

Modified at 2026-07-31 15:09:00

Delete a webhook endpoint

Get a realtime session