API docs

Bonus hunts

Read and run your bonus hunts. Writes behave exactly like the dashboard: totals recompute from the entries, overlays and the live hunt page update instantly, Discord announcements and chat points fire as usual. Money amounts are plain numbers in the hunt's currency.

Guess the Balance

Viewers guess a hunt's final balance in chat. Guessing is one switch on your account that applies to your live hunt. Twitch and YouTube viewers are never named in API responses or webhooks — they come back as a stable `anonId` instead.

Slot requests

The games your viewers call in chat. Statuses: `pending` (queued), `added` (on the hunt), `played`, `skipped`, `archived`.

Payouts

Everything on Store → Payouts: raffle winners (`source: raffle`), giveaway winners (`source: giveaway`) and manual payouts (`source: manual` — added by hand, through the API, or by a feature such as a wheel, a wager race or Clip Rewards; that feature is in `origin`). A payout is a record of what you owe — marking it paid never moves money or points.

Store

Your points shop: the catalogue, buying on a viewer's behalf, orders and refunds. Prices and balances are in points. Orders made in chat (!buy), on your store page, in Discord or through the API all fire `store.purchase`.

Raffles

Numbered-ticket raffles. Every ticket gets a sequential number; the draw picks one ticket at random across the whole pool. Raffles can be drawn before their draw date (plans with early draws).

Points

Viewer point balances and movements. A balance is the viewer's unified total (their linked Discord and Kick balances included). Award / remove / set accept an idempotency key — send one per logical operation and a retry replays the first result (header Idempotency-Replay: true) instead of applying twice. Keys last 7 days; the same key with a different body is a 422, and one still in flight is a 409.

Viewers

A viewer is one person across Discord, Kick, Twitch and YouTube. Look them up by any linked account, or link accounts from your own site.

Giveaways

Chat giveaways (viewers type a command on Kick, Twitch, YouTube or Hype to enter) and the giveaways your bot runs in Discord. Starting, drawing and rerolling behave exactly like the dashboard: the overlay plays the draw, chat gets the winner callout and points prizes are credited straight away.

Polls

Two kinds: chat polls (the Poll overlay widget — viewers vote by typing an option number) and community polls (players with numbers, a free first vote per viewer and paid extra votes in points). Your key always sees the real counts, even while results are hidden on stream.

Stream

Your streams and what happened on them. A stream is one sitting: if you simulcast to Kick and Twitch, it is one stream with one leg per platform — the same numbers as your stream history on the dashboard. Webhooks: stream.online when you go live, stream.offline when a stream ends.

Tips and gifts

Money your viewers sent, across Kick, Twitch and YouTube. Amounts are in each platform's own unit: KICKS on Kick, BITS on Twitch and the viewer's currency for Super Chats. Anonymous supporters keep their amount but never their name. Webhooks: support.tip and support.gifted_subs as they arrive.

Clips

Your clip library and win moments. A moment is a mark on the stream ("that was a moment") — a big win, a tagged press, a sponsor deliverable. A clip is the video saved for a moment. Webhook: clip.created when a clip is saved.

Campaigns

Your sponsor campaigns and how far along each deliverable is. done is a live count — presses for count and mention deliverables, bonuses opened on the partner's games for auto_games — the same number your Stream Pad tiles and sponsor reports show.

Overlays and Stream Pad

Switch overlay scenes and press Stream Pad buttons from your own tools — the same thing a Stream Deck button does.

Wager leaderboards

Your wager races. Standings come from the casino on each board's refresh schedule; hidden players are always removed. Webhook: wager_leaderboard.updated after each refresh, with the top 10.

Casino extension

What the StreamNeeds casino extension sends while you play. Pairing the extension creates its own key with the casino:write permission, so you only need these to build your own reader. Every call works on your current live hunt.

Health

Errors

{
  "error": "amount: Expected number, received string",
  "code": "invalid_body"
}

{
  "error": "Invalid or missing API key"
}

{
  "error": "Feature not available on the resource owner's plan",
  "code": "feature_locked",
  "feature": "raffles_payouts"
}

{
  "error": "API key needs one of these scopes: payouts:read"
}

{
  "error": "Payout not found",
  "code": "not_found"
}

{
  "ok": false,
  "error": "no_open_hunt",
  "message": "No live hunt — start one first."
}

{
  "error": "Rate limit exceeded",
  "retryAfter": 2
}

{
  "error": "Service temporarily overloaded, retry shortly",
  "retryAfter": 2
}