Live Streaming (VP Live) API Documentation

Author: Josh S. Sakweli, Backend Lead Team Last Updated: 2026-08-20 Version: v1.0

Base URL: http://localhost:8765/api/v1 (local) — server.port=8765

Short Description: VP Live is one-to-many broadcasting: a host publishes, an audience watches over HLS through the CDN. Four surfaces sit here — Streams (lifecycle and ingest), Comments (the live overlay), Attachments (the commerce shelf) and Spaces (many speakers, an HLS audience). Media goes host → SRS → CDN → viewers; the backend never carries a frame.

Hints:

• Every endpoint needs Authorization: Bearer <token> unless noted.
• There is no "go live" endpoint. A host asks for an ingest key and publishes; the stream turns LIVE when SRS reports media arriving. A client never sets state — the media server is the authority.
• playbackUrl is null until media actually flows. Handing it out earlier gives a player a URL that 404s, which reads as broken rather than as not-started-yet.
• The comment read endpoint is CDN-cached and returns a bare array, not the platform envelope. It is the one endpoint served at volume.
• Refusals are 409 with a code (404 for NOT_FOUND).

Standard Response Format

{
  "success": true,
  "httpStatus": "OK",
  "message": "Stream created",
  "action_time": "2026-08-20T10:30:45",
  "data": { }
}

Refusals

409 CONFLICT (or 404 when the code is NOT_FOUND). For streams, attachments and comments the envelope message carries the code:

{
  "success": true,
  "httpStatus": "CONFLICT",
  "message": "NOT_HOST",
  "data": { "code": "NOT_HOST", "reason": "This is not your stream" }
}

Spaces are shaped the other way round — message is the prose and data holds only { "code": … }. Read data.code in both cases and you are safe.

Part 1 — Streams

api/v1/live/streams

Why there is no "go live" button

HOST                          BACKEND                 SRS                VIEWERS
 |                               |                     |                    |
 |-- POST /live/streams -------->| DRAFT               |                    |
 |   {title, mode}               |                     |                    |
 |                               |                     |                    |
 |   [ device-check screen; host is actually ready ]   |                    |
 |-- POST /{id}/ingest-key ----->| mint key            |                    |
 |<-- {ingestKey, whipUrl, rtmpUrl, expiresAt}         |                    |
 |                               |                     |                    |
 |======== publish (WHIP or RTMP) ====================>|                    |
 |                               |<-- hooks /publish --|                    |
 |                               |  state STARTING     |   (nothing to play)|
 |                               |                     |                    |
 |                               |<-- hooks /hls ------|  first segment closed
 |                               |  state LIVE         |                    |
 |                               |  announce + notify ====================> |
 |                               |                     |   playbackUrl now set
 |                               |                     |                    |
 |-- POST /{id}/end ------------>| ENDED               |                    |
 |                               |<-- hooks /dvr ------|  recording ready   |
 |                               |  PROCESSING -> REPLAY_READY              |

The point to make in a demo: STARTING exists so that announcing a stream never sends followers to an empty player. RTMP takes ~8 seconds to produce a first segment, and WHIP can take a minute. LIVE is the first moment the word is true for anybody except the host.

Stream state machine

  DRAFT ─────┐
             ├──> STARTING ──> LIVE ──> ENDED ──> PROCESSING ──> REPLAY_READY
  SCHEDULED ─┘                                          └──> FAILED
      └──(abandoned ~1 day, silently)──> ENDED

REPLAY_READY rather than VOD_READY on purpose: "video on demand" is wrong for AUDIO_RADIO, which has no video, and a state named after a format the mode does not produce quietly teaches the next reader something false.

Modes

Radio publishes into its own SRS app, which is what scopes the 32 kbps transcode to the streams that actually need it. Mode is chosen at creation and never changed — switching mid-session renegotiates every participant's media and resets every HLS player.

(Spaces used to be a third mode. They now have their own entity and their own endpoints — see Part 4.)

POST /api/v1/live/streams — Create

Setup only. Nothing is live and nothing costs anything — the host may fill it in, leave, and come back.

Request (CreateStreamRequest):

Returns StreamResponse.

POST /api/v1/live/streams/{streamId}/ingest-key — Get broadcast credentials

Called from the device-check screen, once the host is actually ready. This is the only place an ingest key is ever returned. Host only.

Response:

{
  "streamId": "…",
  "ingestKey": "…",
  "expiresAt": "2026-08-20T…",
  "whipUrl": "http://127.0.0.1:1985/rtc/v1/whip/?app=live&stream=<ingestKey>",
  "rtmpUrl": "rtmp://127.0.0.1/live/<ingestKey>"
}

The stream name a publisher uses is the key itself — that is what lets SRS hand it to us for checking without any other channel.

POST /api/v1/live/streams/{streamId}/end — End the broadcast

Host only. Returns StreamResponse with state: ENDED.

PUT /api/v1/live/streams/{streamId}/reminder — Remind me

A PUT with wanted=false rather than a DELETE route, because "remind me" is one toggle in the UI.

GET /api/v1/live/streams/{streamId} — Read a stream

StreamResponse

Note what is absent: ingestKey. It is a broadcast credential, returned only from the endpoint the host calls to get one, and never carried on an object that viewers also read.

playbackUrl is gated on state, not on replayMediaId being set — that id is stored the moment the recording is handed to File Thunder, so during PROCESSING it exists but points at nothing playable yet.

Stream refusal codes

Part 2 — Live comments

api/v1/live/streams/{streamId}/comments

A write endpoint and a read endpoint, and the difference between them is the whole design.

   viewer ──POST──> origin        (per viewer, rate limited, moderated)

   10 000 viewers ──GET──> [ CDN, 2s cache ] ──one read──> origin

The write is per viewer and rate limited. The read is the same response for everybody, cached at the CDN for two seconds — one origin read serving thousands. That is why it takes no parameters: a since cursor would give every viewer a unique URL and turn the cache off. The client drops what it has already rendered using the per-stream monotonic seq.

POST …/comments — Post a comment

Request: { "body": "…" }

Refuses unless the stream is LIVE. Then moderation runs:

On success returns the posted LiveComment to the poster, even though the read window may sample it away for everyone else. A viewer always sees their own comment — it is what makes the feature feel alive when a comment reached nobody.

GET …/comments — Read the overlay

No parameters. Identical for every viewer. Cache-Control: public, max-age=2.

Deliberately not wrapped in the platform envelope — the payload is the comments:

[
  { "seq": 412, "userId": "…", "name": "Mama Yoyo", "body": "bei gani?",
    "at": 1755680000000, "system": false, "event": null, "refId": null }
]

A comment is deliberately not shaped like a chat message: no conversation, no recipient, no delivery guarantee, no id the sender can retry against.

Host tools

Both host-only; a non-host gets 409 NOT_HOST.

Part 3 — Attachments (the commerce shelf)

api/v1/live/streams/{streamId}/attachments

Host verbs are attach, pin, unpin and remove; the only viewer verbs are reading the shelf and tapping through. Pinning is a live act — most attachments arrive while the host is talking, not at setup.

All types are equal — attach any number, of any type, from any shop, at any point in the stream's life.

AttachmentResponse

Part 4 — Spaces

api/v1/live/spaces — many speakers, audio, an HLS audience.

The cost model, which is the whole design

  HOST + COHOSTs + SPEAKERs  ──WebRTC──> [ LiveKit SFU ]
                                              |
                                    Egress mixes the stage
                                              |
                                          RTMP ──> [ SRS ] ──> HLS ──> [ CDN ]
                                                                          |
                                        LISTENERS ────────────────────────┘

Note which endpoints return a token and which do not. Opening the stage and being promoted return one; joining as a listener never does. That asymmetry IS the cost model — a token is what would put the audience on the SFU. An audience of ten thousand on LiveKit would need ten thousand SFU downstreams; on HLS it is one CDN origin.

Stage cap: 10 by default (app.live.space-stage-limit). A product limit, not an infrastructure one — Egress was measured carrying 10+ concurrent Spaces. A conversation with twenty people talking is not a conversation.

SpaceState mirrors the stream states: DRAFT, SCHEDULED, STARTING, LIVE, ENDED, PROCESSING, REPLAY_READY, FAILED. Same rule — LIVE happens because SRS reported the mixed audio arrived, not because the host's app said so.

Endpoints

The riskiest thing in this feature: the token returned by promote is a permission, not a connection. Crossing from HLS playback to a LiveKit publish without a gap in audio is the client's problem.

Space refusal codes

Part 5 — SRS hooks (internal)

api/v1/live/hooks — SRS → backend. Not for clients. These are what actually drive stream state:

Configuration

SRS treats Egress as an ordinary broadcaster, so the ingest key is the credential exactly as it is for a phone publishing a stream.