A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Twitch API is how an app or AI agent works with a Twitch channel: reading who is live, updating a channel's title and category, sending a message into chat, creating channel point rewards, or moderating viewers. Access is granted through an OAuth 2.0 access token, where an app token reaches public data and a user token carries scopes that set which of a channel owner's actions a call can take. Twitch can also push a notification the moment something happens on a channel through EventSub, so an integration learns about activity without polling.
How an app or AI agent connects to Twitch determines what it can reach. There is a route for making calls and a route for receiving events, and each is governed by the access token behind it and the scopes that token carries.
The Helix REST API takes and returns JSON at https://api.twitch.tv/helix, and pages through lists with a cursor returned in a pagination object. Every call sends an Authorization Bearer access token and a Client-Id header naming the app. Read-only public endpoints accept an app access token; endpoints that act for a channel owner need a user access token carrying the right scope.
EventSub is how Twitch pushes live events to an integration. After subscribing to an event type, Twitch sends a notification when it fires, over a webhook callback on HTTPS port 443 (using an app access token and a secret Twitch verifies first), a WebSocket connection (using a user access token), or a conduit. Each event type carries its own version, and many require a scope from the affected channel.
An app access token is obtained through the OAuth 2.0 client-credentials flow using the app's client id and secret. It identifies the app, not a user, and reaches public data such as streams, users, games, and clips. It is also required for EventSub webhook transport. It carries no user scopes and cannot act on a specific channel owner's behalf.
A user access token is obtained through the OAuth 2.0 authorization-code flow, where a Twitch user signs in and approves the scopes the app requested. It acts on behalf of that user and carries only the granted scopes, so it is required for anything tied to a channel owner, like editing channel info, sending chat, managing channel points, or moderating. WebSocket EventSub also uses a user token.
The Twitch API is split into areas an agent can act on, like channel info, streams, chat, channel points, moderation, and live event subscriptions. Each area has its own methods, and some, like banning a viewer or sending a chat message, act on a live broadcast in front of an audience.
Methods for reading user accounts and reading or editing a channel's broadcast settings.
Methods for reading live streams, past videos, and clips, and creating a clip.
Methods for sending messages, reading the viewer list, and posting announcements in chat.
Methods for creating, reading, updating, and deleting custom channel point rewards.
Methods for banning and unbanning viewers, reading moderators, and reading a channel's subscribers.
Methods for looking up games and categories and reading the most-watched games.
Methods for creating, listing, and deleting live event subscriptions.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
Users & ChannelsMethods for reading user accounts and reading or editing a channel's broadcast settings.3 | ||||||
| GET | /helix/users | Get information about one or more Twitch users by id or login name. | read | — | Current | |
No scope required; an app access token and Client-Id are enough. A user token with user:read:email also returns the user's email. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /helix/channels | Get a channel's information, including its current title, game/category, and language. | read | — | Current | |
No scope required; an app or user access token works. Acts onchannel Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /helix/channels | Update a channel's information, like its stream title, game/category, language, or tags. | write | channel:manage:broadcast | Current | |
Requires a user access token with channel:manage:broadcast from the channel owner. Acts onchannel Permission (capability) channel:manage:broadcastVersionAvailable since the API’s base version Webhook event channel.updateRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Streams, Videos & ClipsMethods for reading live streams, past videos, and clips, and creating a clip.4 | ||||||
| GET | /helix/streams | Get a list of live streams, filterable by user, game, language, or stream type. | read | — | Current | |
No scope required; an app or user access token works. Only currently live channels are returned. Acts onstream Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /helix/videos | Get one or more videos by video id, user id, or game id. | read | — | Current | |
No scope required; an app or user access token works. Acts onvideo Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /helix/clips | Get one or more clips by clip id, broadcaster id, or game id. | read | — | Current | |
No scope required; an app or user access token works. Acts onclip Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /helix/clips | Create a clip from a broadcaster's live stream. | write | clips:edit | Current | |
Requires a user access token with clips:edit. The broadcaster must be live. Acts onclip Permission (capability) clips:editVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ChatMethods for sending messages, reading the viewer list, and posting announcements in chat.3 | ||||||
| POST | /helix/chat/messages | Send a message to a channel's chat room on behalf of a user. | write | user:write:chat | Current | |
A user access token needs user:write:chat. An app access token also needs user:bot from the sending user and either channel:bot from the channel or moderator status. Acts onchat_message Permission (capability) user:write:chatVersionAvailable since the API’s base version Webhook event channel.chat.messageRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /helix/chat/chatters | Get the list of users currently connected to a channel's chat room. | read | moderator:read:chatters | Current | |
Requires a user access token with moderator:read:chatters from the broadcaster or one of the channel's moderators. Acts onchatter Permission (capability) moderator:read:chattersVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /helix/chat/announcements | Send an announcement, a highlighted message, to a channel's chat room. | write | moderator:manage:announcements | Current | |
Requires a user access token with moderator:manage:announcements from the broadcaster or a moderator. Acts onannouncement Permission (capability) moderator:manage:announcementsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Channel PointsMethods for creating, reading, updating, and deleting custom channel point rewards.4 | ||||||
| GET | /helix/channel_points/custom_rewards | Get the list of custom channel point rewards a broadcaster created. | read | channel:read:redemptions | Current | |
Requires a user access token with channel:read:redemptions or channel:manage:redemptions from the broadcaster. Acts oncustom_reward Permission (capability) channel:read:redemptionsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /helix/channel_points/custom_rewards | Create a custom channel point reward viewers can redeem. | write | channel:manage:redemptions | Current | |
Requires a user access token with channel:manage:redemptions. Only rewards the app created can later be updated or deleted by it. Acts oncustom_reward Permission (capability) channel:manage:redemptionsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /helix/channel_points/custom_rewards | Update a custom channel point reward the app created. | write | channel:manage:redemptions | Current | |
Requires a user access token with channel:manage:redemptions. The app can only update rewards it created. Acts oncustom_reward Permission (capability) channel:manage:redemptionsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /helix/channel_points/custom_rewards | Delete a custom channel point reward the app created. | write | channel:manage:redemptions | Current | |
Requires a user access token with channel:manage:redemptions. The app can only delete rewards it created. Acts oncustom_reward Permission (capability) channel:manage:redemptionsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Moderation & SubscriptionsMethods for banning and unbanning viewers, reading moderators, and reading a channel's subscribers.4 | ||||||
| GET | /helix/subscriptions | Get the list of users who subscribe to a broadcaster's channel. | read | channel:read:subscriptions | Current | |
Requires a user access token with channel:read:subscriptions from the broadcaster. Acts onsubscription Permission (capability) channel:read:subscriptionsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /helix/moderation/bans | Ban or time out a user from participating in a channel's chat room. | write | moderator:manage:banned_users | Current | |
Requires a user access token with moderator:manage:banned_users from the broadcaster or a moderator. Omitting a duration is a permanent ban; a duration is a timeout. Acts onban Permission (capability) moderator:manage:banned_usersVersionAvailable since the API’s base version Webhook event channel.banRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /helix/moderation/bans | Remove a ban or timeout, letting a user chat in the channel again. | write | moderator:manage:banned_users | Current | |
Requires a user access token with moderator:manage:banned_users from the broadcaster or a moderator. Acts onban Permission (capability) moderator:manage:banned_usersVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /helix/moderation/moderators | Get the list of users allowed to moderate a broadcaster's chat room. | read | moderation:read | Current | |
Requires a user access token with moderation:read or channel:manage:moderators from the broadcaster. Acts onmoderator Permission (capability) moderation:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Games & CategoriesMethods for looking up games and categories and reading the most-watched games.2 | ||||||
| GET | /helix/games | Get information about one or more games (categories) by id or name. | read | — | Current | |
No scope required; an app or user access token works. Acts ongame Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /helix/games/top | Get the list of games sorted by the number of current viewers, most first. | read | — | Current | |
No scope required; an app or user access token works. Acts ongame Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
EventSubMethods for creating, listing, and deleting live event subscriptions.3 | ||||||
| POST | /helix/eventsub/subscriptions | Create an EventSub subscription so Twitch notifies the app when an event fires. | write | — | Current | |
Token type depends on transport: webhook needs an app access token, WebSocket needs a user access token. The scope, if any, is set by the chosen event type, not this endpoint. Acts oneventsub_subscription Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /helix/eventsub/subscriptions | Get the list of EventSub subscriptions the app created, filterable by status or type. | read | — | Current | |
Uses the same token type as the subscriptions it lists; no extra scope of its own. Acts oneventsub_subscription Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /helix/eventsub/subscriptions | Delete an EventSub subscription so Twitch stops sending its notifications. | write | — | Current | |
Uses the same token type as the subscription being deleted; no extra scope of its own. Acts oneventsub_subscription Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Twitch can notify an app the moment something happens on a channel, like a stream going live or a new follow, through EventSub. An integration subscribes to the events it cares about and receives a notification when each one fires, so it learns about activity without polling.
| Event | What it signals | Triggered by |
|---|---|---|
stream.online | A broadcaster started a stream. The notification carries the broadcaster and stream type. | In-app only |
stream.offline | A broadcaster stopped a stream and went offline. | In-app only |
channel.update | A channel's metadata changed, like its title, category, language, or content labels. | /helix/channels |
channel.follow | A user followed a channel. Subscribing requires the moderator:read:followers scope. | In-app only |
channel.chat.message | A message was sent to a channel's chat room. Subscribing requires the user:read:chat scope from the chatting user. | /helix/chat/messages |
channel.ban | A viewer was banned or timed out from a channel. Subscribing requires the channel:moderate scope. | /helix/moderation/bans |
Twitch limits how fast an app can call using a points-per-minute model, where most requests cost one point and the response carries headers showing how many points are left.
Twitch meters requests with a token-bucket model rather than a fixed requests-per-second cap. An app is given a bucket of points, and each endpoint costs a points value, by default one point per request. App access and user access tokens have separate buckets. Every response carries Ratelimit-Limit (the bucket size, commonly 800), Ratelimit-Remaining (points left), and Ratelimit-Reset (a Unix timestamp when the bucket refills). Going over returns HTTP 429 Too Many Requests; some endpoints also return 429 for their own per-endpoint limits, signalled in the error message.
Most list endpoints are cursor-based. A response includes a pagination object holding a cursor, and the next page is fetched by passing that cursor in the after query parameter. The first parameter sets the page size. When there are no more results the pagination object comes back empty.
The first query parameter sets how many items a page returns, with a documented maximum that varies by endpoint (commonly 100). EventSub allows up to 300 enabled subscriptions per WebSocket connection.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | Bad Request | The request was malformed, like a missing required query parameter or an invalid body. The JSON response carries error, status, and message fields naming the problem. | Read the message field, fix the parameters or body, and resend. The request is not retryable as-is. |
| 401 | Unauthorized | The access token is missing, expired, or invalid; the Client-Id header is missing or does not match the token; or a user token lacks the scope the endpoint requires. | Send both an Authorization Bearer token and a matching Client-Id, refresh an expired token, or have the user re-authorize with the missing scope. |
| 403 | Forbidden | The token is valid but not permitted for this action, for example a moderation call by a user who is not the broadcaster or a moderator of the channel. | Use a token from a user who has the required role on the channel, or request the action against a channel the user controls. |
| 404 | Not Found | The requested resource does not exist, like an unknown user id, channel, or subscription. | Verify the id or login passed in the query and confirm the resource exists. |
| 429 | Too Many Requests | The app exhausted its points bucket, or hit a per-endpoint limit. The Ratelimit-Reset header gives a Unix timestamp for when the bucket refills. | Back off until Ratelimit-Reset, then retry, and smooth the request rate to stay within Ratelimit-Limit. |
| 500 | Internal Server Error | An error on Twitch's side. It is uncommon. | Retry with exponential backoff. If it persists, check the Twitch developer forums or status page. |
Twitch does not put a dated version number on the Helix API. It is a single, continuously updated API, while each EventSub event type carries its own version number that is pinned when an integration subscribes.
Helix is Twitch's current API, REST over JSON, and it carries no dated or numbered API-wide version; it is continuously updated. Versioning applies only to EventSub, where each event type has its own version pinned at subscription time. The older v5 (Kraken) API was retired.
When using an app access token to send chat, messages by default are delivered only to the source channel named by broadcaster_id, rather than across a shared chat session.
Twitch added the channel.chat.message EventSub subscription for reading chat, a Helix endpoint for sending chat messages, and the Conduit transport method for EventSub, as a managed path off legacy IRC chat.
The legacy /helix/users/follows endpoint was shut down and replaced by Get Channel Followers and Get Followed Channels, which use new scopes.
There is no API-wide version to pin; pin the version of each EventSub event type instead.
Twitch API changelog ↗Bollard AI sits between a team's AI agents and Twitch. Grant each agent exactly the access it needs, read or write, area by area, and every call is checked and logged.