TipPage Developer API

Read your tips, drive the TTS and media queues, run the chat bot, and get events the moment they happen.

API base	`https://api.tippage.com/v1`
Auth	`Authorization: Bearer tp_live_...` - see Authentication
Realtime stream	`wss://ws.tippage.com` - see Realtime
Spec	openapi.yaml - import into Postman, Insomnia or Bruno, or generate a client

Guides: OAuth 2.0 for apps other streamers connect, Webhooks for signed events, Claim and finish to play tips from your own code.

Rate limits: 240 requests/min per IP and 120/min per key (or OAuth authorization), in RateLimit-* headers; over the limit is 429. POST /chat/messages also has its own budget: 20 messages per 30 seconds per streamer, across all keys.

Errors are JSON: { "error": "<human message>", "code": "<machine_code>" }.

Version 1.0

Base URLhttps://api.tippage.com/v1

Identity

Key introspection and API discovery.

Realtime

The webhook event stream, live over a WebSocket at wss://ws.tippage.com - same events, same payloads, same event ids as the webhooks, delivered while you’re connected. No SDK needed: open a plain WebSocket, send one JSON line - {"data": {"apiKey": "tp_live_..."}} for connections you control, or {"data": {"token": "..."}} with a short-lived token from POST /realtime/token to let clients that shouldn’t hold your key (browsers, third parties) connect. The server streams the events your key’s scopes allow. Full guide, wire format, channel table, and lifecycle: https://docs.tippage.com/api/realtime

POST
Mint a realtime handoff token/realtime/token

TTS queue

The pending TTS queue and its played history. Reads need tts:read; controls need tts:control. The start/finish pair is the same protocol the stream overlay speaks - an external consumer can claim a TTS, play it its own way, and finish it into history. Full pattern: claim, do your thing, finish.

Media queue

The media (video request) queue, its played history, live playback status, and direct video queueing. Reads need media:read; controls and queueing need media:control.

Tipping

Tips themselves: create manual tips (tips:create), the accept-new-tips switch (status readable by any valid key, opening/closing via tipping:control), and the supporter leaderboard (any valid key).

Alerts

Platform alerts - subs, gift subs, resubs, cheers, raids, Kicks and channel point redemptions - as the overlay’s alert box plays them: what is on screen now, what played, skip and replay. Reads need tts:read, controls tts:control (the same pair the dashboard’s TTS page uses for the same panel). The live events themselves ride the twitch and kick realtime groups.

AI voices

AI voice TTS (TipPage+): the curated voice catalog with per-voice enabled flags, this month’s character usage, and toggles for the whole feature or individual voices. Needs ai_voices:manage. Every endpoint answers 404 unless AI voices are available to your account.

Viewers

Viewer management for the sub-rewards system. A viewer is someone who has signed in to the tip page - with Twitch or Kick - and every viewer object names that account as platform + platform_user_id, with the person’s other linked account(s) in linked_accounts. List them with their first sign-in dates and credit balances (viewers:read), read one viewer’s grant ledger and sub-reward usage, and grant or revoke credits (viewers:manage). Balances, grants and reward history are read across a person’s linked accounts; a grant or revoke lands on the exact account you name. Everywhere a {user} appears in a path you can pass <platform>:<id> (kick:123), a bare numeric id, or the viewer’s name (login or display name, case-insensitive, on either platform). Someone who has never signed in can’t be looked up or granted credits - those requests answer 404 viewer_not_signed_in.

Channel points

Create channel point rewards and resolve their redemptions on Twitch. Needs channel_points:manage. Twitch only lets the app that created a reward resolve its redemptions, so resolving works for rewards TipPage created - through POST /channel-points/rewards, or the dashboard’s Channel points page. Pair with the twitch.channel_point_redemption webhook, whose is_managed flag says whether a redemption is resolvable.

Webhook endpoints

Manage where events get delivered. Needs webhooks:manage. Endpoints can also be managed in the dashboard.

Chat timers

Scheduled chat-bot messages - the bot posts them on a fixed or randomized interval, optionally only while the streamer is live or after enough chat activity. Needs timers:manage. The same timers as the dashboard’s Chat bot page; max 20 per streamer. Editing a timer’s interval restarts its schedule from now.

Counters

Named per-streamer numbers the chat bot bumps with {count} / {count:name} command tokens and overlay Data labels can display live. Addressed by name - a lowercase slug (a-z 0-9 _ -, max 64 chars) is the key on every surface. Needs counters:manage. Every change made here behaves exactly like a chat bump: overlays update live and the counter.updated webhook fires. Max 100 per streamer.

Chat bot

The streamer’s chat bot: its status and send identity (any valid key), speaking in chat as the bot (chat:write), and the custom !commands it answers (commands:manage, addressed by command name - the trigger without the !). Pair with the chat.command webhook event to react when a custom command runs.

Overlays

The account’s overlays: list them, inspect one (name, resolution, widget types - never overlay keys), delete one, reload a connected one, fire the Event celebration widget on demand (all of them or one specific instance), and read, update, or add to each overlay’s tip goal. All of it needs overlays:manage.