Stream API

You can create and manage RTMP live streams in rooms via API. Creating a stream returns RTMPS ingest credentials (server and stream key for OBS or any RTMP encoder) and an HLS playback URL. Every broadcast session is recorded automatically and is available as VOD.

Each room has one stream: the create endpoint is idempotent and always returns the credentials of the room's current stream. The externalRoomId is the same room ID used in the Room API.

Create or get a stream

Creates a stream for the room and returns ingest credentials. If the room already has an active stream, the existing credentials are returned — the call is idempotent and safe to repeat.

Endpoint https://stream.watchers.io/stream/rooms/:externalRoomId

Method PUT

Body application/json (optional)

Path parameter

Body

curl -X 'PUT' \
  'https://stream.watchers.io/stream/rooms/liveevent123' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {Api key of project from admin panel}' \
  -H 'Authorization: Bearer {Bearer token from admin panel}'

Response

{
  "provider": "cloudflare",
  "streamKey": "d6f3ffb32bdd3fa8b4d4d8284740b6f5k80ee15af9c419fda12f8e2f4a725c40",
  "streamServer": "rtmps://live.cloudflare.com:443/live/",
  "streamUrl": "https://customer-ab12cd34.cloudflarestream.com/8f4e2b1c9d3a4f6e8b0c2d4e6f8a0b1c/manifest/video.m3u8",
  "playbackUrl": "https://customer-ab12cd34.cloudflarestream.com/8f4e2b1c9d3a4f6e8b0c2d4e6f8a0b1c/manifest/video.m3u8"
}

Notes

• streamServer and streamKey are the ingest credentials for your encoder: in OBS set Settings → Stream → Service: Custom, Server = streamServer, Stream Key = streamKey.
• playbackUrl is a public HLS manifest (.m3u8). It plays in any HLS player (hls.js, Video.js, native Safari). Typical end-to-end latency is 10–20 seconds. streamUrl is a legacy alias of playbackUrl.
• The credentials are reusable: you can stop and start broadcasting through the same stream many times (including recurring and 24/7 rooms). Each broadcast session is saved as a separate recording.
• Streams that stay idle for over two weeks are cleaned up and their credentials are revoked. The call is idempotent, so simply repeat it before going live to make sure your credentials are current — recordings are not affected by the cleanup.
• When the broadcast starts, the stream automatically appears in the room player on the Watchers frontend — no extra API calls are needed.

Get stream status

Endpoint https://stream.watchers.io/stream/rooms/:externalRoomId

Method GET

Path parameter

curl -X 'GET' \
  'https://stream.watchers.io/stream/rooms/liveevent123' \
  -H 'accept: application/json' \
  -H 'x-api-key: {Api key of project from admin panel}' \
  -H 'Authorization: Bearer {Bearer token from admin panel}'

Response

{
  "id": 42,
  "provider": "cloudflare",
  "project": "yourproject",
  "externalRoomId": "liveevent123",
  "isLive": true,
  "streamKey": "d6f3ffb32bdd3fa8b4d4d8284740b6f5k80ee15af9c419fda12f8e2f4a725c40",
  "streamServer": "rtmps://live.cloudflare.com:443/live/",
  "playbackUrl": "https://customer-ab12cd34.cloudflarestream.com/8f4e2b1c9d3a4f6e8b0c2d4e6f8a0b1c/manifest/video.m3u8",
  "videoUrl": "https://customer-ab12cd34.cloudflarestream.com/2c1d0e9f8a7b6c5d4e3f2a1b0c9d8e7f/manifest/video.m3u8",
  "createdAt": "2026-07-08T12:00:00.000Z",
  "streamEndedAt": null
}

Notes

• isLive switches to true when the encoder connects and back to false when it disconnects.
• videoUrl is the HLS URL of the latest finished recording. It is null until the first recording has been processed.
• streamEndedAt is the time the last broadcast session ended; it is null while the stream is live.

Stop and delete a stream

Ends the broadcast, revokes the ingest credentials and removes the stream from the room.

Endpoint https://stream.watchers.io/stream/rooms/:externalRoomId

Method DELETE

Path parameter

curl -X 'DELETE' \
  'https://stream.watchers.io/stream/rooms/liveevent123' \
  -H 'accept: application/json' \
  -H 'x-api-key: {Api key of project from admin panel}' \
  -H 'Authorization: Bearer {Bearer token from admin panel}'

Response

{
  "deleted": true
}

Notes

• Only the stream is deleted — the room itself is not affected. Rooms are managed separately via the Room API.
• Recordings are not deleted — they remain available via the recordings endpoint (see “List recordings” below).
• After deletion, a new PUT request creates a fresh stream with new credentials. The old stream key stops working.

List recordings

Returns all recordings (VOD) made in the room, newest first.

Endpoint https://stream.watchers.io/stream/rooms/:externalRoomId/videos

Method GET

Path parameter

curl -X 'GET' \
  'https://stream.watchers.io/stream/rooms/liveevent123/videos' \
  -H 'accept: application/json' \
  -H 'x-api-key: {Api key of project from admin panel}' \
  -H 'Authorization: Bearer {Bearer token from admin panel}'

Response

[
  {
    "id": 7,
    "project": "yourproject",
    "externalRoomId": "liveevent123",
    "slug": "2c1d0e9f8a7b6c5d4e3f2a1b0c9d8e7f",
    "duration": 5400000,
    "url": "https://customer-ab12cd34.cloudflarestream.com/2c1d0e9f8a7b6c5d4e3f2a1b0c9d8e7f/manifest/video.m3u8",
    "createdAt": "2026-07-08T12:00:00.000Z"
  }
]

Notes

• duration is in milliseconds.
• url is a public HLS manifest of the recording, playable in any HLS player.
• A recording appears in the list within a few minutes after the broadcast session ends.
• Recordings survive stream deletion, so the full VOD history of the room is always available here.

Errors