A live stream is an RTC room plus a chat conversation: one host broadcasts, many viewers watch and chat. Your backend calls these endpoints with the project API key.
- Creating a stream creates both.
- A host or viewer credential includes tokens for both, ready for
LiveStream.join().
When you'd call them in a real app: create the stream when a host
schedules a webinar, add a host to get the host's credential, make a
viewer token each time someone opens the watch page, and end the
stream when the host is done. ENDED is final.
More: Streams & lifecycle.
Endpoints
GET/v1/live-streams
List the project's live streams
Credential Project API key
No parameters.
POST/v1/live-streams
Create a live stream — a dedicated RTC room plus an attached chat conversation
Credential Project API key · Rate limit 30 per window (details) · Idempotent send Idempotency-Key to replay safely
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
title | body | string | Yes | 1–200 chars |
hostIdentity | body | string | Yes | 1–128 chars, pattern-checked — The developer's own identity for whoever is starting this stream. Registered as its HOST — the only identity a stream is created with, and the only one whose role is ever HOST rather than CO_HOST. |
description | body | string | No | 0–2000 chars |
thumbnailUrl | body | string | No | 0–2048 chars — A URL you host — Livqeno does not accept or store thumbnail uploads. |
category | body | string | No | 0–64 chars |
tags | body | string[] | No | array |
language | body | string | No | 0–16 chars |
visibility | body | LiveStreamVisibility | No | PUBLIC · PRIVATE · AUTHENTICATED |
metadata | body | Record<string, unknown> | No | Your own JSON, capped at 4 KB — same convention as Room/Conversation metadata. |
scheduledAt | body | string | No | When set, the stream is created for a future start — see docs/live-streaming/overview.md#scheduled-streams. Livqeno does not automatically transition status at this time; your backend still calls start(). |
deliveryMode | body | LiveStreamDeliveryMode | No | RTC_ONLY · BROADCAST — RTC_ONLY (default): viewers get an RTC credential and join the room, same as today. BROADCAST: the |
edgeScaling | body | boolean | No | RTC_ONLY streams: past the origin room's share, seat viewers on edge rooms on other SFU nodes so the |
GET/v1/live-streams/{streamId}
Get a stream, including its live viewer count
Credential Project API key
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
streamId | path | string | Yes |
PATCH/v1/live-streams/{streamId}
Update a stream's metadata — title, description, thumbnail, visibility, etc.
Credential Project API key
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
streamId | path | string | Yes | |
title | body | string | No | 1–200 chars |
description | body | string | No | 0–2000 chars |
thumbnailUrl | body | string | No | 0–2048 chars |
category | body | string | No | 0–64 chars |
tags | body | string[] | No | array |
language | body | string | No | 0–16 chars |
visibility | body | LiveStreamVisibility | No | PUBLIC · PRIVATE · AUTHENTICATED |
metadata | body | Record<string, unknown> | No |
POST/v1/live-streams/{streamId}/end
LIVE → ENDED. Terminal — an ended stream cannot be restarted; create a new one.
Credential Project API key
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
streamId | path | string | Yes |
POST/v1/live-streams/{streamId}/hosts
Register a host/co-host and mint their RTC + chat credentials
Credential Project API key · Rate limit 60 per window (details)
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
streamId | path | string | Yes | |
identity | body | string | Yes | 1–128 chars, pattern-checked |
role | body | LiveStreamHostRole | No | HOST · CO_HOST — HOST and CO_HOST get identical RTC/chat grants — the difference is bookkeeping, not permissions. A stream already has a HOST (set at creation); this is normally CO_HOST. Omit it for someone already registered and their existing role is kept, so re-minting a host's credentials never demotes them. |
DELETE/v1/live-streams/{streamId}/hosts/{identity}
Remove a co-host — soft removal, their history in the stream chat is preserved
Credential Project API key
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
streamId | path | string | Yes | |
identity | path | string | Yes |
DELETE/v1/live-streams/{streamId}/ingress
Delete the ingress, revoking its key and disconnecting any encoder
Credential Project API key
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
streamId | path | string | Yes |
GET/v1/live-streams/{streamId}/ingress
Get the stream's ingress and the encoder's live status — never the key
Credential Project API key
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
streamId | path | string | Yes |
POST/v1/live-streams/{streamId}/ingress
Create the stream's encoder ingest (OBS & co.) and get its stream key
Credential Project API key · Rate limit 30 per window (details)
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
streamId | path | string | Yes | |
protocol | body | LiveStreamIngressProtocol | No | WHIP · RTMP — Which encoder protocol this key is for. RTMP covers RTMPS too. |
identity | body | string | No | 1–128 chars, pattern-checked — Host identity the encoder joins the room as. Defaults to the stream's HOST, so an OBS session and a browser |
autoStart | body | boolean | No | Start a CREATED stream automatically when the encoder connects. |
reconnectWindowSec | body | number | No | 0–300 — Seconds the room stays joined after the encoder drops, so a quick reconnect resumes seamlessly. |
POST/v1/live-streams/{streamId}/ingress/reset
Rotate the ingest stream key and disconnect any encoder using the old one
Credential Project API key · Rate limit 30 per window (details)
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
streamId | path | string | Yes |
POST/v1/live-streams/{streamId}/leave
Signal that a viewer left, for live_stream.viewer_left
Credential Project API key
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
streamId | path | string | Yes | |
identity | body | string | Yes | 1–128 chars, pattern-checked |
GET/v1/live-streams/{streamId}/playback
Get broadcast playback info — the HLS URL for a BROADCAST-mode stream
Credential Project API key
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
streamId | path | string | Yes |
GET/v1/live-streams/{streamId}/restreams
List a stream's restream destinations with their live status
Credential Project API key
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
streamId | path | string | Yes |
POST/v1/live-streams/{streamId}/restreams
Add an RTMP/RTMPS restream destination (YouTube, Twitch, ...)
Credential Project API key · Rate limit 30 per window (details)
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
streamId | path | string | Yes | |
url | body | string | Yes | 1–2048 chars — rtmp:// or rtmps:// ingest URL of the destination, without the stream key. No credentials or query string — |
streamKey | body | string | Yes | 1–512 chars — The destination stream key. Write-only: stored encrypted, never returned (only its last 4 characters). |
label | body | string | No | 0–100 chars |
DELETE/v1/live-streams/{streamId}/restreams/{restreamId}
Stop and remove a restream destination, deleting its stored key
Credential Project API key
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
streamId | path | string | Yes | |
restreamId | path | string | Yes |
PATCH/v1/live-streams/{streamId}/restreams/{restreamId}
Pause/resume (enabled) or rename a restream destination, mid-stream too
Credential Project API key
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
streamId | path | string | Yes | |
restreamId | path | string | Yes | |
enabled | body | boolean | No | false pauses the destination (mid-stream too); true resumes it. |
label | body | string | No | 0–100 chars |
POST/v1/live-streams/{streamId}/stage/demote
Take a co-host off stage
Credential Project API key
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
streamId | path | string | Yes | |
identity | body | string | Yes | 1–128 chars, pattern-checked |
POST/v1/live-streams/{streamId}/stage/invites
Invite a viewer on stage
Credential Project API key
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
streamId | path | string | Yes | |
identity | body | string | Yes | 1–128 chars, pattern-checked |
POST/v1/live-streams/{streamId}/stage/promote
Bring a viewer on stage as a co-host (Agora setClientRole)
Credential Project API key · Rate limit 60 per window (details)
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
streamId | path | string | Yes |
POST/v1/live-streams/{streamId}/start
CREATED → LIVE
Credential Project API key
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
streamId | path | string | Yes |
POST/v1/live-streams/{streamId}/viewer-tokens
Mint a viewer's RTC + chat credentials
Credential Project API key · Rate limit 120 per window (details)
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
streamId | path | string | Yes | |
identity | body | string | Yes | 1–128 chars, pattern-checked — The viewer's identity, from your own authenticated session — never trusted from an unauthenticated client. Always minted with subscribe-only RTC permissions; there is no field here that can request publish access. |
acceptPlayback | body | boolean | No | Set true if your client can play HLS (@livqeno/live can). A BROADCAST stream then returns a playback |
Next steps
- Conventions: base URL, errors, request ids, pagination.
- Errors: every error code and how to fix it.
- All endpoints: every endpoint on one page.