WebSocket API ServerCopy Anchor Link

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.

SettingsCopy Anchor Link

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).

ProtocolCopy Anchor Link

All frames are JSON text messages.

RequestCopy Anchor Link

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

ResponseCopy Anchor Link

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

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

EventsCopy Anchor Link

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 methodsCopy Anchor Link

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

Example: run an actionCopy Anchor Link

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

WebhooksCopy Anchor Link

Besides the WebSocket, the server accepts plain HTTP requests on /webhook/<path>. Create webhooks under Core → Webhooks, then use them in the Webhook trigger. See HTTP and webhooks.

Each webhook has its own secret, not the API server access token. Send it in one of these ways:

• Authorization: Bearer YOUR_SECRET
• X-Webhook-Secret: YOUR_SECRET
• ?secret=YOUR_SECRET (for services that can't set headers)

curl -X POST http://127.0.0.1:7892/webhook/scene/next \
  -H "Authorization: Bearer YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"scene":"Gameplay"}'

Any method works. Bodies are limited to 1 MB.

Plugin extensionCopy Anchor Link

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 notesCopy Anchor Link

• 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.
• Webhooks are only reachable on your machine or LAN. To receive webhooks from internet services, put a tunnel or reverse proxy in front of the server.

Example client: Stream DeckCopy Anchor Link

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, …)

RelatedCopy Anchor Link

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