​
REST API

The SBCanvas REST API lets external applications push events to overlays. Use it to connect stream decks, chatbots, dashboards, or any HTTP-capable tool to your overlay widgets.

​
Base URL

https://api.streambot.co/v1/features/sbcanvas

​
Authentication

All requests require a Bearer token: 
curl -H "Authorization: Bearer sb_live_xxxxxxxxxxxx" \
  https://api.streambot.co/v1/features/sbcanvas/events/ch_abc123
Generate tokens in the StreamBot dashboard under Settings > API Keys.

​
Token Types

TypePrefixDescription
Livesb_live_Delivers events to the live overlay
Testsb_test_Events are dropped (for development)

​
Send a Custom Event

POST /events/{channel_id}

{
  "event": "custom:confetti",
  "data": { "count": 200, "color": "#8B5CF6" }
}
Response: 
{ "success": true, "delivered_to": 1 }
The event name must start with custom:. Max length: 64 characters. Allowed characters: a-z, 0-9, :, _, -.

​
Rate Limits

60 requests per minute per token. Exceeding the limit returns 429. Rate limit headers are included in responses: 
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1716900000

​
Error Format

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests.",
    "retry_after": 30
  }
}
StatusMeaning
401Missing or invalid token
404Channel not found
422Invalid request body
429Rate limit exceeded

​
Quick Example: Python

import requests

requests.post(
    "https://api.streambot.co/v1/features/sbcanvas/events/ch_abc123",
    headers={"Authorization": "Bearer sb_live_xxxx"},
    json={"event": "custom:confetti", "data": {"count": 200}}
)

​
Quick Example: Node.js

await fetch('https://api.streambot.co/v1/features/sbcanvas/events/ch_abc123', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sb_live_xxxx',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ event: 'custom:confetti', data: { count: 200 } })
});

​
Widget Side

Events arrive prefixed with widget:event:: 
SBCanvas.on('widget:event:custom:confetti', (data) => {
  SBCanvas.confetti({ count: data.count });
});
See Widget Events for full details.