WebSocket API Server

Stream Kit can host an inbound WebSocket API server for remote control and integrations. This is separate from the WebSocket plugin, which opens outbound connections to external servers.

Configure the server under Settings → API Server.

Settings

Connect with the token in the query string:

ws://127.0.0.1:7892/ws?token=YOUR_TOKEN

Or send an auth frame as the first message:

{ "type": "auth", "token": "YOUR_TOKEN" }

Invalid or missing auth closes the socket (policy violation).

Protocol

All frames are JSON text messages.

Request

{ "id": "1", "type": "request", "method": "actions.getSnapshot", "params": {} }

Response

{ "id": "1", "type": "response", "ok": true, "result": {} }

{
  "id": "1",
  "type": "response",
  "ok": false,
  "error": { "code": "not_found", "message": "Unknown method: …" }
}

Events

Clients receive events only after calling server.subscribe:

{
  "id": "2",
  "type": "request",
  "method": "server.subscribe",
  "params": { "events": ["actions.*", "queues.*", "collections.*"] }
}

Event frame:

{ "type": "event", "event": "actions.executed", "payload": {} }

Patterns support a trailing .* glob (for example plugin:rankings.*).

Built-in methods

Commands require the Bot plugin. Variables and collections require Core.

Example: run an action

{
  "id": "3",
  "type": "request",
  "method": "actions.runById",
  "params": {
    "id": 42,
    "trigger": "api-server",
    "data": { "user": "viewer" }
  }
}

Plugin extension

Plugins register methods and emit events through app.api. Names are prefixed with plugin:<pluginKey>::

import type { Plugin } from '@stream-kit/plugin';

const plugin: Plugin = (app) => {
	app.api.registerMethod('getLeaderboard', async () => {
		return [{ name: 'Alice', points: 10 }];
	});

	return {
		name: 'Rankings',
		onEnable: () => {
			// later:
			void app.api.emit('pointsEarned', { user: 'Alice', points: 5 });
			// → event plugin:rankings:pointsEarned
		},
		onDisable: () => {
			app.api.unregisterMethods();
		}
	};
};

export default plugin;

Remote clients call plugin:rankings:getLeaderboard and subscribe to plugin:rankings.*.

The host also clears plugin methods when a plugin is disabled or uninstalled.

Security notes

• A token is always required.
• Prefer localhost bind unless a companion app on another machine needs access.
• LAN bind (0.0.0.0) exposes the API on your network — treat the token like a password.
• TLS (wss) is not included in v1.

Example client: Stream Deck

The Stream Deck integration uses this API as its only transport:

• Built-in actions.getSnapshot / actions.runById to pick and run actions from Stream Deck keys
• Plugin methods plugin:stream-deck:reportEvent, registerButton, getStatus, …
• Subscribe to plugin:stream-deck.* for feedback (setTitle, setImage, setState, …)

Related

• Plugin Authoring API
• WebSocket plugin (outbound client)
• Stream Deck (Elgato hardware via this API)
• Overlays (separate local server on port 7891)