Reference

API reference

Every endpoint on api.velora.tv that is documented for outside use, grouped by what you are actually doing — acting for a streamer, reading the public catalogue, or managing your own app. Most rows name the scope they need in the description; if a row says public, it answers without a token.

This page is maintained by hand and covers the whole surface, public reads included. What your app can call is generated from the API source at build time and lists only the endpoints that accept a third-party OAuth token. Where the two disagree, trust the generated page — and check the scope before assuming a 403 is a bug.

Before you call anything

Base URL

https://api.velora.tv

Authorization header

Authorization: Bearer YOUR_TOKEN

Most endpoints require a valid access token on that header. The ones marked public do not, and will answer an unauthenticated request.

Prefer to poke at it live? The interactive API explorer runs real calls in the browser with full request and response schemas.

Acting on behalf of a streamer

These take a user’s OAuth access token and act as that person. The scope you hold is exactly the permission you have — this is the surface you build an OBS dock, a chat bot or an overlay against.

OAuth & Authentication

Getting a token in the first place. Start here before any endpoint below will answer you.

GET/api/developer/oauth/authorize

Preview authorization (get app info for consent page)

POST/api/developer/oauth/authorize

Complete authorization (exchange consent for code)

POST/api/developer/oauth/token

Exchange code for access token or refresh token

GET/api/developer/oauth/scopes

List all available OAuth scopes

Streaming Integration (OAuth)

Endpoints for streaming software like OBS and Meld Studio. Requires OAuth access token.

GET/api/integrations/oauth/stream/setup

Get stream key and ingest URLs (requires stream:key)

GET/api/integrations/oauth/stream/info

Get current stream info, including stream tags, channel tags and content warnings (requires stream:read)

PUT/api/integrations/oauth/stream/infoNew

Update stream title, category, stream tags and channel tags (requires stream:write)

GET/api/integrations/oauth/stream/categories

List available stream categories

GET/api/integrations/oauth/stream/tagsNew

List the tag vocabulary with tiers, content-warning flags and the tag limits (requires stream:read)

POST/api/integrations/oauth/stream/key/regenerate

Regenerate stream key (requires stream:key)

Chat

Endpoints for reading and interacting with chat. Perfect for OBS docks, chat bots, and overlays.

GET/api/chat/channels/:channelId/history

Get recent chat messages (public, no auth required - max 100 messages)

GET/api/integrations/oauth/chat/settings

Your channel's chat modes: slowMode, slowModeSeconds, followersOnly, subscribersOnly, emoteOnly (requires stream:read)

PATCH/api/integrations/oauth/chat/settings

Turn chat modes on or off. Applies to live chat immediately, like the web chat toggles. Send only the fields to change; e.g. a raid shield is { followersOnly: true, slowMode: true, slowModeSeconds: 30 } (requires stream:write)

Request body — JSON

slowModebooleanoptional

false also resets the delay to 0; true with no delay set uses 10 seconds

slowModeSecondsintegeroptional

Seconds between a viewer's messages

followersOnlybooleanoptional

Only followers can chat

subscribersOnlybooleanoptional

Only subscribers can chat

emoteOnlybooleanoptional

Only emotes allowed

GET/api/chat/channels/:channelId/viewersNew

Get current viewer list with usernames, avatars, roles, and anonymous count (public, accepts channelId or username)

GET/api/chat/channels/:channelId/stats

Get live chat statistics for a channel (public)

GET/api/chat/channels/:channelId/policy

Get chat moderation policy and rules (public)

POST/api/integrations/oauth/chat/channels/:channelId/messages

Send a chat message with optional effects (requires chat:write)

Request body — JSON

messagestringrequired

The message content (max 500 characters)

sendAsBotbooleanoptional

Post as your connected bot instead of the authenticated user. Needs chat:write (this route's scope) plus either a bot connected via /integrations/oauth/bot/select or a bot-type app. Omit/false to post as the user.

effectstringoptional

Message effect: glow, galaxy, rainbow, gigantify

effectColorstringoptional

Hex color for the effect (e.g., #ff6b6b)

replyToobjectoptional

Reply to a specific message: { messageId, username, message }

POST/api/integrations/oauth/chat/channels/:channelId/moderate

Moderate a user (timeout, ban, delete message - requires chat:moderate)

GET/api/chat/slash-commands

List available slash commands (public)

Channel Points (write, OAuth)

Create and manage your channel's point rewards programmatically — perfect for bots that spin up dynamic redemptions. All write endpoints act on your own channel (the channel that owns the token) and never move real money: rewards cost channel points, not currency. Pass an optional cardDesign object to style the reward exactly like the in-app card designer.

GET/api/integrations/oauth/channel-points/rewards

List your channel point rewards (requires channel:points:read)

POST/api/integrations/oauth/channel-points/rewards

Create a reward on your channel (requires channel:points:write)

Request body — JSON

namestringrequired

Reward name (max 120 chars)

costintegerrequired

Cost in channel points (>= 1). This is the free watch-time loyalty currency — not money.

descriptionstringoptional

Reward description (max 500 chars)

cooldownSecondsintegeroptional

Global cooldown between redemptions, in seconds

maxPerStreamintegeroptional

Max redemptions allowed per stream

maxPerUserPerStreamintegeroptional

Max redemptions per user per stream

requiresModeratorApprovalbooleanoptional

Hold each redemption for mod approval before granting

cardDesignobjectoptional

Full visual styling, identical to the in-app card designer. Shape: { version: number(>=1), background: { type: "solid"|"gradient", color?, colors?[], angle? }, texture: { enabled: boolean, pattern?, opacity?, blendMode? }, icon: { type: "none"|"emote"|"icon"|"emoji"|"symbol"|"custom", emoji?, emoteUrl?, iconName?, iconColor?, iconAnimated?, customIconUrl?, ... }, textLine1 & textLine2: { content, font, size: "xs"|"sm"|"md"|"lg", color: { type: "solid"|"gradient", value?, colors?[] }, animation: "none"|"pulse"|"bounce"|"shake"|"glow" }, border: { color, width: 0|1|2|3 }, textAlign?: "left"|"center"|"right" }. Include it to make beautiful cards; omit it for a default look.

PATCH/api/integrations/oauth/channel-points/rewards/:rewardId

Update a reward on your channel (requires channel:points:write). Accepts any create field plus enabled:boolean, and cardDesign to restyle the card.

DELETE/api/integrations/oauth/channel-points/rewards/:rewardId

Delete a reward on your channel (requires channel:points:write). Built-in rewards cannot be deleted.

Polls, Predictions, Giveaways, Goals & Timers (OAuth)

Run everything a streamer runs from chat or the dashboard, from your bot or tool. Reads need channel:read; control needs channel:interactive:write (reviewed before it is granted). Every endpoint acts on the token owner's own channel only, even if they moderate other channels, and goes through the same code as the dashboard, so overlays, chat cards and events behave identically. Polls, predictions and giveaways need the channel to be live. Rate limit: 60 requests/minute per access token.

GET/api/integrations/oauth/polls/activeNew

Current poll, or null (channel:read)

POST/api/integrations/oauth/pollsNew

Start a poll; replaces an open one (channel:interactive:write)

Request body — JSON

questionstringrequired

3-240 characters

optionsstring[]required

2-6 unique options, 1-120 characters each

durationSecondsintegeroptional

15-3600, default 120

allowMultiplebooleanoptional

Let viewers pick more than one option

POST/api/integrations/oauth/polls/:pollId/endNew

End a poll now; optional { reason } up to 30 characters (channel:interactive:write)

GET/api/integrations/oauth/predictions/activeNew

Current prediction (open, locked, or settled in the last 2 minutes), or null (channel:read)

POST/api/integrations/oauth/predictionsNew

Start a prediction. Fails if one is already open or locked (channel:interactive:write)

Request body — JSON

titlestringrequired

Up to 200 characters

outcomesstring[]required

2-10 outcomes, up to 60 characters each

durationSecondsintegeroptional

How long bets stay open, 15-1800

maxStakeintegeroptional

Most channel points one viewer can bet, 1-1,000,000 (default 250,000)

POST/api/integrations/oauth/predictions/:id/lockNew

Stop taking bets (channel:interactive:write)

POST/api/integrations/oauth/predictions/:id/resolveNew

Body { outcomeId }: pick the winner and pay out channel points (channel:interactive:write)

POST/api/integrations/oauth/predictions/:id/cancelNew

Cancel and refund every bet (channel:interactive:write)

GET/api/integrations/oauth/giveaways/activeNew

Current giveaway, or null (channel:read)

POST/api/integrations/oauth/giveawaysNew

Start a giveaway; replaces an open one (channel:interactive:write)

Request body — JSON

titlestringrequired

Up to 140 characters

descriptionstringoptional

Shown under the title

eligibilitystringoptional

all | followers | subscribers (default all)

entryModestringoptional

button | hashtag (default button)

hashtagstringoptional

Required for hashtag mode: # plus 2-30 characters

winnerCountintegeroptional

1-10, default 1

durationSecondsintegeroptional

30-7200, default 300

autoDrawbooleanoptional

Draw automatically when entries close (default true)

POST/api/integrations/oauth/giveaways/:giveawayId/drawNew

Draw the next winner; closes the giveaway once every winner is drawn (channel:interactive:write)

POST/api/integrations/oauth/giveaways/:giveawayId/endNew

Close a giveaway now (channel:interactive:write)

GET/api/integrations/oauth/goalsNew

Your channel's goals with live progress (channel:read)

POST/api/integrations/oauth/goals/:id/adjustNew

Body { amount, note? }: add to (or subtract from) progress (channel:interactive:write)

PATCH/api/integrations/oauth/goals/:idNew

Body { target }: change the target (channel:interactive:write)

POST/api/integrations/oauth/goals/:id/resetNew

Start a new period now, optional { startValue } (channel:interactive:write)

GET/api/integrations/oauth/timersNew

Your channel's timers and subathons with live state (channel:read)

POST/api/integrations/oauth/timers/:id/:actionNew

action = start | pause | resume | end | reset (channel:interactive:write)

POST/api/integrations/oauth/timers/:id/add-timeNew

Body { seconds, note? }: add time, or remove it with a negative number (channel:interactive:write)

Bot Management

Configure third-party bots with default and custom per-channel names. See full guide at /docs/bot-integration

POST/api/developer/apps/:clientId/bot/configure

Configure default bot name and settings (reserves username platform-wide)

GET/api/developer/apps/:clientId/bot/instances

List all bot instances (default + custom names per channel)

GET/api/developer/apps/:clientId/bot/check-name/:botName

Check if bot name is available

POST/api/integrations/oauth/bot/customize

Set custom bot name for user's channel (requires bot:write)

DELETE/api/integrations/oauth/bot/customize

Remove custom name, revert to default (45-day reservation)

GET/api/integrations/oauth/bot/current

Get current bot config for user's channel

Subscriptions

GET/api/developer/subscriptions/countNew

Authoritative count of your channel's active (non-expired) subscribers — offline-safe (requires subscriptions:read). 120 req/min.

GET/api/developer/subscriptionsNew

Paginated roster of your active subscribers (userId, username, tier, gift + gifter, expiry) + authoritative total. Query: page, perPage (1–100). Offline-safe (requires subscriptions:read). 120 req/min.

GET/api/subscriptions/my-subscriptions

Get current user subscriptions (requires subscriptions:read)

GET/api/subscriptions/creator/:creatorId/subscribers

Get creator subscribers (requires subscriptions:read)

GET/api/subscriptions/creator/:creatorId/gift-leaderboard

Get top gifters for creator (public)

POST/api/subscriptions/subscribe

Subscribe to a creator (requires subscriptions:write)

POST/api/subscriptions/gift/direct

Gift subscription to specific user (requires subscriptions:write)

POST/api/subscriptions/gift/random

Gift subscriptions to random community members (requires subscriptions:write)

POST/api/subscriptions/manage

Manage subscription (cancel, update) (requires subscriptions:write)

Notifications

User notification endpoints for alerts, follows, subs, etc.

GET/api/notifications

Get user notifications (requires notifications:read)

GET/api/notifications/unread-count

Get unread notification count (requires notifications:read)

POST/api/notifications/:id/read

Mark notification as read (requires notifications:write)

POST/api/notifications/read-all

Mark all notifications as read (requires notifications:write)

Volts (Currency)

Velora currency system for tips, purchases, and transactions.

GET/api/volts/wallet

Get user wallet balance (requires payments:read)

GET/api/volts/transactions

Get transaction history (requires payments:read)

POST/api/volts/purchase

Purchase Volts (requires payments:write)

POST/api/volts/send

Send Volts to streamer (requires payments:write)

GET/api/volts/leaderboard/:creatorId

Get top tippers for channel (public)

Channel Points (read & redeem)

Read channel points, redeemable items, and redemptions. Note: Item creation is internal - use webhooks to receive redeem events.

GET/api/channel-points/:channelId/balance

Get user point balance for channel (requires points:read)

GET/api/channel-points/:channelId/items

Get redeemable items for channel (public)

GET/api/channel-points/:channelId/items/with-built-in

Get items including built-in rewards (public)

GET/api/channel-points/:channelId/stream/:streamId/redemptions

Get redemptions for a stream (public)

GET/api/channel-points/:channelId/leaderboard

Get top point earners for channel (public)

POST/api/channel-points/:channelId/redeem/:itemId

Redeem points item (requires points:write)

Journal

Creator journal/blog system.

GET/api/users/:username/journals

Get published journal posts for user (public)

GET/api/journals/:slug

Get specific journal post

GET/api/journals

Get my journal posts including drafts (requires journal:read)

POST/api/journals

Create journal post (requires journal:write)

PUT/api/journals/:slug

Update journal post (requires journal:write)

DELETE/api/journals/:slug

Delete journal post (requires journal:write)

POST/api/journals/:slug/publish

Publish draft (requires journal:write)

POST/api/journals/:slug/images

Upload image to journal post (requires journal:write)

YouTube Integration

Sync and manage YouTube content.

GET/api/youtube/auth/url

Get YouTube OAuth URL (requires youtube:manage)

GET/api/youtube/status

Check YouTube connection status (requires youtube:read)

GET/api/youtube/videos/recent

Get recent synced videos (requires youtube:read)

GET/api/youtube/library

Get YouTube library (requires youtube:read)

GET/api/youtube/playlists

Get YouTube playlists (requires youtube:read)

GET/api/youtube/widgets/:username

Get YouTube widget data for user (public)

POST/api/youtube/disconnect

Disconnect YouTube (requires youtube:manage)

Public reads

No token needed unless a row says otherwise. These are the catalogue surfaces — who is live, what they are playing, the emotes and badges a chat renderer has to resolve.

Streams

GET/api/streams/live

Get live streams (public)

GET/api/streams/browse

Browse live streams with filters (public)

GET/api/streams/featured

Get featured streams (public)

GET/api/streams/top

Get top streams by viewers (public)

GET/api/streams/growing

Get fastest growing streams (public)

GET/api/streams/user/:username

Get stream by username (public)

GET/api/streams/user/:username/vods

Get VODs for a channel (public)

Users

GET/api/users/me

Get current authenticated user

GET/api/users/:username

Get public user profile by username

GET/api/users/search

Search users (query: ?q=term&limit=10)

GET/api/users/:userId/followers

Get user followers

GET/api/users/:userId/following

Get users following

PUT/api/users/me

Update current user profile (requires user:write)

Search

Global search returns creators (with live stream info) and categories. Use this to find live streams by creator name or category.

GET/api/search/global

Search creators and categories (public, query: ?query=term&limit=8). Returns isLive status for each creator.

GET/api/users/search

Search users for mentions/invites (requires auth, query: ?q=term&limit=10)

Emotes

GET/api/emotes

Get all emote collections (global + channel if ?channel=username)

GET/api/emotes/global

Get global emotes only

GET/api/emotes/channel/:username

Get channel emotes by username

GET/api/emotes/resolve

Resolve emote codes to URLs (query: ?codes=emote1,emote2)

Badges

Chat badges including global platform badges and channel subscription badges. All endpoints are public, no auth required.

GET/api/badges/catalog

Get global badge catalog (public, query: ?category=event|achievement|system)

GET/api/badges/channel/:username

Get subscription badges for a channel by username (public)

GET/api/subscriptions/badges/:usernameNew

Get badges for a user (requires authentication)

Followers

POST/api/users/follow/:userId

Follow a user (requires auth)

DELETE/api/users/follow/:userId

Unfollow a user (requires auth)

GET/api/users/follow-status/:userId

Check if following a user (requires auth)

GET/api/users/:userId/followers

Get user followers (public)

GET/api/users/:userId/following

Get users they follow (public)

Clips

GET/api/clips/:clipId

Get clip by ID (public)

GET/api/streams/:username/clips

Get clips for a channel by username (public)

POST/api/streams/:username/clips

Create a clip (requires auth)

Request body — JSON

titlestringrequired

Clip title (3-160 chars)

durationMsnumberrequired

Clip duration in milliseconds (15000-120000, i.e. 15s-120s)

startOffsetMsnumberrequired

Start offset from stream beginning in milliseconds

descriptionstringoptional

Optional description (max 500 chars)

highlightbooleanoptional

Mark as highlight clip

Polls

GET/api/streams/:username/polls/active

Get active poll for a channel (public)

POST/api/streams/:username/polls

Create a poll (requires channel ownership)

POST/api/streams/:username/polls/:pollId/vote

Vote in a poll (requires auth)

POST/api/streams/:username/polls/:pollId/end

End a poll early (requires channel ownership)

Giveaways

Channel giveaway system.

GET/api/streams/:username/giveaways/active

Get active giveaways for channel (public)

POST/api/streams/:username/giveaways

Create giveaway (requires channel ownership)

POST/api/streams/:username/giveaways/:giveawayId/join

Join giveaway (requires user:write)

POST/api/streams/:username/giveaways/:giveawayId/draw

Draw winner (requires channel ownership)

POST/api/streams/:username/giveaways/:giveawayId/end

End giveaway (requires channel ownership)

Teams

GET/api/teams

List all teams (public)

GET/api/teams/:slug

Get team by slug (public)

GET/api/teams/:slug/members

Get team members (public)

Managing your own application

These act on your app rather than on a streamer. You touch them at setup and when rotating credentials, not in your hot path.

Developer Apps

GET/api/developer/apps

List your applications

POST/api/developer/apps

Create a new application

GET/api/developer/apps/:clientId

Get application details

PATCH/api/developer/apps/:clientId

Update application

DELETE/api/developer/apps/:clientId

Delete application

POST/api/developer/apps/:clientId/rotate-secret

Rotate client secret

GET/api/developer/apps/:clientId/scopes

Get app scope grants

Webhooks (Event Subscriptions)

Real-time event notifications for subs, gifts, follows, raids, volts, channel point redeems, etc. Essential for chat bots and integrations.

GET/api/developer/apps/:clientId/webhooks

List all webhooks for your app

POST/api/developer/apps/:clientId/webhooks

Create webhook subscription (events: channel.follow, channel.subscribe, channel.gift, channel.raid, channel.volts, channel.points.redeem, stream.online, stream.offline, etc.)

GET/api/developer/apps/:clientId/webhooks/:id

Get webhook details

PATCH/api/developer/apps/:clientId/webhooks/:id

Update webhook (change events, URL, etc.)

DELETE/api/developer/apps/:clientId/webhooks/:id

Delete webhook subscription

POST/api/developer/apps/:clientId/webhooks/:id/rotate-secret

Rotate webhook signing secret for security

HTTP response codes

Code	Meaning
`200`	Success
`201`	Created successfully
`204`	No content (successful deletion)
`400`	Bad request — invalid parameters
`401`	Unauthorized — invalid or expired token
`403`	Forbidden — insufficient permissions
`404`	Not found — resource doesn't exist
`429`	Rate limited — too many requests
`500`	Internal server error

Error response format

All error responses follow a consistent format:

Response — error body

{
  "error": "error_code",
  "message": "Human-readable error message",
  "details": {
    // Optional additional error details
  }
}

Pagination

List endpoints support cursor-based pagination:

Request

GET /api/streams?limit=25&cursor=eyJsYXN0X2lkIjoi...

Parameter	Description
`limit`	Number of items per page (max 100)
`cursor`	Cursor from previous response for next page

Getting started

New here? Make your first API request, then set up OAuth authentication. Not sure which surface fits what you are building? Start here.

API reference

Before you call anything

Acting on behalf of a streamer

OAuth & Authentication

Streaming Integration (OAuth)

Chat

Channel Points (write, OAuth)

Polls, Predictions, Giveaways, Goals & Timers (OAuth)

Bot Management

Subscriptions

Notifications

Volts (Currency)

Channel Points (read & redeem)

Journal

YouTube Integration

Public reads

Streams

Users

Search

Categories

Emotes

Badges

Followers

Clips

Polls

Giveaways

Teams

Managing your own application

Developer Apps

Webhooks (Event Subscriptions)

HTTP response codes

Error response format

Pagination

Getting started