Skip to main content
POST
Create viewer token

What it’s for

Watching your own stream — a monitoring dashboard, a debug view, or any UI that should show the video the model sees. The token is subscribe-only: it cannot publish media or data-channel messages, so it is safe to hand to a display-only client. Only the stream owner can request one; other API keys get a 404.

How to use it

Connect with any LiveKit client SDK and render the remote video track:
Tokens expire after view.expires_in_seconds (currently 300). A connected session survives token expiry, but reconnecting after expiry requires a fresh token — request a new one from this endpoint.

Authorizations

Authorization
string
header
required

Every public HTTP request requires Authorization: Bearer <api_key>, except GET /models and the public /billing/pricing endpoints.

  • 401 means the key is missing, unknown, or revoked.
  • 403 means the key is valid but cannot access the requested resource.
  • The publish token returned by POST /streams is only for publishing media to LiveKit. It does not replace the API key for HTTP calls.

Headers

X-Overshoot-Region
enum<string>

Optional hint to route the request to the region that owns the stream. If the request reaches the wrong region the API returns 409 with a region_error body.

Available options:
us-west1,
us-central1

Path Parameters

stream_id
string<uuid>
required

UUID returned by POST /streams.

Response

Viewer token issued.

id
string<uuid>
required

The stream identifier the token was issued for.

view
object
required

WebRTC view target. Connect with the LiveKit client SDK and subscribe to the remote video track.