Widgets — API endpoints

Base domains

• https://widgets.streamercatalyst.com
• https://preview.widgets.streamercatalyst.com

Browser-source URLs (/widget/*, /v1/scene/*, /event-page) and the /ws/* socket are loaded straight from widgets.streamercatalyst.com by OBS or other capture software. preview.widgets.streamercatalyst.com serves the same routes for the dashboard’s editor previews.

The StreamerCatalyst dashboard calls the session endpoints same-origin through https://streamercatalyst.com/m/widgets/* (for example /m/widgets/api/channels/:id/token reaches /api/channels/:id/token here). That proxy forwards the session cookie over a Cloudflare service binding and never forwards /internal/*.

Endpoints

Path	Method	Auth	Description
/widget/:channelId	GET	Widget token	A custom widget for an OBS browser source (?token=&widget_id=). ?thumb=1 renders a still with no live-event socket.
/widget/native/:channelId	GET	Widget token	A built-in widget for an OBS browser source (?token=&type=, plus instance_id and an optional pack skin).
/v1/scene/:sceneId	GET	Widget token	A whole scene as one browser source: every widget placed on it, composited (?token=).
/event-page	GET	Widget token	The Event Page as an OBS browser source (?token=). Same data as the public page at streamercatalyst.com/e/<login>, and it renders whether or not that page is published.
/ws/:channelId	GET (WebSocket)	Widget token	Live event socket for overlays (?token=): Twitch and StreamerCatalyst events pushed to the widget, replayed after a reconnect.
/api/widgets/templates/native	GET	Public	Catalogue of built-in widget templates and their settings schemas; …/templates/native/:templateId returns one.
/api/widgets/kv/:widgetId/:key	GET/PUT/DELETE	Widget token	Per-widget key-value storage for custom widgets; GET /api/widgets/kv/:widgetId?prefix= lists keys.
/api/widgets/counters/:channelId	GET	Widget token	One counter value for SE_API.counters.get: a Chatters channel counter or a module metric.
/api/widgets/sc/twitch/*	GET	Widget token	Twitch reads for custom widgets: user/:login, stream/:login, followers, clips, polls, predictions, charity. Rate-limited per channel.
/api/widgets/sc/rewards/*	GET	Widget token	Events data for widgets: recent, goal, leaderboard, metric.
/api/widgets/sc/numbers/*	GET	Widget token	Numbers data for widgets: metric, and plus (Plus Points; a figure that could not be read comes back as unavailable, never 0).
/api/widgets/sc/chatters/metric	GET	Widget token	Chatters metrics for widgets, such as named counters.
/api/widgets/sc/tip/goal	GET	Widget token	Active Tipping donation-goal progress.
/api/widgets/sc/ai/*	GET/POST	Widget token	AI for widgets: complete (generic, rate-limited), persona-comment (the AI persona bubble), remaining (quota left).
/api/widgets/timer/state	GET	Widget token	Subathon timer state for the overlay (?token=&channel_id=).
/api/widgets/timer/add-time	POST	Widget token	The overlay reports a contribution to the subathon timer; each event counts once.
/api/widgets/goals/state	GET	Widget token	Subathon goals ladder tally for the overlay.
/api/widgets/goals/add	POST	Widget token	The overlay reports a contribution to the subathon goals ladder; each event counts once.
/api/widgets/credits/state	GET	Widget token	Ending-credits roll data (?sections=&window=). A section that could not be read is reported as unavailable, never as empty.
/api/widgets/sync-values/:channelId	GET	Widget token	Live values for widget fields bound to a goal (tip goal, a Numbers goal, or the charity campaign).
/api/widgets/runtime-errors	POST	Widget token	A widget reports a runtime error; GET/DELETE /api/widgets/runtime-errors/:widgetId reads and clears them.
/api/channels/:id/token	GET	Session cookie	The channel’s widget token, for building browser-source URLs.
/api/channels/:id/token/rotate	POST	Session cookie	Issue a new widget token. Every URL carrying the old one stops working.
/api/channels/:id/widget-instances	GET/POST	Session cookie	List or save the channel’s built-in widget instances and their settings.
/api/widgets/instances/:instanceId	DELETE	Session cookie	Delete a widget instance; PATCH …/placement moves it on a scene.
/api/widgets/instances/:instanceId/sounds/:eventKey	PUT/DELETE	Session cookie	Assign or clear the sound a widget plays for an event (one sound per event per scene).
/api/widgets/scenes	GET/POST	Session cookie	List or create scenes.
/api/widgets/scenes/:sceneId	PATCH/DELETE	Session cookie	Update or delete a scene; POST …/duplicate copies it and GET …/sounds lists its sound assignments.
/api/widgets/custom	GET	Session cookie	List the channel’s custom widgets.
/api/widgets/custom/:widgetId	GET/POST/DELETE	Session cookie	Read, save, or delete a custom widget; …/publish, …/versions and …/restore/:versionId manage its versions.
/api/widgets/custom/generate	POST	Session cookie	Generate or refine a custom widget with AI; GET /api/widgets/custom/ai-status reports availability.
/api/widgets/assets	GET	Session cookie	Uploaded images, video and audio; POST /api/widgets/assets/upload adds one, DELETE /api/widgets/assets/:assetId removes one.
/api/widgets/sounds	GET	Session cookie	The sound library plus your own uploaded sounds, for the sound pickers.
/api/widgets/packs	GET	Session cookie	Widget packs (overlay skins) available to the channel.
/api/widgets/tier	GET	Session cookie	The channel’s plan; GET /api/widgets/limits reports widget counts against its limits.
/api/channels/:id/timer/*	GET/POST	Session cookie	Subathon timer control from the dashboard: state, pause, resume, adjust, reset.
/api/channels/:id/goals/*	GET/POST	Session cookie	Subathon goals control: state, reset, adjust (a signed correction), backfill (count earlier activity).
/api/channels/:id/credits/*	GET/POST	Session cookie	Ending credits control: state, lists, control, clear.
/internal/eventsub	POST	Service binding (internal)	EventSub fan-out receiver (internal, from eventsub-router).
/internal/sc-event	POST	Service binding (internal)	StreamerCatalyst events from other modules (tips, wheel spins, goal and metric updates) pushed to overlays (internal).
/internal/billing/downgrade	POST	Service binding (internal)	Tier-downgrade handler (internal).

Auth model

• Session cookie endpoints require an active StreamerCatalyst session (set at login via the platform Worker). A channel-scoped route (/api/channels/:id/…) answers only for the session’s own channel, and a read-only admin masquerade may read but not change anything.
• Widget token endpoints are what OBS browser sources and overlays call. The channel’s widget token, passed as ?token=, is the credential: the channel comes from the token, and a token that does not match the channel in the URL is refused. Treat a URL that carries it like a password; rotating the token from the dashboard invalidates every URL with the old one.
• Public endpoints require no authentication.
• Service binding endpoints are for other StreamerCatalyst Workers, called over Cloudflare service bindings with a shared internal token. They are not a public API.