VoltKit RTC API Reference

The API has two parts. Your backend calls the REST API with an API secret. Your clients connect to the realtime API with a token your backend minted.

Every REST call below is shown three ways: the HTTP request, the reply, and the SDK call that makes it for you. The SDK lines use the Node.js server SDK; nothing requires it, and any HTTP client in any language works.

Making a request

All REST requests go to your API base URL (on your project's Credentials tab) and are authenticated with your API secret. Bodies and replies are JSON.

curl -X POST "$VOLTKIT_RTC_URL/v1/rooms" \
  -H "X-API-Key: $VOLTKIT_RTC_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"roomId":"show-42","hostIdentity":"user-7"}'

const { StreamClient } = require("@voltkit-rtc/server");
const rtc = new StreamClient({ baseUrl: process.env.VOLTKIT_RTC_URL, apiKey: process.env.VOLTKIT_RTC_SECRET });

Authorization: Bearer sk_... is accepted as well as X-API-Key.

Times named createdAt, startedAt and ts are milliseconds since the epoch. expiresAt is seconds.

When a request fails

An error is JSON with a machine-readable error and a readable message. Decide on error, show or log message.

{ "error": "room-exists", "message": "a room with that id already exists" }

Any authenticated call can also fail with 401 unauthorized, 403 tenant-suspended, 429 rate-limited or 500 internal. Those are not repeated under each endpoint. Every code, what it means and what to do about it is on the Errors page.

With the SDK, a failure is a StreamError carrying the same code:

try {
  await rtc.createRoom({ roomId: "show-42", hostIdentity: "user-7" });
} catch (err) {
  console.log(err.code, err.status, err.retryable);   // "room-exists" 409 false
}

REST: rooms

Create a room

Creates a room and returns a token for its host. roomId is yours to choose (letters, digits, ., -, _, up to 128) and is generated if you leave it out. metadata is any JSON you want every participant to receive when they join.

Request:

{
  "roomId": "show-42",
  "hostIdentity": "user-7",
  "metadata": {
    "layout": "grid"
  }
}

Response, 201 Created:

{
  "roomId": "show-42",
  "tenantId": "vk_3f9c1a7b2d4e6f80",
  "originNode": "node-1",
  "state": "live",
  "hostIdentity": "user-7",
  "createdAt": 1791048388384,
  "nodes": [
    "node-1"
  ],
  "participants": 0,
  "metadata": {
    "layout": "grid"
  },
  "hostToken": "eyJhbGciOi...",
  "wsUrl": "wss://rtc.example.com/ws",
  "expiresAt": 1791048988
}

Errors:

Create or get a room

Creates the room, or returns the live one with a fresh host token if it already exists. This is the call to use when a host may be reconnecting. metadata is only applied when the room is created.

Request:

{
  "hostIdentity": "user-7"
}

Response, 201 Created, or 200 OK if it already existed:

{
  "roomId": "show-42",
  "tenantId": "vk_3f9c1a7b2d4e6f80",
  "originNode": "node-1",
  "state": "live",
  "hostIdentity": "user-7",
  "createdAt": 1791048388384,
  "nodes": [
    "node-1"
  ],
  "participants": 0,
  "metadata": {
    "layout": "grid"
  },
  "hostToken": "eyJhbGciOi...",
  "wsUrl": "wss://rtc.example.com/ws",
  "expiresAt": 1791048988
}

Errors:

Mint a token

Lets one user into the room. role is host, cohost, moderator or viewer, and defaults to viewer. Your backend decides the role; the service enforces it. Hand token and wsUrl to the client SDK.

Request:

{
  "identity": "user-99",
  "role": "viewer"
}

Response, 200 OK:

{
  "token": "eyJhbGciOi...",
  "wsUrl": "wss://rtc.example.com/ws",
  "role": "viewer",
  "identity": "user-99",
  "roomId": "show-42",
  "expiresAt": 1791048988
}

Errors:

Get a room

One room with who is in it and what they are publishing. Poll this for a live viewer count rather than counting webhook events.

Response, 200 OK:

{
  "room": {
    "roomId": "show-42",
    "tenantId": "vk_3f9c1a7b2d4e6f80",
    "originNode": "node-1",
    "state": "live",
    "hostIdentity": "user-7",
    "createdAt": 1791048388384,
    "nodes": [
      "node-1"
    ],
    "participants": 0,
    "metadata": {
      "layout": "grid"
    }
  },
  "participants": [
    {
      "identity": "user-7",
      "role": "host",
      "handRaised": false,
      "muted": false
    }
  ],
  "producers": [
    {
      "producerId": "5d0c...",
      "identity": "user-7",
      "kind": "audio",
      "source": "mic",
      "paused": false
    }
  ]
}

Errors:

List rooms

Every room your project has live right now.

Response, 200 OK:

{
  "rooms": [
    {
      "roomId": "show-42",
      "tenantId": "vk_3f9c1a7b2d4e6f80",
      "originNode": "node-1",
      "state": "live",
      "hostIdentity": "user-7",
      "createdAt": 1791048388384,
      "nodes": [
        "node-1"
      ],
      "participants": 0,
      "metadata": {
        "layout": "grid"
      }
    }
  ]
}

List participants

Who is connected, at this moment.

Response, 200 OK:

{
  "participants": [
    {
      "identity": "user-7",
      "role": "host",
      "handRaised": false,
      "muted": false,
      "metadata": {
        "name": "Asha"
      }
    }
  ]
}

Errors:

End a room

Ends the room for everyone and clears its chat. Clients receive roomClosed.

Response, 200 OK:

{
  "closed": true
}

Errors:

REST: chat

Mint a chat token

Lets one user into a channel's chat with no media rights. A channel has the same name as the room it belongs to; a channel with no room is chat on its own. Someone already in the room does not need this: chat is on their room connection.

Request:

{
  "identity": "user-99",
  "role": "viewer"
}

Response, 200 OK:

{
  "token": "eyJhbGciOi...",
  "wsUrl": "wss://rtc.example.com/ws/chat",
  "role": "viewer",
  "identity": "user-99",
  "channel": "show-42",
  "expiresAt": 1791048988
}

Errors:

Send a message

Posts a message from your backend: a system notice, a gift, a moderation warning. from defaults to system; you may also speak as one of your own users. to makes it a direct message. ephemeral: true delivers without storing. A message needs text or metadata.

Request:

{
  "text": "The show starts in 5 minutes",
  "type": "system"
}

Response, 201 Created:

{
  "id": "1791048388390-0",
  "channel": "show-42",
  "from": "system",
  "type": "system",
  "text": "The show starts in 5 minutes",
  "ts": 1791048388390
}

Errors:

Read history

Messages oldest first. Pass the oldest id you hold as before to page backwards. Your backend sees direct messages too; clients only ever see their own.

Response, 200 OK:

{
  "messages": [
    {
      "id": "1791048388390-0",
      "channel": "show-42",
      "from": "system",
      "type": "system",
      "text": "The show starts in 5 minutes",
      "ts": 1791048388390
    }
  ]
}

Errors:

Delete a message

Removes it from history and tells every connected client.

Response, 200 OK:

{
  "deleted": true
}

Errors:

Mute or unmute someone

A muted identity cannot send. The mute survives them reconnecting, and lasts until you remove it or the room ends.

Response, 200 OK:

{
  "identity": "user-13",
  "muted": true
}

List mutes and members

Who is muted, and how many distinct identities are connected to the channel.

Response, 200 OK:

{
  "muted": [
    "user-13"
  ]
}

REST: broadcast

Create a stream

Creates a broadcast stream. playback is public (anyone with the URL can watch) or token (each viewer needs a URL you mint). The publish block is returned only here: whipUrl carries the publish token, so treat it like a password.

Request:

{
  "streamId": "show-42",
  "playback": "public"
}

Response, 201 Created:

{
  "streamId": "show-42",
  "tenantId": "vk_3f9c1a7b2d4e6f80",
  "streamKey": "9f2c41d07ab35e886c01d4f2",
  "state": "idle",
  "playback": "public",
  "createdAt": 1791048388384,
  "viewers": 0,
  "peakViewers": 0,
  "playbackUrls": {
    "llhls": "https://cdn.example.com/app/9f2c41d07ab35e886c01d4f2/llhls.m3u8",
    "webrtc": "wss://live.example.com/app/9f2c41d07ab35e886c01d4f2"
  },
  "publish": {
    "whipUrl": "https://live.example.com/app/9f2c41d07ab35e886c01d4f2?direction=whip&token=eyJ...",
    "token": "eyJhbGciOi...",
    "expiresAt": 1791052000
  }
}

Errors:

Mint a publish or playback URL

action is publish (a fresh whipUrl for the broadcaster) or play (playback URLs for one viewer of a token stream).

Request:

{
  "action": "play",
  "identity": "user-99"
}

Response, 200 OK:

{
  "streamId": "show-42",
  "action": "play",
  "token": "eyJhbGciOi...",
  "expiresAt": 1791052000,
  "llhls": "https://cdn.example.com/app/9f2c41d07ab35e886c01d4f2/llhls.m3u8?token=eyJ...",
  "webrtc": "wss://live.example.com/app/9f2c41d07ab35e886c01d4f2?token=eyJ..."
}

Errors:

Get, list, update, delete

state is idle or live. viewers counts playback sessions the media server serves itself; an audience behind a CDN is not in that number. Deleting a stream takes it off air and stops its publish URL working.

Response, 200 OK:

{
  "streamId": "show-42",
  "tenantId": "vk_3f9c1a7b2d4e6f80",
  "streamKey": "9f2c41d07ab35e886c01d4f2",
  "state": "live",
  "playback": "public",
  "createdAt": 1791048388384,
  "viewers": 37,
  "peakViewers": 52,
  "playbackUrls": {
    "llhls": "https://cdn.example.com/app/9f2c41d07ab35e886c01d4f2/llhls.m3u8",
    "webrtc": "wss://live.example.com/app/9f2c41d07ab35e886c01d4f2"
  },
  "startedAt": 1791048400000
}

Errors:

REST: usage

Usage so far

Today, this month and all time, with the balance. minutesRemaining is -1 on an unlimited plan; on a metered project that uses the account balance, it includes what the project can still use from it. allowance breaks the figure down; see Reading your usage.

Response, 200 OK:

{
  "tenantId": "vk_3f9c1a7b2d4e6f80",
  "plan": "metered",
  "status": "active",
  "minutesLimit": 6000,
  "usedMinutes": 90,
  "minutesRemaining": 5910,
  "today": {
    "participantSeconds": 5400,
    "publisherSeconds": 3600,
    "roomSeconds": 3600,
    "roomsCreated": 2,
    "peakParticipants": 14,
    "chatMessages": 212,
    "chatConnectionSeconds": 9000,
    "broadcastSeconds": 0,
    "broadcastViewerSeconds": 0,
    "streamsStarted": 0
  },
  "month": {
    "participantSeconds": 5400,
    "publisherSeconds": 3600,
    "roomSeconds": 3600,
    "roomsCreated": 2,
    "peakParticipants": 14,
    "chatMessages": 212,
    "chatConnectionSeconds": 9000,
    "broadcastSeconds": 0,
    "broadcastViewerSeconds": 0,
    "streamsStarted": 0
  },
  "lifetime": {
    "participantSeconds": 5400,
    "publisherSeconds": 3600,
    "roomSeconds": 3600,
    "roomsCreated": 2,
    "peakParticipants": 14,
    "chatMessages": 212,
    "chatConnectionSeconds": 9000,
    "broadcastSeconds": 0,
    "broadcastViewerSeconds": 0,
    "streamsStarted": 0
  }
}

Usage by day

One entry per day, oldest first, ending today. Days with no usage are present and zero. days is capped at 90.

Response, 200 OK:

{
  "tenantId": "vk_3f9c1a7b2d4e6f80",
  "days": 2,
  "series": [
    {
      "day": "2026-10-02",
      "participantSeconds": 5400,
      "publisherSeconds": 3600,
      "roomSeconds": 3600,
      "roomsCreated": 2,
      "peakParticipants": 14,
      "chatMessages": 212,
      "chatConnectionSeconds": 9000,
      "broadcastSeconds": 0,
      "broadcastViewerSeconds": 0,
      "streamsStarted": 0
    },
    {
      "day": "2026-10-03",
      "participantSeconds": 5400,
      "publisherSeconds": 3600,
      "roomSeconds": 3600,
      "roomsCreated": 2,
      "peakParticipants": 14,
      "chatMessages": 212,
      "chatConnectionSeconds": 9000,
      "broadcastSeconds": 0,
      "broadcastViewerSeconds": 0,
      "streamsStarted": 0
    }
  ]
}

Realtime: connecting

Clients connect to the wsUrl returned with their token:

Messages are JSON. A request carries an id, which the reply repeats:

{ "id": 1, "method": "join", "params": { "token": "eyJ..." } }

{ "id": 1, "ok": true, "result": { "roomId": "show-42", "role": "viewer" } }

{ "id": 1, "ok": false, "error": { "code": "forbidden", "message": "role viewer may not publish" } }

The server also sends events, which have no id:

{ "event": "participantJoined", "data": { "identity": "user-99", "role": "viewer" } }

join must be the first request, within 15 seconds of connecting.

Realtime: room methods

Media setup uses createTransport, connectTransport, produce, consume, resumeConsumer, pauseProducer, closeProducer and setPreferredLayers. The SDKs call these for you; if you are writing your own client, ask support for the protocol guide.

A publisher may have one producer per source, allowing camera, screen, microphone, music and screen audio together. videoLayers contains each spatial index and its width/height in produce, consume, room state and producer events. Joined videoPolicy defaults to 1080p/60 fps for every plan. Role, pending-hand and mute state survive reconnects; explicit operator restrictions still apply. See Video quality and Screen sharing.

Realtime: chat methods

Available on both connections.

Realtime: events

Realtime errors

A refused request is answered with ok: false and an error object holding code and message. The SDKs raise it as RpcError (rooms) or ChatRpcError (chat-only connections). The full list, with what to do about each, is on the Errors page.

Webhooks

Event types, payloads and signature verification are on the Webhooks page.