API Reference

StreamForge exposes a REST API used by the dashboard itself and by external automations. Most endpoints accept either session authentication or API key authentication.

Authentication

You can authenticate in two ways:

Session auth (dashboard/browser): cookie-based authentication from a signed-in user session.
API key auth (automation/server): generate keys in Settings → API and send them in the Authorization header.

API key example:

Authorization: Bearer sf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Notes:

API keys are tenant-scoped
Maximum 5 active API keys per tenant
API key management requires Pro tier
For session-authenticated mutation requests, valid browser origin/CSRF requirements apply

Base URL

https://streamforge.bifrostlive.com

Endpoints below are shown as absolute API paths (for example: /api/events).

Request & Response Conventions

JSON request/response bodies with Content-Type: application/json
ISO-8601 timestamps (UTC)
UUID identifiers for most entities
Validation errors return status 400 with field details

HTTP Status Codes

Status Code	Meaning
`200`	OK — Request succeeded
`201`	Created — Resource created successfully
`204`	No Content — Request succeeded, no body returned
`400`	Bad Request — Invalid request body or parameters
`401`	Unauthorized — Missing or invalid API key
`403`	Forbidden — Insufficient permissions or tier limit reached
`404`	Not Found — Resource does not exist
`409`	Conflict — Resource state conflict (e.g., event already active)
`422`	Unprocessable Entity — Validation failed
`429`	Too Many Requests — Rate limit exceeded
`500`	Internal Server Error — Unexpected server error

Rate Limiting

Some endpoints use route-level rate limiting. On limit hit, expect 429 and respect Retry-After when present.

Endpoints

Endpoints are grouped by feature area. Paths below are current API routes.

API Keys

Method	Path	Description
`GET`	`/api/keys`	List active API keys
`POST`	`/api/keys`	Generate a new API key
`DELETE`	`/api/keys/:id`	Revoke an API key

Viewers

Method	Path	Description
`GET`	`/api/viewers/search?q=...&limit=20`	Search viewers by username (min 2 chars)
`GET`	`/api/viewers/:viewerId/profile`	Get viewer details with stats
`POST`	`/api/viewers/resolve`	Resolve viewer IDs to display names. Body: { "viewer_ids": ["uuid", ...] }

Example — Search Viewers

GET /api/viewers/search?q=ninja&limit=5
Authorization: Bearer sf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Response:

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "twitch_username": "ninja",
      "twitch_display_name": "Ninja",
      "total_points": 15200,
      "message_count": 342,
      "watch_minutes": 18400
    }
  ]
}

Viewer Interactions

Method	Path	Description
`POST`	`/api/viewers/interactions`	Add a manual interaction for a viewer
`DELETE`	`/api/viewers/interactions/:id`	Remove a manual interaction (source=manual only)

Example — Add Interaction

POST /api/viewers/interactions
Authorization: Bearer sf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "username": "viewer123",
  "type": "donation",
  "quantity": 1,
  "date": "2026-04-09",
  "mode": "add"
}

Point Rules

Method	Path	Description
`GET`	`/api/point-rules`	List all point rules for your workspace
`PUT`	`/api/point-rules`	Update point rules (bulk). Body: { "rules": [...] }

VIP Rules

Method	Path	Description
`GET`	`/api/vip-rules`	List all VIP rules
`POST`	`/api/vip-rules`	Create a new VIP rule
`GET`	`/api/vip-rules/:id`	Get VIP rule details
`PATCH`	`/api/vip-rules/:id`	Update a VIP rule
`DELETE`	`/api/vip-rules/:id`	Delete a VIP rule
`POST`	`/api/vip-rules/:id/evaluate`	Manually trigger rule evaluation

Example — Create VIP Rule

POST /api/vip-rules
Authorization: Bearer sf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "name": "Top Monthly Supporters",
  "metric": "total_points",
  "threshold": 5000,
  "period": "monthly",
  "max_winners": 3,
  "auto_grant": true
}

VIP Awards

Method	Path	Description
`GET`	`/api/vip-awards`	List VIP award history. Query: ?page=1&limit=50&status=active&viewer_id=uuid&rule_id=uuid
`POST`	`/api/vip-awards/:id/revoke`	Revoke a VIP award

Permanent VIPs

Method	Path	Description
`GET`	`/api/vip/permanent`	List all permanent VIPs
`POST`	`/api/vip/permanent`	Add permanent VIP. Body: { "twitch_username": "name", "reason": "..." }
`POST`	`/api/vip/permanent/bulk`	Bulk add permanent VIPs. Body: { "usernames": [...], "reason": "..." }
`DELETE`	`/api/vip/permanent/:viewerId`	Remove permanent VIP status

Ignore Lists

Method	Path	Description
`GET`	`/api/ignore-lists`	List all ignore list entries
`POST`	`/api/ignore-lists`	Add a user to the ignore list
`DELETE`	`/api/ignore-lists/:id`	Remove an entry from the ignore list

Events

Method	Path	Description
`GET`	`/api/events`	List all events. Query: ?status=active\|draft\|paused\|ended
`POST`	`/api/events`	Create a new event
`GET`	`/api/events/:id`	Get event details
`PATCH`	`/api/events/:id`	Update event configuration
`POST`	`/api/events/:id/start`	Start an event
`POST`	`/api/events/:id/pause`	Pause a running event
`POST`	`/api/events/:id/resume`	Resume a paused event
`POST`	`/api/events/:id/end`	End an event
`POST`	`/api/events/:id/recalculate`	Recalculate event data and contributions

Event Power Hours

Method	Path	Description
`GET`	`/api/events/:id/power-hours`	List power hours for an event
`POST`	`/api/events/:id/power-hours`	Create a power hour for an event
`POST`	`/api/events/:id/power-hours/:phId/activate`	Activate a scheduled power hour
`POST`	`/api/events/:id/power-hours/:phId/deactivate`	Deactivate a power hour

Event Goals

Method	Path	Description
`GET`	`/api/events/:id/goals`	List goals for an event
`POST`	`/api/events/:id/goals`	Create a goal for an event
`PATCH`	`/api/events/:id/goals/:goalId`	Update an event goal
`DELETE`	`/api/events/:id/goals/:goalId`	Delete an event goal

Event Contributions

Method	Path	Description
`GET`	`/api/events/:id/contributions`	List contributions for an event (paginated). Query: ?page=1&limit=50
`POST`	`/api/events/:id/contributions`	Add a manual contribution to an event

Challenges

Method	Path	Description
`GET`	`/api/challenges`	List community challenges. Query: ?status=active\|draft\|completed\|expired
`POST`	`/api/challenges`	Create a new challenge
`PATCH`	`/api/challenges/:id`	Update a challenge
`DELETE`	`/api/challenges/:id`	Delete a challenge

Achievements

Method	Path	Description
`GET`	`/api/achievements`	List achievements for your workspace
`POST`	`/api/achievements`	Create an achievement
`PATCH`	`/api/achievements`	Update an achievement
`DELETE`	`/api/achievements`	Delete an achievement

Data Import

Method	Path	Description
`POST`	`/api/import/csv`	Import viewer data from parsed CSV rows. Body: { "rows": [...] }
`GET`	`/api/import/template`	Download CSV import template

Community Wheel

Method	Path	Description
`GET`	`/api/community-wheel/sessions`	List wheel sessions
`POST`	`/api/community-wheel/sessions`	Create a wheel session
`GET`	`/api/community-wheel/history`	List wheel history
`POST`	`/api/community-wheel/sessions/:id/spin`	Trigger a spin
`POST`	`/api/community-wheel/sessions/:id/grant-prize`	Grant selected prize outcome

Recaps

Method	Path	Description
`GET`	`/api/recaps`	List recap records for your workspace
`GET`	`/api/recaps/:id`	Get recap details with stats and narrative

Settings

Method	Path	Description
`GET`	`/api/settings`	Get all tenant settings
`PATCH`	`/api/settings`	Update settings. Body: { "settings": [{ "key": "...", "value": "..." }] }

Team

Method	Path	Description
`GET`	`/api/team`	List team members
`POST`	`/api/team/invite`	Send a team invitation. Body: { "email": "...", "role": "admin\|moderator\|viewer" }
`DELETE`	`/api/team/:userId`	Remove a team member
`PATCH`	`/api/team/:userId/role`	Change a team member's role (owner only). Body: { "role": "admin\|moderator\|viewer" }

Tips

Use pagination parameters (page, limit) on list endpoints to avoid large payloads.
Store your API key securely — never expose it in client-side code or public repositories.
Use the search endpoints for viewer lookups instead of listing all viewers.
When automating event management, check the event status field before issuing start/pause/resume/end commands.
If you need help or encounter issues, contact support from your dashboard.