Contents

Twitch API Reference

Resource Endpoint Description
Ads Start Commercial

Starts a commercial on the specified channel.

Analytics Get Extension Analytics

Gets an analytics report for one or more extensions.

Analytics Get Game Analytics

Gets an analytics report for one or more games.

Bits Get Bits Leaderboard

Gets the Bits leaderboard for the authenticated broadcaster.

Bits Get Cheermotes

Gets a list of Cheermotes that users can use to cheer Bits.

Bits Get Extension Transactions

Gets a list of transactions for an extension.

Channels Get Channel Information

Gets information about one or more channels.

Channels Modify Channel Information

Updates a channel’s properties.

Channels Get Channel Editors

Gets a list of users that are editors for the specified broadcaster.

Channel Points Create Custom Rewards

Creates a Custom Reward in the broadcaster’s channel.

Channel Points Delete Custom Reward

Deletes a custom reward that the broadcaster created.

Channel Points Get Custom Reward

Gets a list of custom rewards that the specified broadcaster created.

Channel Points Get Custom Reward Redemption

Gets a list of redemptions for a custom reward.

Channel Points Update Custom Reward

Updates a custom reward.

Channel Points Update Redemption Status

Updates a redemption’s status.

Charity Get Charity Campaign

BETA Gets information about the broadcaster’s active charity campaign.

Charity Get Charity Campaign Donations

BETA Gets the list of donations that users have made to the broadcaster’s active charity campaign.

Chat Get Chatters

Gets the list of users that are connected to the broadcaster’s chat session.

Chat Get Channel Emotes

Gets all emotes that the specified Twitch channel created.

Chat Get Global Emotes

Gets all global emotes.

Chat Get Emote Sets

Gets emotes for one or more specified emote sets.

Chat Get Channel Chat Badges

Gets all badges that the specified broadcaster created.

Chat Get Global Chat Badges

Gets the list of chat badges that Twitch created.

Chat Get Chat Settings

Gets the broadcaster’s chat settings.

Chat Update Chat Settings

Updates the broadcaster’s chat settings.

Chat Send Chat Announcement

Sends an announcement to the broadcaster’s chat room.

Chat Get User Chat Color

Gets the color used for the user’s name in chat.

Chat Update User Chat Color

Updates the color used for the user’s name in chat.

Clips Create Clip

Creates a clip from the broadcaster’s stream.

Clips Get Clips

Gets one or more video clips.

Entitlements Get Code Status

Gets the status of one or more redemption codes for a Bits reward.

Entitlements Get Drops Entitlements

Gets an organization’s list of entitlements that have been granted to a game, a user, or both.

Entitlements Update Drops Entitlements

Updates the Drop entitlement’s fulfillment status.

Entitlements Redeem Code

Redeems one or more redemption codes.

Extensions Get Extension Configuration Segment

Gets the specified configuration segment from the specified extension.

Extensions Set Extension Configuration Segment

Updates a configuration segment.

Extensions Set Extension Required Configuration

Updates the extension’s required_configuration string.

Extensions Send Extension PubSub Message

Sends a message to one or more viewers.

Extensions Get Extension Live Channels

Gets a list of broadcasters that are streaming live and have installed or activated the extension.

Extensions Get Extension Secrets

Gets an extension’s list of shared secrets.

Extensions Create Extension Secret

Creates a shared secret used to sign and verify JWT tokens.

Extensions Send Extension Chat Message

Sends a message to the specified broadcaster’s chat room.

Extensions Get Extensions

Gets information about an extension.

Extensions Get Released Extensions

Gets information about a released extension.

Extensions Get Extension Bits Products

Gets the list of Bits products that belongs to the extension.

Extensions Update Extension Bits Product

Adds or updates a Bits product that the extension created.

EventSub Create EventSub Subscription

Creates an EventSub subscription.

EventSub Delete EventSub Subscription

Deletes an EventSub subscription.

EventSub Get EventSub Subscriptions

Gets a list of EventSub subscriptions that the client in the access token created.

Games Get Top Games

Gets information about all broadcasts on Twitch.

Games Get Games

Gets information about specified games.

Goals Get Creator Goals

Gets the broadcaster’s list of active goals.

Hype Train Get Hype Train Events

Gets information about the broadcaster’s current or most recent Hype Train event.

Moderation Check AutoMod Status

Checks whether AutoMod would flag the specified message for review.

Moderation Manage Held AutoMod Messages

Allow or deny the message that AutoMod flagged for review.

Moderation Get AutoMod Settings

Gets the broadcaster’s AutoMod settings.

Moderation Update AutoMod Settings

Updates the broadcaster’s AutoMod settings.

Moderation Get Banned Users

Gets all users that the broadcaster banned or put in a timeout.

Moderation Ban User

Bans a user from participating in a broadcaster’s chat room or puts them in a timeout.

Moderation Unban User

Removes the ban or timeout that was placed on the specified user.

Moderation Get Blocked Terms

Gets the broadcaster’s list of non-private, blocked words or phrases.

Moderation Add Blocked Term

Adds a word or phrase to the broadcaster’s list of blocked terms.

Moderation Remove Blocked Term

Removes the word or phrase from the broadcaster’s list of blocked terms.

Moderation Delete Chat Messages

Removes a single chat message or all chat messages from the broadcaster’s chat room.

Moderation Get Moderators

Gets all users allowed to moderate the broadcaster’s chat room.

Moderation Add Channel Moderator

Adds a moderator to the broadcaster’s chat room.

Moderation Remove Channel Moderator

Removes a moderator from the broadcaster’s chat room.

Moderation Get VIPs

Gets a list of the broadcaster’s VIPs.

Moderation Add Channel VIP

Adds the specified user as a VIP in the broadcaster’s channel.

Moderation Remove Channel VIP

Removes the specified user as a VIP in the broadcaster’s channel.

Moderation Update Shield Mode Status

BETA Activates or deactivates the broadcaster’s Shield Mode.

Moderation Get Shield Mode Status

BETA Gets the broadcaster’s Shield Mode activation status.

Polls Get Polls

Gets a list of polls that the broadcaster created.

Polls Create Poll

Creates a poll that viewers in the broadcaster’s channel can vote on.

Polls End Poll

End an active poll.

Predictions Get Predictions

Gets a list of Channel Points Predictions that the broadcaster created.

Predictions Create Prediction

Create a Channel Points Prediction.

Predictions End Prediction

Locks, resolves, or cancels a Channel Points Prediction.

Raids Start a raid

Raid another channel by sending the broadcaster’s viewers to the targeted channel.

Raids Cancel a raid

Cancel a pending raid.

Schedule Get Channel Stream Schedule

Gets the broadcaster’s streaming schedule.

Schedule Get Channel iCalendar

Gets the broadcaster’s streaming schedule as an iCalendar.

Schedule Update Channel Stream Schedule

Updates the broadcaster’s schedule settings, such as scheduling a vacation.

Schedule Create Channel Stream Schedule Segment

Adds a single or recurring broadcast to the broadcaster’s streaming schedule.

Schedule Update Channel Stream Schedule Segment

Updates a scheduled broadcast segment.

Schedule Delete Channel Stream Schedule Segment

Deletes a broadcast from the broadcaster’s streaming schedule.

Search Search Categories

Gets the games or categories that match the specified query.

Search Search Channels

Gets the channels that match the specified query and have streamed content within the past 6 months.

Music Get Soundtrack Current Track

Gets the Soundtrack track that the broadcaster is playing.

Music Get Soundtrack Playlist

Gets the Soundtrack playlist’s tracks.

Music Get Soundtrack Playlists

Gets a list of Soundtrack playlists.

Streams Get Stream Key

Gets the channel’s stream key.

Streams Get Streams

Gets a list of all broadcasters that are streaming.

Streams Get Followed Streams

Gets a list of live streams of broadcasters that the specified user follows.

Streams Create Stream Marker

Adds a marker to a live stream.

Streams Get Stream Markers

Gets a list of markers from the user’s most recent stream or from the specified VOD/video.

Subscriptions Get Broadcaster Subscriptions

Gets a list of users that subscribe to the specified broadcaster.

Subscriptions Check User Subscription

Checks whether the user subscribes to the broadcaster’s channel.

Tags Get All Stream Tags

Gets the list of all stream tags that Twitch defines. You can also filter the list by one or more tag IDs.

Tags Get Stream Tags

Gets the list of stream tags that the broadcaster or Twitch added to their channel.

Tags Replace Stream Tags

Applies one or more tags to the specified channel, overwriting existing tags.

Teams Get Channel Teams

Gets the list of Twitch teams that the broadcaster is a member of.

Teams Get Teams

Gets information about the specified Twitch team.

Users Get Users

Gets information about one or more users.

Users Update User

Updates the user’s information.

Users Get Users Follows

Gets information about users that are following other users.

Users Get User Block List

Gets the list of users that the broadcaster has blocked.

Users Block User

Blocks the specified user from interacting with or having contact with the broadcaster.

Users Unblock User

Removes the user from the broadcaster’s list of blocked users.

Users Get User Extensions

Gets a list of all extensions (both active and inactive) that the broadcaster has installed.

Users Get User Active Extensions

Gets the active extensions that the broadcaster has installed for each configuration.

Users Update User Extensions

Updates an installed extension’s information.

Videos Get Videos

Gets information about one or more published videos.

Videos Delete Videos

Deletes one or more videos.

Whispers Send Whisper

Sends a whisper message to the specified user.

Start Commercial

Starts a commercial on the specified channel.

NOTE: Only partners and affiliates may run commercials and they must be streaming live at the time.

NOTE: Only the broadcaster may start a commercial; the broadcaster’s editors and moderators may not start commercials on behalf of the broadcaster.

Authentication

Requires a user access token that includes the channel:edit:commercial scope.

URL

POST https://api.twitch.tv/helix/channels/commercial

Request Body

Field Type Description
broadcaster_id String The ID of the partner or affiliate broadcaster that wants to run the commercial. This ID must match the user ID found in the OAuth token.
length Integer The length of the commercial to run, in seconds. Twitch tries to serve a commercial that’s the requested length, but it may be shorter or longer. The maximum length you should request is 180 seconds.

Response Body

Field Type Description
data Object[] An array that contains a single object with the status of your start commercial request.
   length Integer The length of the commercial you requested. If you request a commercial that’s longer than 180 seconds, the API uses 180 seconds.
   message String A message that indicates whether Twitch was able to serve an ad.
   retry_after Integer The number of seconds you must wait before running another commercial.

Response Codes

Code Description
200 OK Successfully started the commercial.
400 Bad Request
  • The broadcaster_id query parameter is required.
  • The length query parameter is required.
  • The ID in broadcaster_id is not valid.
  • To start a commercial, the broadcaster must be streaming live.
  • The broadcaster may not run another commercial until the cooldown period expires. The retry_after field in the previous start commercial response specifies the amount of time the broadcaster must wait between running commercials.
401 Unauthorized
  • The ID in broadcaster_id must match the user ID found in the request’s OAuth token.
  • The Authorization header is required and must contain a user access token.
  • The user access token must include the channel:edit:commercial scope.
  • The OAuth token is not valid.
  • The client ID specified in the Client-Id header does not match the client ID specified in the OAuth token.
404 Not Found
  • The ID in broadcaster_id was not found.
429 Too Many Requests
  • The broadcaster may not run another commercial until the cooldown period expires. The retry_after field in the previous start commercial response specifies the amount of time the broadcaster must wait between running commercials.

Example Request

This request starts a commercial.

curl -X POST 'https://api.twitch.tv/helix/channels/commercial' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz' \
-H 'Content-Type: application/json' \
--data-raw '{
  "broadcaster_id": "41245072",
  "length": 60
}'

Example Response

{
  "data": [
    {
      "length" : 60,
      "message" : "",
      "retry_after" : 480
    }
  ]
}

Get Extension Analytics

Gets an analytics report for one or more extensions. The response contains the URLs used to download the reports (CSV files). Learn More

Authentication

Requires a user access token that includes the analytics:read:extensions scope.

URL

GET https://api.twitch.tv/helix/analytics/extensions

Request Query Parameters

Name Type Required? Description
extension_id String No The extension’s client ID. If specified, the response contains a report for the specified extension. If not specified, the response includes a report for each extension that the authenticated user owns.
type String No The type of analytics report to get. Possible values are:
  • overview_v2
started_at String No The reporting window’s start date, in RFC3339 format. Set the time portion to zeroes (for example, 2021-10-22T00:00:00Z).

The start date must be on or after January 31, 2018. If you specify an earlier date, the API ignores it and uses January 31, 2018. If you specify a start date, you must specify an end date. If you don’t specify a start and end date, the report includes all available data since January 31, 2018.

The report contains one row of data for each day in the reporting window.
ended_at String No The reporting window’s end date, in RFC3339 format. Set the time portion to zeroes (for example, 2021-10-27T00:00:00Z). The report is inclusive of the end date.

Specify an end date only if you provide a start date. Because it can take up to two days for the data to be available, you must specify an end date that’s earlier than today minus one to two days. If not, the API ignores your end date and uses an end date that is today minus one to two days.
first Integer No The maximum number of report URLs to return per page in the response. The minimum page size is 1 URL per page and the maximum is 100 URLs per page. The default is 20.

NOTE: While you may specify a maximum value of 100, the response will contain at most 20 URLs per page.
after String No The cursor used to get the next page of results. The Pagination object in the response contains the cursor’s value. Read More

This parameter is ignored if the extension_id parameter is set.

Response Body

Field Type Description
data Object[] A list of reports. The reports are returned in no particular order; however, the data within each report is in ascending order by date (newest first). The report contains one row of data per day of the reporting window; the report contains rows for only those days that the extension was used. The array is empty if there are no reports.
   extension_id String An ID that identifies the extension that the report was generated for.
   URL String The URL that you use to download the report. The URL is valid for 5 minutes.
   type String The type of report.
   date_range Object The reporting window’s start and end dates, in RFC3339 format.
      started_at String The reporting window’s start date.
      ended_at String The reporting window’s end date.
pagination Object Contains the information used to page through the list of results. The object is empty if there are no more pages left to page through. Read More
   cursor String The cursor used to get the next page of results. Use the cursor to set the request’s after query parameter.

Response Codes

Code Description
200 OK Successfully retrieved the broadcaster’s analytics reports.
400 Bad Request
  • The start and end dates are optional but if you specify one, you must specify the other.
  • The end date must be equal to or later than the start date.
  • The cursor specified in the after query parameter is not valid.
  • The resource supports only forward pagination (use the after query parameter).
  • The first query parameter is outside the allowed range of values.
401 Unauthorized
  • The Authorization header is required and must contain a user access token.
  • The user access token must include the analytics:read:extensions scope.
  • The OAuth token is not valid.
  • The Client-Id header is required.
  • The client ID specified in the Client-Id header does not match the client ID specified in the OAuth token.
404 Not Found
  • The extension specified in the extension_id query parameter was not found.

Example Request

Gets the URLs for all reports for all extensions of the authenticated client. The request was issued on June 1, 2018.

curl -X GET 'https://api.twitch.tv/helix/analytics/extensions' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
   "data": [
      {
         "extension_id": "efgh",
         "URL": "https://twitch-piper-reports.s3-us-west-2.amazonaws.com/dynamic/LoL%20ADC...",
         "type": "overview_v2",
         "date_range": {
            "started_at": "2018-03-01T00:00:00Z",
            "ended_at": "2018-06-01T00:00:00Z"
         }
      },
      ...
   ],
   "pagination": {"cursor": "eyJiIjpudWxsLCJhIjp7Ik9mZnNldCI6NX19"}
}

Get Game Analytics

Gets an analytics report for one or more games. The response contains the URLs used to download the reports (CSV files). Learn more

Authentication

Requires a user access token that includes the analytics:read:games scope.

URL

GET https://api.twitch.tv/helix/analytics/games

Request Query Parameters

Name Type Required? Description
game_id String No The game’s client ID. If specified, the response contains a report for the specified game. If not specified, the response includes a report for each of the authenticated user’s games.
type String No The type of analytics report to get. Possible values are:
  • overview_v2
started_at String No The reporting window’s start date, in RFC3339 format. Set the time portion to zeroes (for example, 2021-10-22T00:00:00Z). If you specify a start date, you must specify an end date.

The start date must be within one year of today’s date. If you specify an earlier date, the API ignores it and uses a date that’s one year prior to today’s date. If you don’t specify a start and end date, the report includes all available data for the last 365 days from today.

The report contains one row of data for each day in the reporting window.
ended_at String No The reporting window’s end date, in RFC3339 format. Set the time portion to zeroes (for example, 2021-10-22T00:00:00Z). The report is inclusive of the end date.

Specify an end date only if you provide a start date. Because it can take up to two days for the data to be available, you must specify an end date that’s earlier than today minus one to two days. If not, the API ignores your end date and uses an end date that is today minus one to two days.
first Integer No The maximum number of report URLs to return per page in the response. The minimum page size is 1 URL per page and the maximum is 100 URLs per page. The default is 20.

NOTE: While you may specify a maximum value of 100, the response will contain at most 20 URLs per page.
after String No The cursor used to get the next page of results. The Pagination object in the response contains the cursor’s value. Read More

This parameter is ignored if game_id parameter is set.

Response Body

Field Type Description
data Object[] A list of reports. The reports are returned in no particular order; however, the data within each report is in ascending order by date (newest first). The report contains one row of data per day of the reporting window; the report contains rows for only those days that the game was used. A report is available only if the game was broadcast for at least 5 hours over the reporting period. The array is empty if there are no reports.
   game_id String An ID that identifies the game that the report was generated for.
   URL String The URL that you use to download the report. The URL is valid for 5 minutes.
   type String The type of report.
   date_range Object The reporting window’s start and end dates, in RFC3339 format.
      started_at String The reporting window’s start date.
      ended_at String The reporting window’s end date.
pagination Object Contains the information used to page through the list of results. The object is empty if there are no more pages left to page through. Read More
   cursor String The cursor used to get the next page of results. Use the cursor to set the request’s after query parameter.

Response Codes

Code Description
200 OK Successfully retrieved the broadcaster’s analytics reports.
400 Bad Request
  • The start and end dates are optional but if you specify one, you must specify the other.
  • The end date must be equal to or later than the start date.
  • The cursor specified in the after query parameter is not valid.
  • The resource supports only forward pagination (use the after query parameter).
  • The first query parameter is outside the allowed range of values.
401 Unauthorized
  • The Authorization header is required and must contain a user access token.
  • The user access token must include the analytics:read:games scope.
  • The OAuth token is not valid.
  • The Client-Id header is required.
  • The client ID specified in the Client-Id header does not match the client ID specified in the OAuth token.
404 Not Found
  • The game specified in the game_id query parameter was not found.

Example Request

Gets the URL for a downloadable CSV report for game ID 493057, covering the period January 1, 2018 through March 1, 2018.

curl -X GET 'https://api.twitch.tv/helix/analytics/games?game_id=493057&started_at=2018-01-01T00:00:00Z&ended_at=2018-03-01T00:00:00Z' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
  "data": [
    {
      "game_id" : "493057",
      "URL" : "https://twitch-piper-reports.s3-us-west-2.amazonaws.com/games/66170/overview/15183...",
      "type" : "overview_v2",
      "date_range" : {
        "started_at" : "2018-01-01T00:00:00Z",
        "ended_at" : "2018-03-01T00:00:00Z"
      }
    }
  ]
}

Example Request

Gets the first 5 URLs for all reports for all games of the authenticated client. The request was issued on June 14, 2018.

curl -X GET 'https://api.twitch.tv/helix/analytics/games?first=5' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
  "data": [
    {
      "game_id": "9821",
      "URL": "https://twitch-piper-reports.s3-us-west-2.amazonaws.com/games/9821/overview/152642...",
      "type" : "overview_v2",
      "date_range" : {
        "started_at" : "2018-03-13T00:00:00Z",
        "ended_at" : "2018-06-13T00:00:00Z"
      }
    },
    ...
  ],
  "pagination": {"cursor": "eyJiIjpudWxsLJxhIjoiIn0gf5"}
}

Get Bits Leaderboard

Gets the Bits leaderboard for the authenticated broadcaster.

Authentication

Requires a user access token that includes the bits:read scope.

URL

GET https://api.twitch.tv/helix/bits/leaderboard

Request Query Parameters

Parameter Type Required? Description
count Integer No The number of results to return. The minimum count is 1 and the maximum is 100. The default is 10.
period String No The time period over which data is aggregated (uses the PST time zone). Possible values are:
  • day — A day spans from 00:00:00 on the day specified in started_at and runs through 00:00:00 of the next day.
  • week — A week spans from 00:00:00 on the Monday of the week specified in started_at and runs through 00:00:00 of the next Monday.
  • month — A month spans from 00:00:00 on the first day of the month specified in started_at and runs through 00:00:00 of the first day of the next month.
  • year — A year spans from 00:00:00 on the first day of the year specified in started_at and runs through 00:00:00 of the first day of the next year.
  • all — Default. The lifetime of the broadcaster's channel.
started_at String No The start date, in RFC3339 format, used for determining the aggregation period. Specify this parameter only if you specify the period query parameter. The start date is ignored if period is all.

Note that the date is converted to PST before being used, so if you set the start time to 2022-01-01T00:00:00.0Z and period to month, the actual reporting period is December 2021, not January 2022. If you want the reporting period to be January 2022, you must set the start time to 2022-01-01T08:00:00.0Z or 2022-01-01T00:00:00.0-08:00.

If your start date uses the ‘+’ offset operator (for example, 2022-01-01T00:00:00.0+05:00), you must URL encode the start date.
user_id String No An ID that identifies a user that cheered bits in the channel. If count is greater than 1, the response may include users ranked above and below the specified user. To get the leaderboard’s top leaders, don’t specify a user ID.

Response Body

Field Type Description
data Object[] A list of leaderboard leaders. The leaders are returned in rank order by how much they’ve cheered. The array is empty if nobody has cheered bits.
   user_id String An ID that identifies a user on the leaderboard.
   user_login String The user’s login name.
   user_name String The user’s display name.
   rank Integer The user’s position on the leaderboard.
   score Integer The number of Bits the user has cheered.
date_range Object The reporting window’s start and end dates, in RFC3339 format. The dates are calculated by using the started_at and period query parameters. If you don’t specify the started_at query parameter, the fields contain empty strings.
   started_at String The reporting window’s start date.
   ended_at String The reporting window’s end date.
total Integer The number of ranked users in data. This is the value in the count query parameter or the total number of entries on the leaderboard, whichever is less.

Response Codes

Code Description
200 OK Successfully retrieved the broadcaster’s Bits leaderboard.
400 Bad Request
  • The time period specified in the period query parameter is not valid.
  • The started_at query parameter is required if period is not set to all.
  • The value in the count query parameter is outside the range of allowed values.
401 Unauthorized
  • The Authorization header is required and must specify a user access token.
  • The user access token must include the the bits:read scope.
  • The access token is not valid.
  • The ID in the Client-Id header must match the client ID in the access token.
403 Forbidden  

Example Request

Gets information about the authenticated broadcaster’s top two Bits leaderboard entries for the specified week.

curl -X GET 'https://api.twitch.tv/helix/bits/leaderboard?count=2&period=week&started_at=2018-02-05T08%3A00%3A00Z' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
  "data": [
    {
      "user_id": "158010205",
      "user_login": "tundracowboy",
      "user_name": "TundraCowboy",
      "rank": 1,
      "score": 12543
    },
    {
      "user_id": "7168163",
      "user_login": "topramens",
      "user_name": "Topramens",
      "rank": 2,
      "score": 6900
    }
  ],
  "date_range": {
    "started_at": "2018-02-05T08:00:00Z",
    "ended_at": "2018-02-12T08:00:00Z"
  },
  "total": 2
}

Get Cheermotes

Gets a list of Cheermotes that users can use to cheer Bits in any Bits-enabled channel’s chat room. Cheermotes are animated emotes that viewers can assign Bits to.

URL

GET https://api.twitch.tv/helix/bits/cheermotes

Authentication

Requires an app access token or user access token.

Request Query Parameters

Parameter Type Required? Description
broadcaster_id String No The ID of the broadcaster whose custom Cheermotes you want to get. Specify the broadcaster’s ID if you want to include the broadcaster’s Cheermotes in the response (not all broadcasters upload Cheermotes). If not specified, the response contains only global Cheermotes.

If the broadcaster uploaded Cheermotes, the type field in the response is set to channel_custom.

Response Body

Field Type Description
data Object[] The list of Cheermotes. The list is in ascending order by the order field’s value.
   prefix String The name portion of the Cheermote string that you use in chat to cheer Bits. The full Cheermote string is the concatenation of {prefix} + {number of Bits}. For example, if the prefix is “Cheer” and you want to cheer 100 Bits, the full Cheermote string is Cheer100. When the Cheermote string is entered in chat, Twitch converts it to the image associated with the Bits tier that was cheered.
   tiers Object[] A list of tier levels that the Cheermote supports. Each tier identifies the range of Bits that you can cheer at that tier level and an image that graphically identifies the tier level.
      min_bits Integer The minimum number of Bits that you must cheer at this tier level. The maximum number of Bits that you can cheer at this level is determined by the required minimum Bits of the next tier level minus 1. For example, if min_bits is 1 and min_bits for the next tier is 100, the Bits range for this tier level is 1 through 99. The minimum Bits value of the last tier is the maximum number of Bits you can cheer using this Cheermote. For example, 10000.
      id String The tier level. Possible tiers are:
  • 1
  • 100
  • 500
  • 1000
  • 5000
  • 10000
  • 100000
      color String The hex code of the color associated with this tier level (for example, #979797).
      images Dictionary The animated and static image sets for the Cheermote. The dictionary of images is organized by theme, format, and size. The theme keys are dark and light. Each theme is a dictionary of formats: animated and static. Each format is a dictionary of sizes: 1, 1.5, 2, 3, and 4. The value of each size contains the URL to the image.
      can_cheer Boolean A Boolean value that determines whether users can cheer at this tier level.
      show_in_bits_card Boolean A Boolean value that determines whether this tier level is shown in the Bits card. Is true if this tier level is shown in the Bits card.
   type String The type of Cheermote. Possible values are:
  • global_first_party — A Twitch-defined Cheermote that is shown in the Bits card.
  • global_third_party — A Twitch-defined Cheermote that is not shown in the Bits card.
  • channel_custom — A broadcaster-defined Cheermote.
  • display_only — Do not use; for internal use only.
  • sponsored — A sponsor-defined Cheermote. When used, the sponsor adds additional Bits to the amount that the user cheered. For example, if the user cheered Terminator100, the broadcaster might receive 110 Bits, which includes the sponsor's 10 Bits contribution.
   order Integer The order that the Cheermotes are shown in the Bits card. The numbers may not be consecutive. For example, the numbers may jump from 1 to 7 to 13. The order numbers are unique within a Cheermote type (for example, global_first_party) but may not be unique amongst all Cheermotes in the response.
   last_updated String The date and time, in RFC3339 format, when this Cheermote was last updated.
   is_charitable Boolean A Boolean value that indicates whether this Cheermote provides a charitable contribution match during charity campaigns.

Response Codes

Code Description
200 OK Successfully retrieved the Cheermotes.
401 Unauthorized
  • The Authorization header is required and must specify an app access token or user access token.
  • The ID in the Client-Id header must match the Client ID in the OAuth token.

Example Requests

Gets a list of all global Cheermotes.

curl -X GET 'https://api.twitch.tv/helix/bits/cheermotes' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'

Gets a list of all global Cheermotes and any Cheermotes that the broadcaster has uploaded.

curl -X GET 'https://api.twitch.tv/helix/bits/cheermotes?broadcaster_id=41245072' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'

Example Response

{
  "data": [
    {
      "prefix": "Cheer",
      "tiers": [
        {
          "min_bits": 1,
          "id": "1",
          "color": "#979797",
          "images": {
            "dark": {
              "animated": {
                "1": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/dark/animated/1/1.gif",
                "1.5": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/dark/animated/1/1.5.gif",
                "2": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/dark/animated/1/2.gif",
                "3": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/dark/animated/1/3.gif",
                "4": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/dark/animated/1/4.gif"
              },
              "static": {
                "1": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/dark/static/1/1.png",
                "1.5": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/dark/static/1/1.5.png",
                "2": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/dark/static/1/2.png",
                "3": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/dark/static/1/3.png",
                "4": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/dark/static/1/4.png"
              }
            },
            "light": {
              "animated": {
                "1": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/light/animated/1/1.gif",
                "1.5": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/light/animated/1/1.5.gif",
                "2": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/light/animated/1/2.gif",
                "3": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/light/animated/1/3.gif",
                "4": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/light/animated/1/4.gif"
              },
              "static": {
                "1": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/light/static/1/1.png",
                "1.5": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/light/static/1/1.5.png",
                "2": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/light/static/1/2.png",
                "3": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/light/static/1/3.png",
                "4": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/light/static/1/4.png"
              }
            }
          },
          "can_cheer": true,
          "show_in_bits_card": true
        }
        ...
      ],
      "type": "global_first_party",
      "order": 1,
      "last_updated": "2018-05-22T00:06:04Z",
      "is_charitable": false
    },
    ...
  ]
}

Get Extension Transactions

Gets a list of transactions for an extension. A transaction records the exchange of a currency (for example, Bits) for a digital product.

Authentication

Requires an app access token.

URL

GET https://api.twitch.tv/helix/extensions/transactions

Request Query Parameters

Parameter Type Required? Description
extension_id String Yes The ID of the extension whose list of transactions you want to get.
id String No A transaction ID used to filter the list of transactions. Specify this parameter for each transaction you want to get. For example, id=1234&id=5678. You may specify a maximum of 100 IDs.
first Integer No The maximum number of items to return per page in the response. The minimum page size is 1 item per page and the maximum is 100 items per page. The default is 20.
after String No The cursor used to get the next page of results. The Pagination object in the response contains the cursor’s value. Read More

Response Body

Field Type Description
data Object[] The list of transactions.
   id String An ID that identifies the transaction.
   timestamp String The UTC date and time (in RFC3339 format) of the transaction.
   broadcaster_id String The ID of the broadcaster that owns the channel where the transaction occurred.
   broadcaster_login String The broadcaster’s login name.
   broadcaster_name String The broadcaster’s display name.
   user_id String The ID of the user that purchased the digital product.
   user_login String The user’s login name.
   user_name String The user’s display name.
   product_type String The type of transaction. Possible values are:
  • BITS_IN_EXTENSION
   product_data Object Contains details about the digital product.
      sku String An ID that identifies the digital product.
      domain String Set to twitch.ext. + <the extension's ID>.
      cost Object Contains details about the digital product’s cost.
         amount Integer The amount exchanged for the digital product.
         type String The type of currency exchanged. Possible values are:
  • bits
      inDevelopment Boolean A Boolean value that determines whether the product is in development. Is true if the digital product is in development and cannot be exchanged.
      displayName String The name of the digital product.
      expiration String This field is always empty since you may purchase only unexpired products.
       broadcast Boolean A Boolean value that determines whether the data was broadcast to all instances of the extension. Is true if the data was broadcast to all instances.
pagination Object Contains the information used to page through the list of results. The object is empty if there are no more pages left to page through. Read More
   cursor String The cursor used to get the next page of results. Use the cursor to set the request’s after query parameter.

Response Codes

Code Description
200 OK Sccessfully retrieved the list of transactions.
400 Bad Request
  • The extension_id query parameter is required.
  • The request specified too many id query parameters.
  • The pagination cursor is not valid.
401 Unauthorized
  • The Authorization header is required and must specify an app access token.
  • The access token is not valid.
  • The ID in the extension_id query parameter must match the client ID in the access token.
  • The ID in the Client-Id header must match the client ID in the access token.
404 Not Found
  • One or more of the transaction IDs specified using the id query parameter were not found.

Example Request

curl -X GET
'https://api.twitch.tv/helix/extensions/transactions?extension_id=1234' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
  "data": [
    {
      "id": "74c52265-e214-48a6-91b9-23b6014e8041",
      "timestamp": "2019-01-28T04:15:53.325Z",
      "broadcaster_id": "439964613",
      "broadcaster_login": "chikuseuma",
      "broadcaster_name": "chikuseuma",
      "user_id": "424596340",
      "user_login": "quotrok",
      "user_name": "quotrok",
      "product_type": "BITS_IN_EXTENSION",
      "product_data": {
        "domain": "twitch.ext.uo6dggojyb8d6soh92zknwmi5ej1q2",
        "sku": "testSku100",
        "cost": {
          "amount": 100,
          "type": "bits"
        },
        "inDevelopment": false,
        "displayName": "Test Product 100",
        "expiration": "",
        "broadcast": false
      }
    },
    {
      "id": "8d303dc6-a460-4945-9f48-59c31d6735cb",
      "timestamp": "2019-01-18T09:10:13.397Z",
      "broadcaster_id": "439964613",
      "broadcaster_login": "chikuseuma",
      "broadcaster_name": "chikuseuma",
      "user_id": "439966926",
      "user_login": "liscuit",
      "user_name": "liscuit",
      "product_type": "BITS_IN_EXTENSION",
      "product_data": {
        "domain": "twitch.ext.uo6dggojyb8d6soh92zknwmi5ej1q2",
        "sku": "testSku200",
        "cost": {
          "amount": 200,
          "type": "bits"
        },
        "inDevelopment": false,
        "displayName": "Test Product 200",
        "expiration": "",
        "broadcast": false
      }
    },
    ...
  ],
  "pagination": {
    "cursor": "cursorString"
  }
}

Get Channel Information

Gets information about one or more channels.

Authentication

Requires an app access token or user access token.

URL

GET https://api.twitch.tv/helix/channels

Request Query Parameters

Parameter Type Required? Description
broadcaster_id String Yes The ID of the broadcaster whose channel you want to get. To specify more than one ID, include this parameter for each broadcaster you want to get. For example, broadcaster_id=1234&broadcaster_id=5678. You may specify a maximum of 100 IDs. The API ignores duplicate IDs and IDs that are not found.

Response Body

Field Type Description
data Object[] A list that contains information about the specified channels. The list is empty if the specified channels weren’t found.
   broadcaster_id String An ID that uniquely identifies the broadcaster.
   broadcaster_login String The broadcaster’s login name.
   broadcaster_name String The broadcaster’s display name.
   broadcaster_language String The broadcaster’s preferred language. The value is an ISO 639-1 two-letter language code (for example, en for English). The value is set to “other” if the language is not a Twitch supported language.
   game_name String The name of the game that the broadcaster is playing or last played. The value is an empty string if the broadcaster has never played a game.
   game_id String An ID that uniquely identifies the game that the broadcaster is playing or last played. The value is an empty string if the broadcaster has never played a game.
   title String The title of the stream that the broadcaster is currently streaming or last streamed. The value is an empty string if the broadcaster has never streamed.
   delay Unsigned Integer The value of the broadcaster’s stream delay setting, in seconds. This field’s value defaults to zero unless 1) the request specifies a user access token, 2) the ID in the broadcaster_id query parameter matches the user ID in the access token, and 3) the broadcaster has partner status and they set a non-zero stream delay value.

Response Codes

HTTP Code Description
200 OK Successfully retrieved the list of channels.
400 Bad Request
  • The broadcaster_id query parameter is required.
  • The broadcaster ID is not valid.
  • The number of broadcaster_id query parameters exceeds the maximum allowed.
401 Unauthorized
  • The Authorization header is required and must specify an app access token or user access token.
  • The OAuth token is not valid.
  • The ID in the Client-Id header must match the Client ID in the OAuth token.
429 Too Many Requests
  • The application exceeded the number of calls it may make per minute. For details, see Rate Limits.
500 Internal Server Error  

Example Request

Gets information about the TwitchDev channel.

curl -X GET 'https://api.twitch.tv/helix/channels?broadcaster_id=141981764' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'

Example Response

{
  "data": [
    {
      "broadcaster_id": "141981764",
      "broadcaster_login": "twitchdev",
      "broadcaster_name": "TwitchDev",
      "broadcaster_language": "en",
      "game_id": "509670",
      "game_name": "Science & Technology",
      "title": "TwitchDev Monthly Update // May 6, 2021",
      "delay": 0
    }
  ]
}

Modify Channel Information

Updates a channel’s properties.

Authentication

Requires a user access token that includes the channel:manage:broadcast scope.

URL

PATCH https://api.twitch.tv/helix/channels

Request Query Parameters

Parameter Type Required? Description
broadcaster_id String Yes The ID of the broadcaster whose channel you want to update. This ID must match the user ID associated with the user access token.

Request Body

All fields are optional, but you must specify at least one field.

Field Type Required? Description
game_id String No The ID of the game that the user plays. The game is not updated if the ID isn’t a game ID that Twitch recognizes. To unset this field, use “0” or “” (an empty string).
broadcaster_language String No The user’s preferred language. Set the value to an ISO 639-1 two-letter language code (for example, en for English). Set to “other” if the user’s preferred language is not a Twitch supported language. The language isn’t updated if the language code isn’t a Twitch supported language.
title String No The title of the user’s stream. You may not set this field to an empty string.
delay Integer No The number of seconds you want your broadcast buffered before streaming it live. The delay helps ensure fairness during competitive play. Only users with Partner status may set this field. The maximum delay is 900 seconds (15 minutes).

Response Codes

HTTP Code Description
204 No Content Successfully updated the channel’s properties.
400 Bad Request
  • The broadcaster_id query parameter is required.
  • The request must update at least one property.
  • The title field may not contain an empty string.
  • The ID in game_id is not valid.
  • To update the delay field, the broadcaster must have partner status.
401 Unauthorized
  • The ID in broadcaster_id must match the user ID found in the OAuth token.
  • The Authorization header is required and must specify a user access token.
  • The OAuth token must include the channel:manage:broadcast scope.
  • The OAuth token is not valid.
  • The ID in the Client-Id header must match the Client ID in the OAuth token.
500 Internal server error  

Example Request

curl -X PATCH 'https://api.twitch.tv/helix/channels?broadcaster_id=41245072' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz' \
-H 'Content-Type: application/json' \
--data-raw '{"game_id":"33214", "title":"there are helicopters in the game? REASON TO PLAY FORTNITE found", "broadcaster_language":"en"}'

Get Channel Editors

Gets a list of users that are editors for the specified broadcaster.

Authentication

Requires a user access token that includes the channel:read:editors scope.

URL

GET https://api.twitch.tv/helix/channels/editors

Request Query Parameters

Parameter Type Required? Description
broadcaster_id String Yes The ID of the broadcaster that owns the channel. This ID must match the user ID in the access token.

Response Body

Field Type Description
data Object[] A list of users that are editors for the specified broadcaster. The list is empty if the broadcaster doesn’t have editors.
   user_id String An ID that uniquely identifies a user with editor permissions.
   user_name String The user’s display name.
   created_at String The date and time, in RFC3339 format, when the user became one of the broadcaster’s editors.

Response Codes

Code Description
200 OK Successfully retrieved the list of editors.
400 Bad Request
  • The broadcaster_id query parameter is required.
401 Unauthorized
  • The ID in the broadcaster_id query parameter must match the user ID found in the OAuth token.
  • The Authorization header is required and must specify a user access token.
  • The OAuth token must include the channel:read:editors scope.
  • The OAuth token is not valid.
  • The ID in the Client-Id header must match the Client ID in the OAuth token.

Example Request

Gets the list of editors for TwitchDev.

curl -X GET 'https://api.twitch.tv/helix/channels/editors?broadcaster_id=141981764' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz' \

Example Response

{
  "data": [
    {
      "user_id": "182891647",
      "user_name": "mauerbac",
      "created_at": "2019-02-15T21:19:50.380833Z"
    },
    {
      "user_id": "135093069",
      "user_name": "BlueLava",
      "created_at": "2018-03-07T16:28:29.872937Z"
    }
  ]
}

Create Custom Rewards

Creates a Custom Reward in the broadcaster’s channel. The maximum number of custom rewards per channel is 50, which includes both enabled and disabled rewards.

Authentication

Requires a user access token that includes the channel:manage:redemptions scope.

URL

POST https://api.twitch.tv/helix/channel_points/custom_rewards

Request Query Parameters

Parameter Type Required? Description
broadcaster_id String Yes The ID of the broadcaster to add the custom reward to. This ID must match the user ID found in the OAuth token.

Request Body

Field Type Required? Description
title String Yes The custom reward’s title. The title may contain a maximum of 45 characters and it must be unique amongst all of the broadcaster’s custom rewards.
cost Int64 Yes The cost of the reward, in Channel Points. The minimum is 1 point.
prompt String No The prompt shown to the viewer when they redeem the reward. Specify a prompt if is_user_input_required is true. The prompt is limited to a maximum of 200 characters.
is_enabled Boolean No A Boolean value that determines whether the reward is enabled. Viewers see only enabled rewards. The default is true.
background_color String No The background color to use for the reward. Specify the color using Hex format (for example, #9147FF).
is_user_input_required Boolean No A Boolean value that determines whether the user needs to enter information when redeeming the reward. See the prompt field. The default is false.
is_max_per_stream_enabled Boolean No A Boolean value that determines whether to limit the maximum number of redemptions allowed per live stream (see the max_per_stream field). The default is false.
max_per_stream Integer No The maximum number of redemptions allowed per live stream. Applied only if is_max_per_stream_enabled is true. The minimum value is 1.
is_max_per_user_per_stream_enabled Boolean No A Boolean value that determines whether to limit the maximum number of redemptions allowed per user per stream (see the max_per_user_per_stream field). The default is false.
max_per_user_per_stream Integer No The maximum number of redemptions allowed per user per stream. Applied only if is_max_per_user_per_stream_enabled is true. The minimum value is 1.
is_global_cooldown_enabled Boolean No A Boolean value that determines whether to apply a cooldown period between redemptions (see the global_cooldown_seconds field for the duration of the cooldown period). The default is false.
global_cooldown_seconds Integer No The cooldown period, in seconds. Applied only if the is_global_cooldown_enabled field is true. The minimum value is 1; however, the minimum value is 60 for it to be shown in the Twitch UX.
should_redemptions_skip_request_queue Boolean No A Boolean value that determines whether redemptions should be set to FULFILLED status immediately when a reward is redeemed. If false, status is set to UNFULFILLED and follows the normal request queue process. The default is false.

Response Body

Field Type Description
data Object[] A list that contains the single custom reward you created.
   broadcaster_id String The ID that uniquely identifies the broadcaster.
   broadcaster_login String The broadcaster’s login name.
   broadcaster_name String The broadcaster’s display name.
   id String The ID that uniquely identifies this custom reward.
   title String The title of the reward.
   prompt String The prompt shown to the viewer when they redeem the reward if user input is required (see the is_user_input_required field).
   cost Integer The cost of the reward in Channel Points.
   image Object A set of custom images for the reward. This field is set to null if the broadcaster didn’t upload images.
      url_1x String The URL to a small version of the image.
      url_2x String The URL to a medium version of the image.
      url_4x String The URL to a large version of the image.
   default_image Object A set of default images for the reward.
      url_1x String The URL to a small version of the image.
      url_2x String The URL to a medium version of the image.
      url_4x String The URL to a large version of the image.
   background_color String The background color to use for the reward. The color is in Hex format (for example, #00E5CB).
   is_enabled Boolean A Boolean value that determines whether the reward is enabled. Is true if enabled; otherwise, false. Disabled rewards aren’t shown to the user.
   is_user_input_required Boolean A Boolean value that determines whether the user must enter information when redeeming the reward. Is true if the reward requires user input.
   max_per_stream_setting Object The settings used to determine whether to apply a maximum to the number to the redemptions allowed per live stream.
      is_enabled Boolean A Boolean value that determines whether the reward applies a limit on the number of redemptions allowed per live stream. Is true if the reward applies a limit.
      max_per_stream Int64 The maximum number of redemptions allowed per live stream.
   max_per_user_per_stream_setting Object The settings used to determine whether to apply a maximum to the number of redemptions allowed per user per live stream.
      is_enabled Boolean A Boolean value that determines whether the reward applies a limit on the number of redemptions allowed per user per live stream. Is true if the reward applies a limit.
      max_per_user_per_stream Int64 The maximum number of redemptions allowed per user per live stream.
   global_cooldown_setting Object The settings used to determine whether to apply a cooldown period between redemptions and the length of the cooldown.
      is_enabled Boolean A Boolean value that determines whether to apply a cooldown period. Is true if a cooldown period is enabled.
      global_cooldown_seconds Int64 The cooldown period, in seconds.
   is_paused Boolean A Boolean value that determines whether the reward is currently paused. Is true if the reward is paused. Viewers can’t redeem paused rewards.
   is_in_stock Boolean A Boolean value that determines whether the reward is currently in stock. Is true if the reward is in stock. Viewers can’t redeem out of stock rewards.
   should_redemptions_skip_request_queue Boolean A Boolean value that determines whether redemptions should be set to FULFILLED status immediately when a reward is redeemed. If false, status is UNFULFILLED and follows the normal request queue process.
   redemptions_redeemed_current_stream Integer The number of redemptions redeemed during the current live stream. The number counts against the max_per_stream_setting limit. This field is null if the broadcaster’s stream isn’t live or max_per_stream_setting isn’t enabled.
   cooldown_expires_at String The timestamp of when the cooldown period expires. Is null if the reward isn’t in a cooldown state (see the global_cooldown_setting field).

Response Codes

HTTP Code Description
200 OK Successfully created the Custom Reward.
400 Bad Request
  • The request exceeds the maximum number of rewards allowed per channel.
  • The broadcaster_id query parameter is required.
  • The title field is required.
  • The title must contain a minimum of 1 character and a maximum of 45 characters.
  • The title must be unique amongst all of the broadcaster's custom rewards.
  • The cost field is required.
  • The cost field must contain a minimum of 1 point.
  • The prompt field is limited to a maximum of 200 characters.
  • If is_max_per_stream_enabled is true, the minimum value for max_per_stream is 1.
  • If is_max_per_user_per_stream_enabled is true, the minimum value for max_per_user_per_stream is 1.
  • If is_global_cooldown_enabled is true, the minimum value for global_cooldown_seconds is 1.
401 Unauthorized
  • The Authorization header is required and must specify a user access token.
  • The user access token is missing the channel:manage:redemptions scope.
  • The OAuth token is not valid.
  • The ID in the Client-Id header must match the Client ID in the OAuth token.
403 Forbidden
  • The broadcaster is not a partner or affiliate.
500 Internal Server Error  

Example Request

Creates a custom reward.

curl -X POST 'https://api.twitch.tv/helix/channel_points/custom_rewards?broadcaster_id=274637212' \
-H 'client-id: gx2pv4208cff0ig9ou7nk3riccffxt' \
-H 'Authorization: Bearer vjxv3i0l4zxru966wsnwji51tmpkj2' \
-H 'Content-Type: application/json' \
-d '{
  "title":"game analysis 1v1",
  "cost":50000
}'

Example Response

{
  "data": [
    {
      "broadcaster_name": "torpedo09",
      "broadcaster_login": "torpedo09",
      "broadcaster_id": "274637212",
      "id": "afaa7e34-6b17-49f0-a19a-d1e76eaaf673",
      "image": null,
      "background_color": "#00E5CB",
      "is_enabled": true,
      "cost": 50000,
      "title": "game analysis 1v1",
      "prompt": "",
      "is_user_input_required": false,
      "max_per_stream_setting": {
        "is_enabled": false,
        "max_per_stream": 0
      },
      "max_per_user_per_stream_setting": {
        "is_enabled": false,
        "max_per_user_per_stream": 0
      },
      "global_cooldown_setting": {
        "is_enabled": false,
        "global_cooldown_seconds": 0
      },
      "is_paused": false,
      "is_in_stock": true,
      "default_image": {
        "url_1x": "https://static-cdn.jtvnw.net/custom-reward-images/default-1.png",
        "url_2x": "https://static-cdn.jtvnw.net/custom-reward-images/default-2.png",
        "url_4x": "https://static-cdn.jtvnw.net/custom-reward-images/default-4.png"
      },
      "should_redemptions_skip_request_queue": false,
      "redemptions_redeemed_current_stream": null,
      "cooldown_expires_at": null
    }
  ]
}

Delete Custom Reward

Deletes a custom reward that the broadcaster created.

The app used to create the reward is the only app that may delete it. If the reward’s redemption status is UNFULFILLED at the time the reward is deleted, its redemption status is marked as FULFILLED.

Authentication

Requires a user access token that includes the channel:manage:redemptions scope.

URL

DELETE https://api.twitch.tv/helix/channel_points/custom_rewards

Request Query Parameters

Parameter Type Required? Description
broadcaster_id String Yes The ID of the broadcaster that created the custom reward. This ID must match the user ID found in the OAuth token.
id String Yes The ID of the custom reward to delete.

Response Codes

HTTP Code Description
204 No Content Successfully deleted the custom reward.
400 Bad Request
  • The broadcaster_id query parameter is required.
  • The id query parameter is required.
401 Unauthorized
  • The Authorization header is required and must specify a user access token.
  • The user access token must include the channel:manage:redemptions scope.
  • The OAuth token is not valid.
  • The ID in the Client-Id header must match the Client ID in the OAuth token.
403 Forbidden
  • The ID in the Client-Id header must match the client ID used to create the custom reward.
  • The broadcaster is not a partner or affiliate.
404 Not Found
  • The custom reward specified in the id query parameter was not found.
500 Internal Server Error  

Example Request

Deletes the specified custom reward.

curl -X DELETE 'https://api.twitch.tv/helix/channel_points/custom_rewards?broadcaster_id=274637212&id=b045196d-9ce7-4a27-a9b9-279ed341ab28' \
-H 'Client-Id: gx2pv4208cff0ig9ou7nk3riccffxt' \
-H 'Authorization: Bearer vjxv3i0l4zxru966wsnwji51tmpkj2'

Get Custom Reward

Gets a list of custom rewards that the specified broadcaster created.

Authentication

Requires a user access token that includes the channel:read:redemptions scope.

NOTE: A channel may offer a maximum of 50 rewards, which includes both enabled and disabled rewards.

URL

GET https://api.twitch.tv/helix/channel_points/custom_rewards

Request Query Parameters

Parameter Type Required? Description
broadcaster_id String Yes The ID of the broadcaster whose custom rewards you want to get. This ID must match the user ID found in the OAuth token.
id String No A list of IDs to filter the rewards by. To specify more than one ID, include this parameter for each reward you want to get. For example, id=1234&id=5678. You may specify a maximum of 50 IDs.

Duplicate IDs are ignored. The response contains only the IDs that were found. If none of the IDs were found, the response is 404 Not Found.
only_manageable_rewards Boolean No A Boolean value that determines whether the response contains only the custom rewards that the app may manage (the app is identified by the ID in the Client-Id header). Set to true to get only the custom rewards that the app may manage. The default is false.

Response Body

Field Type Description
data Object[] A list of custom rewards. The list is in ascending order by id. If the broadcaster hasn’t created custom rewards, the list is empty.
   broadcaster_id String The ID that uniquely identifies the broadcaster.
   broadcaster_login String The broadcaster’s login name.
   broadcaster_name String The broadcaster’s display name.
   id String The ID that uniquely identifies this custom reward.
   title String The title of the reward.
   prompt String The prompt shown to the viewer when they redeem the reward if user input is required (see the is_user_input_required field).
   cost Integer The cost of the reward in Channel Points.
   image Object A set of custom images for the reward. This field is null if the broadcaster didn’t upload images.
      url_1x String The URL to a small version of the image.
      url_2x String The URL to a medium version of the image.
      url_4x String The URL to a large version of the image.
   default_image Object A set of default images for the reward.
      url_1x String The URL to a small version of the image.
      url_2x String The URL to a medium version of the image.
      url_4x String The URL to a large version of the image.
   background_color String The background color to use for the reward. The color is in Hex format (for example, #00E5CB).
   is_enabled Boolean A Boolean value that determines whether the reward is enabled. Is true if enabled; otherwise, false. Disabled rewards aren’t shown to the user.
   is_user_input_required Boolean A Boolean value that determines whether the user must enter information when redeeming the reward. Is true if the user is prompted.
   max_per_stream_setting Object The settings used to determine whether to apply a maximum to the number of redemptions allowed per live stream.
      is_enabled Boolean A Boolean value that determines whether the reward applies a limit on the number of redemptions allowed per live stream. Is true if the reward applies a limit.
      max_per_stream Int64 The maximum number of redemptions allowed per live stream.
   max_per_user_per_stream_setting Object The settings used to determine whether to apply a maximum to the number of redemptions allowed per user per live stream.
      is_enabled Boolean A Boolean value that determines whether the reward applies a limit on the number of redemptions allowed per user per live stream. Is true if the reward applies a limit.
      max_per_user_per_stream Int64 The maximum number of redemptions allowed per user per live stream.
   global_cooldown_setting Object The settings used to determine whether to apply a cooldown period between redemptions and the length of the cooldown.
      is_enabled Boolean A Boolean value that determines whether to apply a cooldown period. Is true if a cooldown period is enabled.
      global_cooldown_seconds Int64 The cooldown period, in seconds.
   is_paused Boolean A Boolean value that determines whether the reward is currently paused. Is true if the reward is paused. Viewers can’t redeem paused rewards.
   is_in_stock Boolean A Boolean value that determines whether the reward is currently in stock. Is true if the reward is in stock. Viewers can’t redeem out of stock rewards.
   should_redemptions_skip_request_queue Boolean A Boolean value that determines whether redemptions should be set to FULFILLED status immediately when a reward is redeemed. If false, status is set to UNFULFILLED and follows the normal request queue process.
   redemptions_redeemed_current_stream Integer The number of redemptions redeemed during the current live stream. The number counts against the max_per_stream_setting limit. This field is null if the broadcaster’s stream isn’t live or max_per_stream_setting isn’t enabled.
   cooldown_expires_at String The timestamp of when the cooldown period expires. Is null if the reward isn’t in a cooldown state. See the global_cooldown_setting field.

Response Codes

HTTP Code Meaning
200 OK Successfully retrieved the broadcaster’s list of the Custom Rewards.
400 Bad Request
  • The broadcaster_id query parameter is required.
  • The request exceeds the maximum number of id query parameters that you may specify.
401 Unauthorized
  • The Authorization header must specify a user access token.
  • The user access token must include the channel:read:redemptions scope.
  • The OAuth token is not valid.
  • The ID in the Client-Id header must match the Client ID in the OAuth token.
403 Forbidden
  • The broadcaster is not a partner or affiliate.
404 Not Found
  • All of the custom rewards specified using the id query parameter were not found.
500 Internal Server Error  

Example Request

Gets the broadcaster’s list of custom rewards.

curl -X GET 'https://api.twitch.tv/helix/channel_points/custom_rewards?broadcaster_id=274637212'
-H 'Client-Id: gx2pv4208cff0ig9ou7nk3riccffxt' \
-H 'Authorization: Bearer vjxv3i0l4zxru966wsnwji51tmpkj2'

Example Response

{
  "data": [
    {
      "broadcaster_name": "torpedo09",
      "broadcaster_login": "torpedo09",
      "broadcaster_id": "274637212",
      "id": "92af127c-7326-4483-a52b-b0da0be61c01",
      "image": null,
      "background_color": "#00E5CB",
      "is_enabled": true,
      "cost": 50000,
      "title": "game analysis",
      "prompt": "",
      "is_user_input_required": false,
      "max_per_stream_setting": {
        "is_enabled": false,
        "max_per_stream": 0
      },
      "max_per_user_per_stream_setting": {
        "is_enabled": false,
        "max_per_user_per_stream": 0
      },
      "global_cooldown_setting": {
        "is_enabled": false,
        "global_cooldown_seconds": 0
      },
      "is_paused": false,
      "is_in_stock": true,
      "default_image": {
        "url_1x": "https://static-cdn.jtvnw.net/custom-reward-images/default-1.png",
        "url_2x": "https://static-cdn.jtvnw.net/custom-reward-images/default-2.png",
        "url_4x": "https://static-cdn.jtvnw.net/custom-reward-images/default-4.png"
      },
      "should_redemptions_skip_request_queue": false,
      "redemptions_redeemed_current_stream": null,
      "cooldown_expires_at": null
    }
  ]
}

Example Request

Gets the list of custom rewards that the calling Client ID can manage.

curl -X GET 'https://api.twitch.tv/helix/channel_points/custom_rewards?broadcaster_id=274637212&only_manageable_rewards=true'
-H 'Client-Id: gx2pv4208cff0ig9ou7nk3riccffxt' \
-H 'Authorization: Bearer vjxv3i0l4zxru966wsnwji51tmpkj2'​​​​​​​

Example Response

{
  "data": [
    {
      "broadcaster_name": "torpedo09",
      "broadcaster_id": "274637212",
      "id": "92af127c-7326-4483-a52b-b0da0be61c01",
      "image": null,
      "background_color": "#00E5CB",
      "is_enabled": true,
      "cost": 50000,
      "title": "game analysis",
      "prompt": "",
      "is_user_input_required": false,
      "max_per_stream_setting": {
        "is_enabled": false,
        "max_per_stream": 0
      },
      "max_per_user_per_stream_setting": {
        "is_enabled": false,
        "max_per_user_per_stream": 0
      },
      "global_cooldown_setting": {
        "is_enabled": false,
        "global_cooldown_seconds": 0
      },
      "is_paused": false,
      "is_in_stock": true,
      "default_image": {
        "url_1x": "https://static-cdn.jtvnw.net/custom-reward-images/default-1.png",
        "url_2x": "https://static-cdn.jtvnw.net/custom-reward-images/default-2.png",
        "url_4x": "https://static-cdn.jtvnw.net/custom-reward-images/default-4.png"
      },
      "should_redemptions_skip_request_queue": false,
      "redemptions_redeemed_current_stream": null,
      "cooldown_expires_at": null
    }
  ]
}

Example Request

Gets the specified custom reward.

curl -X GET 'https://api.twitch.tv/helix/channel_points/custom_rewards?broadcaster_id=274637212&id=92af127c-7326-4483-a52b-b0da0be61c01'
-H 'Client-Id: gx2pv4208cff0ig9ou7nk3riccffxt' \
-H 'Authorization: Bearer vjxv3i0l4zxru966wsnwji51tmpkj2'​​​​​​​​​​​​​​

Example Response

{
  "data": [
    {
      "broadcaster_name": "torpedo09",
      "broadcaster_id": "274637212",
      "id": "92af127c-7326-4483-a52b-b0da0be61c01",
      "image": null,
      "background_color": "#00E5CB",
      "is_enabled": true,
      "cost": 50000,
      "title": "game analysis",
      "prompt": "",
      "is_user_input_required": false,
      "max_per_stream_setting": {
        "is_enabled": false,
        "max_per_stream": 0
      },
      "max_per_user_per_stream_setting": {
        "is_enabled": false,
        "max_per_user_per_stream": 0
      },
      "global_cooldown_setting": {
        "is_enabled": false,
        "global_cooldown_seconds": 0
      },
      "is_paused": false,
      "is_in_stock": true,
      "default_image": {
        "url_1x": "https://static-cdn.jtvnw.net/custom-reward-images/default-1.png",
        "url_2x": "https://static-cdn.jtvnw.net/custom-reward-images/default-2.png",
        "url_4x": "https://static-cdn.jtvnw.net/custom-reward-images/default-4.png"
      },
      "should_redemptions_skip_request_queue": false,
      "redemptions_redeemed_current_stream": null,
      "cooldown_expires_at": null
    }
  ]
}

Get Custom Reward Redemption

Gets a list of redemptions for the specified custom reward. The app used to create the reward is the only app that may get the redemptions.

Authentication

Requires a user access token that includes the channel:read:redemptions scope.

URL

GET https://api.twitch.tv/helix/channel_points/custom_rewards/redemptions

Request Query Parameters

Parameter Type Required? Description
broadcaster_id String Yes The ID of the broadcaster that owns the custom reward. This ID must match the user ID found in the user OAuth token.
reward_id String Yes The ID that identifies the custom reward whose redemptions you want to get.
status String Yes The status of the redemptions to return. The possible case-sensitive values are:
  • CANCELED
  • FULFILLED
  • UNFULFILLED
NOTE: This field is required only if you don’t specify the id query parameter.

NOTE: Canceled and fulfilled redemptions are returned for only a few days after they’re canceled or fulfilled.
id String No A list of IDs to filter the redemptions by. To specify more than one ID, include this parameter for each redemption you want to get. For example, id=1234&id=5678. You may specify a maximum of 50 IDs.

Duplicate IDs are ignored. The response contains only the IDs that were found. If none of the IDs were found, the response is 404 Not Found.
sort String No The order to sort redemptions by. The possible case-sensitive values are:
  • OLDEST
  • NEWEST
The default is OLDEST.
after String No The cursor used to get the next page of results. The Pagination object in the response contains the cursor’s value. Read more
first Integer No The maximum number of redemptions to return per page in the response. The minimum page size is 1 redemption per page and the maximum is 50. The default is 20.

Response Body

Field Type Description
data Object[] The list of redemptions for the specified reward. The list is empty if there are no redemptions that match the redemption criteria.
   broadcaster_id String The ID that uniquely identifies the broadcaster.
   broadcaster_login String The broadcaster’s login name.
   broadcaster_name string The broadcaster’s display name.
   id String The ID that uniquely identifies this redemption.
   user_login String The user’s login name.
   user_id String The ID that uniquely identifies the user that redeemed the reward.
   user_name String The user’s display name.
   user_input String The text the user entered at the prompt when they redeemed the reward; otherwise, an empty string if user input was not required.
   status String The state of the redemption. Possible values are:
  • CANCELED
  • FULFILLED
  • UNFULFILLED
   redeemed_at String The date and time of when the reward was redeemed, in RFC3339 format.
   reward Object The reward that the user redeemed.
      id String The ID that uniquely identifies the redeemed reward.
      title String The reward’s title.
      prompt String The prompt displayed to the viewer if user input is required.
      cost Int64 The reward’s cost, in Channel Points.

Response Codes

HTTP Code Description
200 Ok Successfully retrieved the list of redeemed custom rewards.
400 Bad Request
  • The broadcaster_id query parameter is required.
  • The reward_id query parameter is required.
  • The status query parameter is required if you didn't specify the id query parameter.
  • The value in the status query parameter is not valid.
  • The value in the sort query parameter is not valid.
401 Unauthorized
  • The Authorization header is required and must specify a user access token.
  • The user access token must include the channel:read:redemptions scope.
  • The OAuth token is not valid.
  • The ID in the Client-Id header must match the Client ID in the OAuth token.
403 Forbidden
  • The ID in the Client-Id header must match the client ID used to create the custom reward.
  • The broadcaster is not a partner or affiliate.
404 Not Found
  • All of the redemptions specified using the id query parameter were not found.
500 Internal Server Error  

Example Request

Gets the list of redemptions that were canceled for the specified reward.

curl -X GET 'https://api.twitch.tv/helix/channel_points/custom_rewards/redemptions?broadcaster_id=274637212&reward_id=92af127c-7326-4483-a52b-b0da0be61c01&status=CANCELED' \
-H 'Client-Id: gx2pv4208cff0ig9ou7nk3riccffxt' \
-H 'Authorization: Bearer vjxv3i0l4zxru966wsnwji51tmpkj2'

Example Response

{
  "data": [
    {
      "broadcaster_name": "torpedo09",
      "broadcaster_login": "torpedo09",
      "broadcaster_id": "274637212",
      "id": "17fa2df1-ad76-4804-bfa5-a40ef63efe63",
      "user_login": "torpedo09",
      "user_id": "274637212",
      "user_name": "torpedo09",
      "user_input": "",
      "status": "CANCELED",
      "redeemed_at": "2020-07-01T18:37:32Z",
      "reward": {
        "id": "92af127c-7326-4483-a52b-b0da0be61c01",
        "title": "game analysis",
        "prompt": "",
        "cost": 50000
      }
    }
  ],
  "pagination": {
      "cursor": "eyJiIjpudWxsLCJhIjp7IkN1cnNvciI6Ik1UZG1ZVEprWmpFdFlXUTNOaTAwT0RBMExXSm1ZVFV0WVRRd1pXWTJNMlZtWlRZelgxOHlNREl3TFRBM0xUQXhWREU0T2pNM09qTXlMakl6TXpFeU56RTFOMW89In19"
  }
}

Example Request

Gets redemptions by ID.

curl -X GET 'https://api.twitch.tv/helix/channel_points/custom_rewards/redemptions?broadcaster_id=274637212&reward_id=92af127c-7326-4483-a52b-b0da0be61c01&id=17fa2df1-ad76-4804-bfa5-a40ef63efe63' \
-H 'Client-Id: gx2pv4208cff0ig9ou7nk3riccffxt' \
-H 'Authorization: Bearer vjxv3i0l4zxru966wsnwji51tmpkj2'

Example Response

{
  "data": [
    {
      "broadcaster_name": "torpedo09",
      "broadcaster_login": "torpedo09",
      "broadcaster_id": "274637212",
      "id": "17fa2df1-ad76-4804-bfa5-a40ef63efe63",
      "user_id": "274637212",
      "user_name": "torpedo09",
      "user_input": "",
      "status": "CANCELED",
      "redeemed_at": "2020-07-01T18:37:32Z",
      "reward": {
        "id": "92af127c-7326-4483-a52b-b0da0be61c01",
        "title": "game analysis",
        "prompt": "",
        "cost": 50000
      }
    }
  ]
}

Update Custom Reward

Updates a custom reward. The app used to create the reward is the only app that may update the reward.

Authentication

Requires a user access token that includes the channel:manage:redemptions scope.

URL

PATCH https://api.twitch.tv/helix/channel_points/custom_rewards

Request Query Parameters

Parameter Type Required? Description
broadcaster_id String Yes The ID of the broadcaster that’s updating the reward. This ID must match the user ID found in the OAuth token.
id String Yes The ID of the reward to update.

Request Body

The body of the request should contain only the fields you’re updating.

Field Type Required? Description
title String No The reward’s title. The title may contain a maximum of 45 characters and it must be unique amongst all of the broadcaster’s custom rewards.
prompt String No The prompt shown to the viewer when they redeem the reward. Specify a prompt if is_user_input_required is true. The prompt is limited to a maximum of 200 characters.
cost Int64 No The cost of the reward, in channel points. The minimum is 1 point.
background_color String No The background color to use for the reward. Specify the color using Hex format (for example, #00E5CB).
is_enabled Boolean No A Boolean value that indicates whether the reward is enabled. Set to true to enable the reward. Viewers see only enabled rewards.
is_user_input_required Boolean No A Boolean value that determines whether users must enter information to redeem the reward. Set to true if user input is required. See the prompt field.
is_max_per_stream_enabled Boolean No A Boolean value that determines whether to limit the maximum number of redemptions allowed per live stream (see the max_per_stream field). Set to true to limit redemptions.
max_per_stream Int64 No The maximum number of redemptions allowed per live stream. Applied only if is_max_per_stream_enabled is true. The minimum value is 1.
is_max_per_user_per_stream_enabled Boolean No A Boolean value that determines whether to limit the maximum number of redemptions allowed per user per stream (see max_per_user_per_stream). The minimum value is 1. Set to true to limit redemptions.
max_per_user_per_stream Int64 No The maximum number of redemptions allowed per user per stream. Applied only if is_max_per_user_per_stream_enabled is true.
is_global_cooldown_enabled Boolean No A Boolean value that determines whether to apply a cooldown period between redemptions. Set to true to apply a cooldown period. For the duration of the cooldown period, see global_cooldown_seconds.
global_cooldown_seconds Int64 No The cooldown period, in seconds. Applied only if is_global_cooldown_enabled is true. The minimum value is 1; however, for it to be shown in the Twitch UX, the minimum value is 60.
is_paused Boolean No A Boolean value that determines whether to pause the reward. Set to true to pause the reward. Viewers can’t redeem paused rewards..
should_redemptions_skip_request_queue Boolean No A Boolean value that determines whether redemptions should be set to FULFILLED status immediately when a reward is redeemed. If false, status is set to UNFULFILLED and follows the normal request queue process.

Response Body

Parameter Type Description
data Object[] The list contains the single reward that you updated.
   broadcaster_id String The ID that uniquely identifies the broadcaster.
   broadcaster_login String The broadcaster’s login name.
   broadcaster_name String The broadcaster’s display name.
   id String The ID that uniquely identifies this custom reward.
   title String The title of the reward.
   prompt String The prompt shown to the viewer when they redeem the reward if user input is required. See the is_user_input_required field.
   cost Int64 The cost of the reward in Channel Points.
   image Object A set of custom images for the reward. This field is null if the broadcaster didn’t upload images.
      url_1x String The URL to a small version of the image.
      url_2x String The URL to a medium version of the image.
      url_4x String The URL to a large version of the image.
   default_image Object A set of default images for the reward.
      url_1x String The URL to a small version of the image.
      url_2x String The URL to a medium version of the image.
      url_4x String The URL to a large version of the image.
   background_color String The background color to use for the reward. The color is in Hex format (for example, #00E5CB).
   is_enabled Boolean A Boolean value that determines whether the reward is enabled. Is true if enabled; otherwise, false. Disabled rewards aren’t shown to the user.
   is_user_input_required Boolean A Boolean value that determines whether the user must enter information when they redeem the reward. Is true if the user is prompted.
   max_per_stream_setting Object The settings used to determine whether to apply a maximum to the number of redemptions allowed per live stream.
      is_enabled Boolean A Boolean value that determines whether the reward applies a limit on the number of redemptions allowed per live stream. Is true if the reward applies a limit.
      max_per_stream Int64 The maximum number of redemptions allowed per live stream.
   max_per_user_per_stream_setting Object The settings used to determine whether to apply a maximum to the number of redemptions allowed per user per live stream.
      is_enabled Boolean A Boolean value that determines whether the reward applies a limit on the number of redemptions allowed per user per live stream. Is true if the reward applies a limit.
      max_per_user_per_stream Int64 The maximum number of redemptions allowed per user per live stream.
   global_cooldown_setting Object The settings used to determine whether to apply a cooldown period between redemptions and the length of the cooldown.
      is_enabled Boolean A Boolean value that determines whether to apply a cooldown period. Is true if a cooldown period is enabled.
     global_cooldown_seconds Int64 The cooldown period, in seconds.
   is_paused Boolean A Boolean value that determines whether the reward is currently paused. Is true if the reward is paused. Viewers can’t redeem paused rewards.
   is_in_stock Boolean A Boolean value that determines whether the reward is currently in stock. Is true if the reward is in stock. Viewers can’t redeem out of stock rewards.
   should_redemptions_skip_request_queue Boolean A Boolean value that determines whether redemptions should be set to FULFILLED status immediately when a reward is redeemed. If false, status is set to UNFULFILLED and follows the normal request queue process.
   redemptions_redeemed_current_stream Integer The number of redemptions redeemed during the current live stream. The number counts against the max_per_stream_setting limit. This field is null if the broadcaster’s stream isn’t live or max_per_stream_setting isn’t enabled.
   cooldown_expires_at String The timestamp of when the cooldown period expires. Is null if the reward isn’t in a cooldown state. See the global_cooldown_setting field.

Response Codes

HTTP Code Description
200 OK Successfully updated the Custom Reward.
400 Bad Request
  • The broadcaster_id query parameter is required.
  • The id query parameter is required.
  • The title must contain a minimum of 1 character and a maximum of 45 characters.
  • The title must be unique amongst all of the broadcaster's custom rewards.
  • The cost field must contain a minimum of 1 point.
  • The prompt field is limited to a maximum of 200 characters.
  • If is_max_per_stream_enabled is true, the minimum value for max_per_stream is 1.
  • If is_max_per_user_per_stream_enabled is true, the minimum value for max_per_user_per_stream is 1.
  • If is_global_cooldown_enabled is true, the minimum value for global_cooldown_seconds is 1 and the maximum is 604800.
401 Unauthorized
  • The Authorization header is required and must specify a user access token.
  • The user access token must include the channel:manage:redemptions scope.
  • The OAuth token is not valide.
  • The ID in the Client-Id header must match the Client ID in the OAuth token.
403 Forbidden
  • The ID in the Client-Id header must match the client ID used to create the custom reward.
  • The broadcaster is not a partner or affiliate.
404 Not Found
  • The custom reward specified in the id query parameter was not found.
500 Internal Server Error  

Example Request

Disables the specified custom reward.

curl -X PATCH 'https://api.twitch.tv/helix/channel_points/custom_rewards?broadcaster_id=274637212&id=92af127c-7326-4483-a52b-b0da0be61c01' \
-H 'client-id: gx2pv4208cff0ig9ou7nk3riccffxt' \
-H 'Authorization: Bearer vjxv3i0l4zxru966wsnwji51tmpkj2' \
-H 'Content-Type: application/json' \
-d '{
  "is_enabled": false
 }'

Example Response

{
  "data": [
    {
      "broadcaster_name": "torpedo09",
      "broadcaster_login": "torpedo09",
      "broadcaster_id": "274637212",
      "id": "92af127c-7326-4483-a52b-b0da0be61c01",
      "image": null,
      "background_color": "#00E5CB",
      "is_enabled": false,
      "cost": 30000,
      "title": "game analysis 2v2",
      "prompt": "",
      "is_user_input_required": false,
      "max_per_stream_setting": {
        "is_enabled": true,
        "max_per_stream": 60
      },
      "max_per_user_per_stream_setting": {
        "is_enabled": false,
        "max_per_user_per_stream": 0
      },
      "global_cooldown_setting": {
        "is_enabled": false,
        "global_cooldown_seconds": 0
      },
      "is_paused": false,
      "is_in_stock": false,
      "default_image": {
        "url_1x": "https://static-cdn.jtvnw.net/custom-reward-images/default-1.png",
        "url_2x": "https://static-cdn.jtvnw.net/custom-reward-images/default-2.png",
        "url_4x": "https://static-cdn.jtvnw.net/custom-reward-images/default-4.png"
      },
      "should_redemptions_skip_request_queue": true,
      "redemptions_redeemed_current_stream": 60,
      "cooldown_expires_at": null
    }
  ]
}

Example Request

Updates the reward’s title.

curl -X PATCH 'https://api.twitch.tv/helix/channel_points/custom_rewards?broadcaster_id=274637212&id=92af127c-7326-4483-a52b-b0da0be61c01' \
-H 'client-id: gx2pv4208cff0ig9ou7nk3riccffxt' \
-H 'Authorization: Bearer vjxv3i0l4zxru966wsnwji51tmpkj2' \
-H 'Content-Type: application/json' \
-d '{
  "title": "game analysis 2v2"
 }'

Example Response

{
  "data": [
    {
      "broadcaster_name": "torpedo09",
      "broadcaster_login": "torpedo09",
      "broadcaster_id": "274637212",
      "id": "92af127c-7326-4483-a52b-b0da0be61c01",
      "image": null,
      "background_color": "",
      "is_enabled": false,
      "cost": 30000,
      "title": "game analysis 2v2",
      "prompt": "",
      "is_user_input_required": false,
      "max_per_stream_setting": {
        "is_enabled": true,
        "max_per_stream": 60
      },
      "max_per_user_per_stream_setting": {
        "is_enabled": false,
        "max_per_user_per_stream": 0
      },
      "global_cooldown_setting": {
        "is_enabled": false,
        "global_cooldown_seconds": 0
      },
      "is_paused": false,
      "is_in_stock": true,
      "default_image": {
        "url_1x": "https://static-cdn.jtvnw.net/custom-reward-images/default-1.png",
        "url_2x": "https://static-cdn.jtvnw.net/custom-reward-images/default-2.png",
        "url_4x": "https://static-cdn.jtvnw.net/custom-reward-images/default-4.png"
      },
      "should_redemptions_skip_request_queue": true,
      "redemptions_redeemed_current_stream": 60,
      "cooldown_expires_at": null
    }
  ]
}

Update Redemption Status

Updates a redemption’s status. You may update a redemption only if its status is UNFULFILLED. The app used to create the reward is the only app that may update the redemption.

Authentication

Requires a user access token that includes the channel:manage:redemptions scope.

URL

PATCH https://api.twitch.tv/helix/channel_points/custom_rewards/redemptions

Request Query Parameters

Parameter Type Required? Description
id String Yes A list of IDs that identify the redemptions to update. To specify more than one ID, include this parameter for each redemption you want to update. For example, id=1234&id=5678. You may specify a maximum of 50 IDs.
broadcaster_id String Yes The ID of the broadcaster that’s updating the redemption. This ID must match the user ID associated with the user OAuth token.
reward_id String Yes The ID that identifies the reward that’s been redeemed.

Request Body

Field Type Required? Description
status String Yes The status to set the redemption to. Possible values are:
  • CANCELED
  • FULFILLED
Setting the status to CANCELED refunds the user’s channel points.

Response Body

Field Type Description
data Object[] The list contains the single redemption that you updated.
   broadcaster_id String The ID that uniquely identifies the broadcaster.
   broadcaster_login String The broadcaster’s login name.
   broadcaster_name String The broadcaster’s display name.
   id String The ID that uniquely identifies this redemption..
   user_id String The ID of the user that redeemed the reward.
   user_name String The user’s display name.
   user_login String The user’s login name.
   reward Object An object that describes the reward that the user redeemed.
      id String The ID that uniquely identifies the reward.
      title String The reward’s title.
      prompt String The prompt displayed to the viewer if user input is required.
      cost Int64 The reward’s cost, in Channel Points.
   user_input String The text that the user entered at the prompt when they redeemed the reward; otherwise, an empty string if user input was not required.
   status String The state of the redemption. Possible values are:
  • CANCELED
  • FULFILLED
  • UNFULFILLED
   redeemed_at String The date and time of when the reward was redeemed, in RFC3339 format.

Response Codes

HTTP Code Description
200 OK Successfully updated the redemption’s status.
400 Bad Request
  • The broadcaster_id query parameter is required.
  • The reward_id query parameter is required.
  • The id query parameter is required.
  • The value in the status query parameter is not valid.
401 Unauthorized
  • The Authorization header is required and must specify a user access token.
  • The user access token must include the channel:manage:redemptions scope.
  • The OAuth token is not valid.
  • The ID in the Client-Id header must match the Client ID in the OAuth token.
403 Forbidden
  • The ID in the Client-Id header must match the client ID used to create the custom reward.
  • The broadcaster is not a partner or affiliate.
404 Not Found
  • The custom reward specified in the reward_id query parameter was not found.
  • The redemptions specified using the id query parameter were not found or their statuses weren't marked as UNFULFILLED.
500 Internal Server Error  

Example Request

Updates a redemption’s status.

curl --X PATCH 'https://api.twitch.tv/helix/channel_points/custom_rewards/redemptions?broadcaster_id=274637212&reward_id=92af127c-7326-4483-a52b-b0da0be61c01&id=17fa2df1-ad76-4804-bfa5-a40ef63efe63' \
-H 'client-id: gx2pv4208cff0ig9ou7nk3riccffxt' \
-H 'Authorization: Bearer vjxv3i0l4zxru966wsnwji51tmpkj2' \
-H 'Content-Type: application/json' \
-d '{
  "status": "CANCELED"
}'

Example Response

{
  "data": [
    {
      "broadcaster_name": "torpedo09",
      "broadcaster_login": "torpedo09",
      "broadcaster_id": "274637212",
      "id": "17fa2df1-ad76-4804-bfa5-a40ef63efe63",
      "user_id": "274637212",
      "user_name": "torpedo09",
      "user_login": "torpedo09",
      "user_input": "",
      "status": "CANCELED",
      "redeemed_at": "2020-07-01T18:37:32Z",
      "reward": {
        "id": "92af127c-7326-4483-a52b-b0da0be61c01",
        "title": "game analysis",
        "prompt": "",
        "cost": 50000
      }
    }
  ]
}

Get Charity Campaign

BETA Gets information about the charity campaign that a broadcaster is running. For example, the campaign’s fundraising goal and the current amount of donations.

To receive events when progress is made towards the campaign’s goal or the broadcaster changes the fundraising goal, subscribe to the channel.charity_campaign.progress subscription type.

Authorization

Requires a user access token that includes the channel:read:charity scope.

URL

GET https://api.twitch.tv/helix/charity/campaigns

Request Query Parameters

Parameter Type Required? Description
broadcaster_id String Yes The ID of the broadcaster that’s currently running a charity campaign. This ID must match the user ID in the access token.

Response Body

Field Type Description
data Object[] A list that contains the charity campaign that the broadcaster is currently running. The list is empty if the broadcaster is not running a charity campaign; the campaign information is not available after the campaign ends.
   id String An ID that uniquely identifies the charity campaign.
   broadcaster_id String An ID that uniquely identifies the broadcaster that’s running the campaign.
   broadcaster_login String The broadcaster’s login name.
   broadcaster_name String The broadcaster’s display name.
   charity_name String The charity’s name.
   charity_description String A description of the charity.
   charity_logo String A URL to an image of the charity’s logo. The image’s type is PNG and its size is 100px X 100px.
   charity_website String A URL to the charity’s website.
   current_amount Object The current amount of donations that the campaign has received.
      value Integer The monetary amount. The amount is specified in the currency’s minor unit. For example, the minor units for USD is cents, so if the amount is $5.50 USD, value is set to 550.
      decimal_places Integer The number of decimal places used by the currency. For example, USD uses two decimal places. Use this number to translate value from minor units to major units by using the formula:

value / 10^decimal_places
      currency String The ISO-4217 three-letter currency code that identifies the type of currency in value.
   target_amount Object The campaign’s fundraising goal. This field is null if the broadcaster has not defined a fundraising goal.
      value Integer The monetary amount. The amount is specified in the currency’s minor unit. For example, the minor units for USD is cents, so if the amount is $5.50 USD, value is set to 550.
      decimal_places Integer The number of decimal places used by the currency. For example, USD uses two decimal places. Use this number to translate value from minor units to major units by using the formula:

value / 10^decimal_places
      currency String The ISO-4217 three-letter currency code that identifies the type of currency in value.

Response Codes

Code Description
200 OK Successfully retrieved information about the broadcaster’s active charity campaign.
400 Bad Request
  • The broadcaster_id query parameter is required.
  • The broadcaster_id query parameter is not valid.
401 Unauthorized
  • The ID in the broadcaster_id query parameter must match the user ID in the access token.
  • The Authorization header is required and must contain a user access token.
  • The user access token must include the channel:read:charity scope.
  • The access token is not valid.
  • The client ID specified in the Client-Id header must match the client ID specified in the access token.
403 Forbidden
  • The broadcaster is not a partner or affiliate.

Example Request

Gets the broadcaster’s active charity campaign.

curl -X GET 'https://api.twitch.tv/helix/charity/campaigns?broadcaster_id=123456' \
-H 'Authorization: Bearer kpvy3cjboyptmiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfn0nyan9c87zr6t'

Example Response


{
  "data": [
    {
      "id": "123-abc-456-def",
      "broadcaster_id": "123456",
      "broadcaster_name": "SunnySideUp",
      "broadcaster_login": "sunnysideup",
      "charity_name": "Example name",
      "charity_description": "Example description",
      "charity_logo": "https://abc.cloudfront.net/ppgf/1000/100.png",
      "charity_website": "https://www.example.com",
      "current_amount": {
        "value": 86000,
        "decimal_places": 2,
        "currency": "USD"
      },
      "target_amount": {
        "value": 1500000,
        "decimal_places": 2,
        "currency": "USD"
      }
    }
  ]
}

Get Charity Campaign Donations

BETA Gets the list of donations that users have made to the broadcaster’s active charity campaign.

To receive events as donations occur, subscribe to the channel.charity_campaign.donate subscription type.

Authorization

Requires a user access token that includes the channel:read:charity scope.

URL

GET https://api.twitch.tv/helix/charity/donations

Request Query Parameters

Parameter Type Required? Description
broadcaster_id String Yes The ID of the broadcaster that’s currently running a charity campaign. This ID must match the user ID in the access token.
first Integer No The maximum number of items to return per page in the response. The minimum page size is 1 item per page and the maximum is 100. The default is 20.
after String No The cursor used to get the next page of results. The Pagination object in the response contains the cursor’s value. Read More

Response Body

Field Type Description
data Object[] A list that contains the donations that users have made to the broadcaster’s charity campaign. The list is empty if the broadcaster is not currently running a charity campaign; the donation information is not available after the campaign ends.
   campaign_id String An ID that identifies the charity campaign that the donation applies to.
   user_id String An ID that identifies a user that donated money to the campaign.
   user_login String The user’s login name.
   user_name String The user’s display name.
   amount Object An object that contains the amount of money that the user donated.
      value Integer The monetary amount. The amount is specified in the currency’s minor unit. For example, the minor units for USD is cents, so if the amount is $5.50 USD, value is set to 550.
      decimal_places Integer The number of decimal places used by the currency. For example, USD uses two decimal places. Use this number to translate value from minor units to major units by using the formula:

value / 10^decimal_places
      currency String The ISO-4217 three-letter currency code that identifies the type of currency in value.
pagination Object An object that contains the information used to page through the list of results. The object is empty if there are no more pages left to page through. Read More
   cursor String The cursor used to get the next page of results. Use the cursor to set the request’s after query parameter.

Response Codes

Code Description
200 OK Successfully retrieved the list of donations that users contributed to the broadcaster’s charity campaign.
400 Bad Request
  • The broadcaster_id query parameter is required.
  • The broadcaster_id query parameter is not valid.
401 Unauthorized
  • The ID in the broadcaster_id query parameter must match the user ID in the access token.
  • The Authorization header is required and must contain a user access token.
  • The user access token must include the channel:read:charity scope.
  • The access token is not valid.
  • The client ID specified in the Client-Id header must match the client ID specified in the access token.
403 Forbidden
  • The broadcaster is not a partner or affiliate.

Example Request

Gets the broadcaster’s active charity campaign.

curl -X GET 'https://api.twitch.tv/helix/charity/donations?broadcaster_id=123456' \
-H 'Authorization: Bearer kpvy3cjboyptmiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfn0nyan9c87zr6t'

Example Response


{
  "data": [
    {
      "campaign_id": "123-abc-456-def",
      "user_id": "5678",
      "user_login": "cool_user",
      "user_name": "Cool_User",
      "amount": {
        "value": 500,
        "decimal_places": 2,
        "currency": "USD"
      }
    },
    {
      "campaign_id": "123-abc-456-def",
      "user_id": "8765",
      "user_login": "cool_user2",
      "user_name": "Cool_User2",
      "amount": {
        "value": 10000,
        "decimal_places": 2,
        "currency": "USD"
      }
    },
    . . .
  ],
  "pagination" : {
      "cursor" : "eyJiIjpudWxsLCJhIjp7Ik9mZnNldCI6NX19"
  }
}

Get Chatters

Gets the list of users that are connected to the broadcaster’s chat session.

NOTE: There is a delay between when users join and leave a chat and when the list is updated accordingly.

To determine whether a user is a moderator or VIP, use the Get Moderators and Get VIPs endpoints. You can check the roles of up to 100 users.

Authorization

Requires a user access token that includes the moderator:read:chatters scope.

URL

GET https://api.twitch.tv/helix/chat/chatters

Request Query Parameters

Parameter Type Required? Description
broadcaster_id String Yes The ID of the broadcaster whose list of chatters you want to get.
moderator_id String Yes The ID of the broadcaster or one of the broadcaster’s moderators. This ID must match the user ID in the user access token.
first Integer No The maximum number of items to return per page in the response. The minimum page size is 1 item per page and the maximum is 1,000. The default is 100.
after String No The cursor used to get the next page of results. The Pagination object in the response contains the cursor’s value. Read More

Response Body

Field Type Description
data Object[] The list of users that are connected to the broadcaster’s chat room. The list is empty if no users are connected to the chat room.
   user_id String The ID of a user that’s connected to the broadcaster’s chat room.
   user_login String The user’s login name.
   user_name String The user’s display name.
pagination Object Contains the information used to page through the list of results. The object is empty if there are no more pages left to page through. Read More
   cursor String The cursor used to get the next page of results. Use the cursor to set the request’s after query parameter.
total Integer The total number of users that are connected to the broadcaster’s chat room. As you page through the list, the number of users may change as users join and leave the chat room.

Response Codes

Code Description
200 OK Successfully retrieved the broadcaster’s list of chatters.
400 Bad Request
  • The broadcaster_id query parameter is required.
  • The ID in the broadcaster_id query parameter is not valid.
  • The moderator_id query parameter is required.
  • The ID in the moderator_id query parameter is not valid.
401 Unauthorized
  • The ID in the moderator_id query parameter must match the user ID in the access token.
  • The Authorization header is required and must contain a user access token.
  • The user access token must include the moderator:read:chatters scope.
  • The access token is not valid.
  • The client ID specified in the Client-Id header does not match the client ID specified in the access token.
403 Forbidden
  • The user in the moderator_id query parameter is not one of the broadcaster's moderators.

Example Request

Gets the list of users that are connected to the specified broadcaster’s chat room.

curl -X GET 'https://api.twitch.tv/helix/chat/chatters?broadcaster_id=123456&moderator_id=654321' \
-H 'Authorization: Bearer kpvy3cjboyptmiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfn0nyan9c87zr6t'

Example Response


{
  "data": [
    {
      "user_id": "128393656",
      "user_login": "smittysmithers",
      "user_name": "smittysmithers"
    },
    ...
  ],
  "pagination": {
    "cursor": "eyJiIjpudWxsLCJhIjp7Ik9mZnNldCI6NX19"
  },
  "total": 8
}

Get Channel Emotes

Gets all emotes that the specified Twitch channel created. Broadcasters create these custom emotes for users who subscribe to or follow the channel or cheer Bits in the channel’s chat window. Learn More

For information about the custom emotes, see subscriber emotes, Bits tier emotes, and follower emotes.

NOTE: With the exception of custom follower emotes, users may use custom emotes in any Twitch chat.

Authorization

Requires an app access token or user access token.

URL

GET https://api.twitch.tv/helix/chat/emotes

Request Query Parameters

Parameter Type Required? Description
broadcaster_id String Yes An ID that identifies the broadcaster whose emotes you want to get.

Response Body

Field Type Description
data Object[] The list of emotes that the specified broadcaster created. If the broadcaster hasn’t created custom emotes, the list is empty.
   id String An ID that identifies this emote.
   name String The name of the emote. This is the name that viewers type in the chat window to get the emote to appear.
   images Object The image URLs for the emote. These image URLs always provide a static, non-animated emote image with a light background.

NOTE: You should use the templated URL in the template field to fetch the image instead of using these URLs.
      url_1x String A URL to the small version (28px x 28px) of the emote.
      url_2x String A URL to the medium version (56px x 56px) of the emote.
      url_4x String A URL to the large version (112px x 112px) of the emote.
   tier String The subscriber tier at which the emote is unlocked. This field contains the tier information only if emote_type is set to subscriptions, otherwise, it’s an empty string.
   emote_type String The type of emote. The possible values are:
  • bitstier — A custom Bits tier emote.
  • follower — A custom follower emote.
  • subscriptions — A custom subscriber emote.
   emote_set_id String An ID that identifies the emote set that the emote belongs to.
   format String[] The formats that the emote is available in. For example, if the emote is available only as a static PNG, the array contains only static. But if the emote is available as a static PNG and an animated GIF, the array contains static and animated. The possible formats are:
  • animated — An animated GIF is available for this emote.
  • static — A static PNG file is available for this emote.
   scale String[] The sizes that the emote is available in. For example, if the emote is available in small and medium sizes, the array contains 1.0 and 2.0. Possible sizes are:
  • 1.0 — A small version (28px x 28px) is available.
  • 2.0 — A medium version (56px x 56px) is available.
  • 3.0 — A large version (112px x 112px) is available.
   theme_mode String[] The background themes that the emote is available in. Possible themes are:
  • dark
  • light
template String A templated URL. Use the values from the id, format, scale, and theme_mode fields to replace the like-named placeholder strings in the templated URL to create a CDN (content delivery network) URL that you use to fetch the emote. For information about what the template looks like and how to use it to fetch emotes, see Emote CDN URL format. You should use this template instead of using the URLs in the images object.

Response Codes

Code Description
200 OK Successfully retrieved the custom emotes for the specified broadcaster.
400 Bad Request
  • The broadcaster_id query parameter is required.
401 Unauthorized
  • The Authorization header is required and must specify a valid app access token or user access token.
  • The OAuth token is not valid.
  • The ID in the Client-Id header must match the Client ID in the OAuth token.

Example Request

Gets custom emotes that the TwitchDev channel created.

curl -X GET 'https://api.twitch.tv/helix/chat/emotes?broadcaster_id=141981764' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
# Twitch CLI example that gets the custom emotes for the specified channel.

twitch api get /chat/emotes -q broadcaster_id=141981764

Example Response


{
  "data": [
    {
      "id": "304456832",
      "name": "twitchdevPitchfork",
      "images": {
        "url_1x": "https://static-cdn.jtvnw.net/emoticons/v2/304456832/static/light/1.0",
        "url_2x": "https://static-cdn.jtvnw.net/emoticons/v2/304456832/static/light/2.0",
        "url_4x": "https://static-cdn.jtvnw.net/emoticons/v2/304456832/static/light/3.0"
      },
      "tier": "1000",
      "emote_type": "subscriptions",
      "emote_set_id": "301590448",
      "format": [
        "static"
      ],
      "scale": [
        "1.0",
        "2.0",
        "3.0"
      ],
      "theme_mode": [
        "light",
        "dark"
      ]
    },
    ...
    {
      "id": "emotesv2_4c3b4ed516de493bbcd2df2f5d450f49",
      "name": "twitchdevHyperPitchfork",
      "images": {
        "url_1x": "https://static-cdn.jtvnw.net/emoticons/v2/emotesv2_4c3b4ed516de493bbcd2df2f5d450f49/static/light/1.0",
        "url_2x": "https://static-cdn.jtvnw.net/emoticons/v2/emotesv2_4c3b4ed516de493bbcd2df2f5d450f49/static/light/2.0",
        "url_4x": "https://static-cdn.jtvnw.net/emoticons/v2/emotesv2_4c3b4ed516de493bbcd2df2f5d450f49/static/light/3.0"
      },
      "tier": "1000",
      "emote_type": "subscriptions",
      "emote_set_id": "318939165",
      "format": [
        "static",
        "animated"
      ],
      "scale": [
        "1.0",
        "2.0",
        "3.0"
      ],
      "theme_mode": [
        "light",
        "dark"
      ]
    },
  ],
  "template": "https://static-cdn.jtvnw.net/emoticons/v2/{{id}}/{{format}}/{{theme_mode}}/{{scale}}"
}

Get Global Emotes

Gets all global emotes. Global emotes are Twitch-created emotes that users can use in any Twitch chat.

Learn More

Authorization

Requires an app access token or user access token.

URL

GET https://api.twitch.tv/helix/chat/emotes/global

Request Query Parameters

None

Response Body

Field Type Description
data Object[] The list of global emotes.
   id String An ID that identifies this emote.
   name String The name of the emote. This is the name that viewers type in the chat window to get the emote to appear.
   images Object The image URLs for the emote. These image URLs always provide a static, non-animated emote image with a light background.

NOTE: You should use the templated URL in the template field to fetch the image instead of using these URLs.
      url_1x String A URL to the small version (28px x 28px) of the emote.
      url_2x String A URL to the medium version (56px x 56px) of the emote.
      url_4x String A URL to the large version (112px x 112px) of the emote.
   format String[] The formats that the emote is available in. For example, if the emote is available only as a static PNG, the array contains only static. But if the emote is available as a static PNG and an animated GIF, the array contains static and animated. The possible formats are:
  • animated — An animated GIF is available for this emote.
  • static — A static PNG file is available for this emote.
   scale String[] The sizes that the emote is available in. For example, if the emote is available in small and medium sizes, the array contains 1.0 and 2.0. Possible sizes are:
  • 1.0 — A small version (28px x 28px) is available.
  • 2.0 — A medium version (56px x 56px) is available.
  • 3.0 — A large version (112px x 112px) is available.
   theme_mode String[] The background themes that the emote is available in. Possible themes are:
  • dark
  • light
template String A templated URL. Use the values from the id, format, scale, and theme_mode fields to replace the like-named placeholder strings in the templated URL to create a CDN (content delivery network) URL that you use to fetch the emote. For information about what the template looks like and how to use it to fetch emotes, see Emote CDN URL format. You should use this template instead of using the URLs in the images object.

Response Codes

Code Description
200 OK Successfully retrieved the global emotes.
401 Unauthorized
  • The Authorization header is required and must specify a valid app access token or user access token.
  • The OAuth token is not valid.
  • The ID in the Client-Id header must match the Client ID in the OAuth token.

Example Request

Gets all global emotes.

curl -X GET 'https://api.twitch.tv/helix/chat/emotes/global' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
# Twitch CLI example that gets all global emotes.

twitch api get /chat/emotes/global

Example Response


{
  "data": [
    {
      "id": "196892",
      "name": "TwitchUnity",
      "images": {
        "url_1x": "https://static-cdn.jtvnw.net/emoticons/v2/196892/static/light/1.0",
        "url_2x": "https://static-cdn.jtvnw.net/emoticons/v2/196892/static/light/2.0",
        "url_4x": "https://static-cdn.jtvnw.net/emoticons/v2/196892/static/light/3.0"
      },
      "format": [
        "static"
      ],
      "scale": [
        "1.0",
        "2.0",
        "3.0"
      ],
      "theme_mode": [
        "light",
        "dark"
      ]
    },
    ...
  ],
  "template": "https://static-cdn.jtvnw.net/emoticons/v2/{{id}}/{{format}}/{{theme_mode}}/{{scale}}"
}

Get Emote Sets

Gets emotes for one or more specified emote sets.

An emote set groups emotes that have a similar context. For example, Twitch places all the subscriber emotes that a broadcaster uploads for their channel in the same emote set.

Learn More

Authorization

Requires an app access token or user access token.

URL

GET https://api.twitch.tv/helix/chat/emotes/set

Request Query Parameters

Parameter Type Required? Description
emote_set_id String Yes An ID that identifies the emote set to get. Include this parameter for each emote set you want to get. For example, emote_set_id=1234&emote_set_id=5678. You may specify a maximum of 25 IDs. The response contains only the IDs that were found and ignores duplicate IDs.

To get emote set IDs, use the Get Channel Emotes API.

Response Body

Field Type Description
data Object[] The list of emotes found in the specified emote sets. The list is empty if none of the IDs were found. The list is in the same order as the set IDs specified in the request. Each set contains one or more emoticons.
   id String An ID that uniquely identifies this emote.
   name String The name of the emote. This is the name that viewers type in the chat window to get the emote to appear.
   images Object The image URLs for the emote. These image URLs always provide a static, non-animated emote image with a light background.

NOTE: You should use the templated URL in the template field to fetch the image instead of using these URLs.
      url_1x String A URL to the small version (28px x 28px) of the emote.
      url_2x String A URL to the medium version (56px x 56px) of the emote.
      url_4x String A URL to the large version (112px x 112px) of the emote.
   emote_type String The type of emote. The possible values are:
  • bitstier — A Bits tier emote.
  • follower — A follower emote.
  • subscriptions — A subscriber emote.
   emote_set_id String An ID that identifies the emote set that the emote belongs to.
   owner_id String The ID of the broadcaster who owns the emote.
   format String[] The formats that the emote is available in. For example, if the emote is available only as a static PNG, the array contains only static. But if the emote is available as a static PNG and an animated GIF, the array contains static and animated. The possible formats are:
  • animated — An animated GIF is available for this emote.
  • static — A static PNG file is available for this emote.
   scale String[] The sizes that the emote is available in. For example, if the emote is available in small and medium sizes, the array contains 1.0 and 2.0. Possible sizes are:
  • 1.0 — A small version (28px x 28px) is available.
  • 2.0 — A medium version (56px x 56px) is available.
  • 3.0 — A large version (112px x 112px) is available.
   theme_mode String[] The background themes that the emote is available in. Possible themes are:
  • dark
  • light
template string A templated URL. Use the values from the id, format, scale, and theme_mode fields to replace the like-named placeholder strings in the templated URL to create a CDN (content delivery network) URL that you use to fetch the emote. For information about what the template looks like and how to use it to fetch emotes, see Emote CDN URL format. You should use this template instead of using the URLs in the images object.

Response Codes

Code Description
200 OK Successfully retrieved the emotes for the specified emote sets.
400 Bad Request
  • The emote_set_id query parameter is required.
  • The number of emote_set_id query parameters exceeds the maximum allowed.
401 Unauthorized
  • The Authorization header is required and must specify a valid app access token or user access token.
  • The OAuth token is not valid.
  • The ID in the Client-Id header must match the Client ID in the OAuth token.

Example Request

Gets the emotes for the TwitchDev subscriber emote set.

curl -X GET 'https://api.twitch.tv/helix/chat/emotes/set?emote_set_id=301590448' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
# Twitch CLI example that gets the emotes for the specified emote set.

twitch api get /chat/emotes/set -q emote_set_id=301590448

Example Response


{
  "data": [
    {
      "id": "304456832",
      "name": "twitchdevPitchfork",
      "images": {
        "url_1x": "https://static-cdn.jtvnw.net/emoticons/v2/304456832/static/light/1.0",
        "url_2x": "https://static-cdn.jtvnw.net/emoticons/v2/304456832/static/light/2.0",
        "url_4x": "https://static-cdn.jtvnw.net/emoticons/v2/304456832/static/light/3.0"
      },
      "emote_type": "subscriptions",
      "emote_set_id": "301590448",
      "owner_id": "141981764",
      "format": [
        "static"
      ],
      "scale": [
        "1.0",
        "2.0",
        "3.0"
      ],
      "theme_mode": [
        "light",
        "dark"
      ]
    },
    ...
  ],
  "template": "https://static-cdn.jtvnw.net/emoticons/v2/{{id}}/{{format}}/{{theme_mode}}/{{scale}}"
}

Get Channel Chat Badges

Gets all badges that the specified broadcaster created. The list is empty if the broadcaster hasn’t created custom chat badges. For information about custom badges, see subscriber badges and Bits badges.

Authorization

Requires an app access token or user access token.

URL

GET https://api.twitch.tv/helix/chat/badges

Request Query Parameter

Parameter Type Required? Description
broadcaster_id String Yes The ID of the broadcaster whose chat badges you want to get.

Response Body

Field Type Description
data Object[] The list of chat badges. The list is sorted in ascending order by set_id, and within a set, the list is sorted in ascending order by id.
   set_id String An ID that identifies this set of chat badges. For example, Bits or Subscriber.
   versions Object[] The list of chat badges in this set.
      id String An ID that identifies this version of the badge. The ID can be any value. For example, for Bits, the ID is the Bits tier level, but for World of Warcraft, it could be Alliance or Horde.
      image_url_1x String A URL to the small version (18px x 18px) of the badge.
      image_url_2x String A URL to the medium version (36px x 36px) of the badge.
      image_url_4x String A URL to the large version (72px x 72px) of the badge.

Response Codes

Code Description
200 OK Successfully retrieved the broadcaster’s custom chat badges.
400 Bad Request
  • The broadcaster_id query parameter is required.
401 Unauthorized
  • The Authorization header is required and must specify a valid app access token or user access token.
  • The OAuth token is not valid.
  • The ID in the Client-Id header must match the Client ID in the OAuth token.

Example Request

Get the list of custom chat badges that the BlueLava Twitch channel created.

curl -X GET 'https://api.twitch.tv/helix/chat/badges?broadcaster_id=135093069' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
  "data": [
    {
      "set_id": "bits",
      "versions": [
        {
          "id": "1",
          "image_url_1x": "https://static-cdn.jtvnw.net/badges/v1/743a0f3b-84b3-450b-96a0-503d7f4a9764/1",
          "image_url_2x": "https://static-cdn.jtvnw.net/badges/v1/743a0f3b-84b3-450b-96a0-503d7f4a9764/2",
          "image_url_4x": "https://static-cdn.jtvnw.net/badges/v1/743a0f3b-84b3-450b-96a0-503d7f4a9764/3"
        }
      ]
    },
    {
      "set_id": "subscriber",
      "versions": [
        {
          "id": "0",
          "image_url_1x": "https://static-cdn.jtvnw.net/badges/v1/eb4a8a4c-eacd-4f5e-b9f2-394348310442/1",
          "image_url_2x": "https://static-cdn.jtvnw.net/badges/v1/eb4a8a4c-eacd-4f5e-b9f2-394348310442/2",
          "image_url_4x": "https://static-cdn.jtvnw.net/badges/v1/eb4a8a4c-eacd-4f5e-b9f2-394348310442/3"
        },
        ...
      ]
    }
  ]
}

Get Global Chat Badges

Gets the list of chat badges that Twitch created. Users can use these badges in any channel’s chat room. For information about chat badges, see Twitch Chat Badges Guide.

Authorization

Requires an app access token or user access token.

URL

GET https://api.twitch.tv/helix/chat/badges/global

Request Query Parameters

None

Response Body

Field Type Description
data Object[] The list of chat badges. The list is sorted in ascending order by set_id, and within a set, the list is sorted in ascending order by id.
   set_id String An ID that identifies this set of chat badges. For example, Bits or Subscriber.
   versions Object[] The list of chat badges in this set.
      id String An ID that identifies this version of the badge. The ID can be any value. For example, for Bits, the ID is the Bits tier level, but for World of Warcraft, it could be Alliance or Horde.
      image_url_1x String A URL to the small version (18px x 18px) of the badge.
      image_url_2x String A URL to the medium version (36px x 36px) of the badge.
      image_url_4x String A URL to the large version (72px x 72px) of the badge.

Response Codes

Code Description
200 OK Successfully retrieved the list of global chat badges.
401 Unauthorized
  • The Authorization header is required and must specify a valid app access token or user access token.
  • The OAuth token is not valid.
  • The ID in the Client-Id header must match the Client ID in the OAuth token.

Example Request

Gets the list of global chat badges.

curl -X GET 'https://api.twitch.tv/helix/chat/badges/global' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
  "data": [
    ...
    {
      "set_id": "vip",
      "versions": [
        {
          "id": "1",
          "image_url_1x": "https://static-cdn.jtvnw.net/badges/v1/b817aba4-fad8-49e2-b88a-7cc744dfa6ec/1",
          "image_url_2x": "https://static-cdn.jtvnw.net/badges/v1/b817aba4-fad8-49e2-b88a-7cc744dfa6ec/2",
          "image_url_4x": "https://static-cdn.jtvnw.net/badges/v1/b817aba4-fad8-49e2-b88a-7cc744dfa6ec/3"
        }
      ]
    },
    ...
  ]
}

Get Chat Settings

Gets the broadcaster’s chat settings.

For an overview of chat settings, see Chat Commands for Broadcasters and Moderators and Moderator Preferences.

Authorization

Requires an app access token or user access token.

URL

GET https://api.twitch.tv/helix/chat/settings

Request Query Parameters

Parameter Type Required? Description
broadcaster_id String Yes The ID of the broadcaster whose chat settings you want to get.
moderator_id String No The ID of a user that has permission to moderate the broadcaster’s chat room, or the broadcaster’s ID if they’re getting the settings.

This field is required only if you want to include the non_moderator_chat_delay and non_moderator_chat_delay_duration settings in the response.

If you specify this field, this ID must match the user ID in the user access token.

Response Body

Field Type Description
data Object[] The list of chat settings. The list contains a single object with all the settings.
   broadcaster_id String The ID of the broadcaster specified in the request.
   emote_mode Boolean A Boolean value that determines whether chat messages must contain only emotes. Is true if chat messages may contain only emotes; otherwise, false.
   follower_mode Boolean A Boolean value that determines whether the broadcaster restricts the chat room to followers only.

Is true if the broadcaster restricts the chat room to followers only; otherwise, false.

See the follower_mode_duration field for how long users must follow the broadcaster before being able to participate in the chat room.
   follower_mode_duration Integer The length of time, in minutes, that users must follow the broadcaster before being able to participate in the chat room. Is null if follower_mode is false.
   moderator_id String The moderator’s ID. The response includes this field only if the request specifies a user access token that includes the moderator:read:chat_settings scope.
   non_moderator_chat_delay Boolean A Boolean value that determines whether the broadcaster adds a short delay before chat messages appear in the chat room. This gives chat moderators and bots a chance to remove them before viewers can see the message. See the non_moderator_chat_delay_duration field for the length of the delay. Is true if the broadcaster applies a delay; otherwise, false.

The response includes this field only if the request specifies a user access token that includes the moderator:read:chat_settings scope and the user in the moderator_id query parameter is one of the broadcaster’s moderators.
   non_moderator_chat_delay_duration Integer The amount of time, in seconds, that messages are delayed before appearing in chat. Is null if non_moderator_chat_delay is false.

The response includes this field only if the request specifies a user access token that includes the moderator:read:chat_settings scope and the user in the moderator_id query parameter is one of the broadcaster’s moderators.
   slow_mode Boolean A Boolean value that determines whether the broadcaster limits how often users in the chat room are allowed to send messages.

Is true if the broadcaster applies a delay; otherwise, false.

See the slow_mode_wait_time field for the delay.
   slow_mode_wait_time Integer The amount of time, in seconds, that users must wait between sending messages.

Is null if slow_mode is false.
   subscriber_mode Boolean A Boolean value that determines whether only users that subscribe to the broadcaster’s channel may talk in the chat room.

Is true if the broadcaster restricts the chat room to subscribers only; otherwise, false.
   unique_chat_mode Boolean A Boolean value that determines whether the broadcaster requires users to post only unique messages in the chat room.

Is true if the broadcaster requires unique messages only; otherwise, false.

Response Codes

Code Description
200 OK Successfully retrieved the broadcaster’s chat settings.
400 Bad Request
  • The broadcaster_id query parameter is required.
401 Unauthorized
  • The Authorization header is required and must specify a valid app access token or user access token.
  • The OAuth token is not valid.
  • The ID in the Client-Id header must match the Client ID in the OAuth token.

Example Request

curl -X GET 'https://api.twitch.tv/helix/chat/settings?broadcaster_id=1234' \
-H 'Authorization: Bearer 4a4x78f5wqvkybms7mxfist3jmzul' \
-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh'

Example Response

{
  "data": [
    {
      "broadcaster_id": "713936733",
      "slow_mode": false,
      "slow_mode_wait_time": null,
      "follower_mode": true,
      "follower_mode_duration": 0,
      "subscriber_mode": false,
      "emote_mode": false,
      "unique_chat_mode": false,
      "non_moderator_chat_delay": true,
      "non_moderator_chat_delay_duration": 4
    }
  ]
}

Update Chat Settings

Updates the broadcaster’s chat settings.

Authentication

Requires a user access token that includes the moderator:manage:chat_settings scope.

URL

PATCH https://api.twitch.tv/helix/chat/settings

Request Query Parameters

Parameter Type Required? Description
broadcaster_id String Yes The ID of the broadcaster whose chat settings you want to update.
moderator_id String Yes The ID of a user that has permission to moderate the broadcaster’s chat room, or the broadcaster’s ID if they’re making the update. This ID must match the user ID in the user access token.

Request Body

All fields are optional. Specify only those fields that you want to update.

To set the slow_mode_wait_time or follower_mode_duration field to its default value, set the corresponding slow_mode or follower_mode field to true (and don’t include the slow_mode_wait_time or follower_mode_duration field).

To set the slow_mode_wait_time, follower_mode_duration, or non_moderator_chat_delay_duration field’s value, you must set the corresponding slow_mode, follower_mode, or non_moderator_chat_delay field to true.

To remove the slow_mode_wait_time, follower_mode_duration, or non_moderator_chat_delay_duration field’s value, set the corresponding slow_mode, follower_mode, or non_moderator_chat_delay field to false (and don’t include the slow_mode_wait_time, follower_mode_duration, or non_moderator_chat_delay_duration field).

Field Type Description
emote_mode Boolean A Boolean value that determines whether chat messages must contain only emotes.

Set to true if only emotes are allowed; otherwise, false. The default is false.
follower_mode Boolean A Boolean value that determines whether the broadcaster restricts the chat room to followers only.

Set to true if the broadcaster restricts the chat room to followers only; otherwise, false. The default is true.

To specify how long users must follow the broadcaster before being able to participate in the chat room, see the follower_mode_duration field.
follower_mode_duration Integer The length of time, in minutes, that users must follow the broadcaster before being able to participate in the chat room. Set only if follower_mode is true. Possible values are: 0 (no restriction) through 129600 (3 months). The default is 0.
non_moderator_chat_delay Boolean A Boolean value that determines whether the broadcaster adds a short delay before chat messages appear in the chat room. This gives chat moderators and bots a chance to remove them before viewers can see the message.

Set to true if the broadcaster applies a delay; otherwise, false. The default is false.

To specify the length of the delay, see the non_moderator_chat_delay_duration field.
non_moderator_chat_delay_duration Integer The amount of time, in seconds, that messages are delayed before appearing in chat. Set only if non_moderator_chat_delay is true. Possible values are:
  • 2 — 2 second delay (recommended)
  • 4 — 4 second delay
  • 6 — 6 second delay
slow_mode Boolean A Boolean value that determines whether the broadcaster limits how often users in the chat room are allowed to send messages. Set to true if the broadcaster applies a wait period between messages; otherwise, false. The default is false.

To specify the delay, see the slow_mode_wait_time field.
slow_mode_wait_time Integer The amount of time, in seconds, that users must wait between sending messages. Set only if slow_mode is true.

Possible values are: 3 (3 second delay) through 120 (2 minute delay). The default is 30 seconds.
subscriber_mode Boolean A Boolean value that determines whether only users that subscribe to the broadcaster’s channel may talk in the chat room.

Set to true if the broadcaster restricts the chat room to subscribers only; otherwise, false. The default is false.
unique_chat_mode Boolean A Boolean value that determines whether the broadcaster requires users to post only unique messages in the chat room.

Set to true if the broadcaster allows only unique messages; otherwise, false. The default is false.

Response Body

Field Type Description
data Object[] The list of chat settings. The list contains a single object with all the settings.
   broadcaster_id String The ID of the broadcaster specified in the request.
   emote_mode Boolean A Boolean value that determines whether chat messages must contain only emotes. Is true if chat messages may contain only emotes; otherwise, false.
   follower_mode Boolean A Boolean value that determines whether the broadcaster restricts the chat room to followers only.

Is true if the broadcaster restricts the chat room to followers only; otherwise, false.

See the follower_mode_duration field for how long users must follow the broadcaster before being able to participate in the chat room.
   follower_mode_duration Integer The length of time, in minutes, that users must follow the broadcaster before being able to participate in the chat room. Is null if follower_mode is false.
   moderator_id String The moderator’s ID. The response includes this field only if the request specifies a user access token that includes the moderator:read:chat_settings scope.
   non_moderator_chat_delay Boolean A Boolean value that determines whether the broadcaster adds a short delay before chat messages appear in the chat room. This gives chat moderators and bots a chance to remove them before viewers can see the message. See the non_moderator_chat_delay_duration field for the length of the delay. Is true if the broadcaster applies a delay; otherwise, false.
   non_moderator_chat_delay_duration Integer The amount of time, in seconds, that messages are delayed before appearing in chat. Is null if non_moderator_chat_delay is false.
   slow_mode Boolean A Boolean value that determines whether the broadcaster limits how often users in the chat room are allowed to send messages.

Is true if the broadcaster applies a delay; otherwise, false.

See the slow_mode_wait_time field for the delay.
   slow_mode_wait_time Integer The amount of time, in seconds, that users must wait between sending messages.

Is null if slow_mode is false.
   subscriber_mode Boolean A Boolean value that determines whether only users that subscribe to the broadcaster’s channel may talk in the chat room.

Is true if the broadcaster restricts the chat room to subscribers only; otherwise, false.
   unique_chat_mode Boolean A Boolean value that determines whether the broadcaster requires users to post only unique messages in the chat room.

Is true if the broadcaster requires unique messages only; otherwise, false.

Response Codes

Code Description
200 OK Successfully updated the broadcaster’s chat settings.
400 Bad Request
  • The broadcaster_id query parameter is required.
  • The moderator_id query parameter is required.
  • If slow_mode is true, the slow_mode_wait_time field must be set to a valid value.
  • If follower_mode is true, the follower_mode_duration field must be set to a valid value.
  • If non_moderator_chat_delay is true, the non_moderator_chat_delay_duration field must be set to a valid value.
401 Unauthorized
  • The ID in the moderator_id query parameter must match the user ID in the user access token.
  • The Authorization header is required and must contain a user access token.
  • The user access token must include the moderator:manage:chat_settings scope.
  • The access token is not valid.
  • The ID in the Client-Id header must match the client ID in the access token.
403 Forbidden
  • The user in the moderator_id query parameter must have moderator privileges in the broadcaster's channel.

Example Request

This example disables follower_mode by setting it to false.

curl -X PATCH 'https://api.twitch.tv/helix/chat/settings?broadcaster_id=1234&moderator_id=5678' \
-H 'Authorization: Bearer 4a4x78f5wqvkybms7mxfist3jmzul' \
-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh' \
-H 'Content-Type: application/json' \
-d '{"follower_mode": false}'

To change a setting’s value, the request must specify the mode field and its corresponding value field. For example, to change the value of slow_mode_wait_time, the request must also specify slow_mode even if it’s already true.

curl -X PATCH 'https://https://api.twitch.tv/helix/chat/settings?broadcaster_id=1234&moderator_id=5678' \
-H 'Authorization: Bearer 8j9yq1kpl92w96trqy7sintbsihdp' \
-H 'Client-Id: 0vql4f5yqu4spo6zrz1pkumcqwa9c' \
-H 'Content-Type: application/json' \
-d '{"slow_mode": true, "slow_mode_wait_time": 10}'

Example Response

{
  "data": [
    {
      "broadcaster_id": "1234",
      "moderator_id": "5678",
      "slow_mode": true,
      "slow_mode_wait_time": 10,
      "follower_mode": false,
      "follower_mode_duration": null,
      "subscriber_mode": false,
      "emote_mode": false,
      "unique_chat_mode": false,
      "non_moderator_chat_delay": false,
      "non_moderator_chat_delay_duration": null
    }
  ]
}

Send Chat Announcement

Sends an announcement to the broadcaster’s chat room.

Authorization

Requires a user access token that includes the moderator:manage:announcements scope.

URL

POST https://api.twitch.tv/helix/chat/announcements

Request Query Parameters

Parameter Type Required? Description
broadcaster_id String Yes The ID of the broadcaster that owns the chat room to send the announcement to.
moderator_id String Yes The ID of a user who has permission to moderate the broadcaster’s chat room, or the broadcaster’s ID if they’re sending the announcement. This ID must match the user ID in the user access token.

Request Body

Field Type Required? Description
message String Yes The announcement to make in the broadcaster’s chat room. Announcements are limited to a maximum of 500 characters; announcements longer than 500 characters are truncated.
color String No The color used to highlight the announcement. Possible case-sensitive values are:
  • blue
  • green
  • orange
  • purple
  • primary (default)
If color is set to primary or is not set, the channel’s accent color is used to highlight the announcement (see Profile Accent Color under profile settings, Channel and Videos, and Brand).

Response Body

None

Response Codes

Code Description
204 No Content Successfully sent the announcement.
400 Bad Request
  • The message field in the request's body is required.
  • The specified color is not valid.
401 Unauthorized
  • The Authorization header is required and must contain a user access token.
  • The user access token is missing the moderator:manage:announcements scope.
  • The OAuth token is not valid.
  • The client ID specified in the Client-Id header does not match the client ID specified in the OAuth token.

Example Request

Sends an announcement to the broadcaster’s chat room.

curl -X POST 'https://api.twitch.tv/helix/chat/announcements?broadcaster_id=11111&moderator_id=44444' \
-H 'Authorization: Bearer kpvy3cjboyptmdkiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfnys0nyan9c87zr6t' \
-H 'Content-Type: application/json' \
-d '{"message":"Hello chat!","color":"purple"}'

Get User Chat Color

Gets the color used for the user’s name in chat.

Authorization

Requires an app access token or user access token.

URL

GET https://api.twitch.tv/helix/chat/color

Request Query Parameters

Parameter Type Required? Description
user_id String Yes The ID of the user whose username color you want to get. To specify more than one user, include the user_id parameter for each user to get. For example, &user_id=1234&user_id=5678. The maximum number of IDs that you may specify is 100.

The API ignores duplicate IDs and IDs that weren’t found.

Response Body

Field Type Description
data Object[] The list of users and the color code they use for their name.
   user_id String An ID that uniquely identifies the user.
   user_login String The user’s login name.
   user_name String The user’s display name.
   color String The Hex color code that the user uses in chat for their name. If the user hasn’t specified a color in their settings, the string is empty.

Response Codes

Code Description
200 OK Successfully retrieved the chat color used by the specified users.
400 Bad Request
  • The ID in the user_id query parameter is not valid.
401 Unauthorized
  • The Authorization header is required and must contain an app access token or user access token.
  • The OAuth token is not valid.
  • The client ID specified in the Client-Id header does not match the client ID specified in the OAuth token.

Example Request

Gets the chat color code used by the specified users.

curl -X GET 'https://api.twitch.tv/helix/chat/color?user_id=11111&user_id=44444' \
-H 'Authorization: Bearer kpvy3cjboyptmdkiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfnys0nyan9c87zr6t' 

Example Response

{
  "data": [
    {
      "user_id": "11111",
      "user_name": "SpeedySpeedster1",
      "user_login": "speedyspeedster1",
      "color": "#9146FF"
    },
    {
      "user_id": "44444",
      "user_name": "SpeedySpeedster2",
      "user_login": "speedyspeedster2",
      "color": ""
    }
  ]
}

Update User Chat Color

Updates the color used for the user’s name in chat.

Authorization

Requires a user access token that includes the user:manage:chat_color scope.

URL

PUT https://api.twitch.tv/helix/chat/color

Request Query Parameters

Parameter Type Required? Description
user_id String Yes The ID of the user whose chat color you want to update. This ID must match the user ID in the access token.
color String Yes The color to use for the user’s name in chat. All users may specify one of the following named color values.
  • blue
  • blue_violet
  • cadet_blue
  • chocolate
  • coral
  • dodger_blue
  • firebrick
  • golden_rod
  • green
  • hot_pink
  • orange_red
  • red
  • sea_green
  • spring_green
  • yellow_green
Turbo and Prime users may specify a named color or a Hex color code like #9146FF. If you use a Hex color code, remember to URL encode it.

Response Body

None

Response Codes

Code Description
204 No Content Successfully updated the user’s chat color.
400 Bad Request
  • The ID in the user_id query parameter is not valid.
  • The color query parameter is required.
  • The named color in the color query parameter is not valid.
  • To specify a Hex color code, the user must be a Turbo or Prime user.
401 Unauthorized
  • The Authorization header is required and must contain a user access token.
  • The user access token must include the user:manage:chat_color scope.
  • The OAuth token is not valid.
  • The ID in the user_id query parameter must match the user ID in the access token.
  • The client ID specified in the Client-Id header does not match the client ID specified in the OAuth token.

Example Request

Uses a named color to change the color that the user uses for their name in chat.

curl -X PUT 'https://api.twitch.tv/helix/chat/color?user_id=123&color=blue' \
-H 'Authorization: Bearer kpvy3cjboyptmdkiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfnys0nyan9c87zr6t' 

Uses a color Hex code to change the color that the user uses for their name in chat.

curl -X PUT 'https://api.twitch.tv/helix/chat/color?user_id=123&color=%239146FF' \
-H 'Authorization: Bearer kpvy3cjboyptmdkiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfnys0nyan9c87zr6t' 

Create Clip

Creates a clip from the broadcaster’s stream.

This API captures up to 90 seconds of the broadcaster’s stream. The 90 seconds spans the point in the stream from when you called the API. For example, if you call the API at the 4:00 minute mark, the API captures from approximately the 3:35 mark to approximately the 4:05 minute mark. Twitch tries its best to capture 90 seconds of the stream, but the actual length may be less. This may occur if you begin capturing the clip near the beginning or end of the stream.

By default, Twitch publishes up to the last 30 seconds of the 90 seconds window and provides a default title for the clip. To specify the title and the portion of the 90 seconds window that’s used for the clip, use the URL in the response’s edit_url field. You can specify a clip that’s from 5 seconds to 60 seconds in length. The URL is valid for up to 24 hours or until the clip is published, whichever comes first.

Creating a clip is an asynchronous process that can take a short amount of time to complete. To determine whether the clip was successfully created, call Get Clips using the clip ID that this request returned. If Get Clips returns the clip, the clip was successfully created. If after 15 seconds Get Clips hasn’t returned the clip, assume it failed.

Authentication

Requires a user access token that includes the clips:edit scope.

URL

POST https://api.twitch.tv/helix/clips

Request Query Parameters

Parameter Type Required? Description
broadcaster_id String Yes The ID of the broadcaster whose stream you want to create a clip from.
has_delay Boolean No A Boolean value that determines whether the API captures the clip at the moment the viewer requests it or after a delay. If false (default), Twitch captures the clip at the moment the viewer requests it (this is the same clip experience as the Twitch UX). If true, Twitch adds a delay before capturing the clip (this basically shifts the capture window to the right slightly).

Response Body

Field Type Description
edit_url String A URL that you can use to edit the clip’s title, identify the part of the clip to publish, and publish the clip. Learn More

The URL is valid for up to 24 hours or until the clip is published, whichever comes first.
id String An ID that uniquely identifies the clip.

Response Codes

Code Description
202 Accepted Successfully started the clip process.
400 Bad Request
  • The broadcaster_id query parameter is required.
  • The ID in the broadcaster_id query parameter was not found.
401 Unauthorized
  • The Authorization header is required and must specify user access token.
  • The user access token must include the clips:edit scope.
  • The OAuth token is not valid.
  • The ID in the Client-Id header must match the Client ID in the OAuth token.
403 Forbidden
  • The broadcaster has restricted the ability to capture clips to followers and/or subscribers only.
  • The specified broadcaster has not enabled clips on their channel.
404 Not Found
  • The broadcaster in the broadcaster_id query parameter must be broadcasting live.

Example Request

curl -X POST 'https://api.twitch.tv/helix/clips?broadcaster_id=44322889' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
   "data":
   [{
      "id": "FiveWordsForClipSlug",
      "edit_url": "http://clips.twitch.tv/FiveWordsForClipSlug/edit"
   }]
}

Get Clips

Gets one or more video clips that were captured from streams. For information about clips, see How to use clips.

Authentication

Requires an app access token or user access token.

URL

GET https://api.twitch.tv/helix/clips

Request Query Parameters

The id, game_id, and broadcaster_id query parameters are mutually exclusive.

Parameter Type Required? Description
broadcaster_id String Yes An ID that identifies the broadcaster whose video clips you want to get. Use this parameter to get clips that were captured from the broadcaster’s streams.
game_id String Yes An ID that identifies the game whose clips you want to get. Use this parameter to get clips that were captured from streams that were playing this game.
id String Yes An ID that identifies the clip to get. To specify more than one ID, include this parameter for each clip you want to get. For example, id=foo&id=bar. You may specify a maximum of 100 IDs. The API ignores duplicate IDs and IDs that aren’t found.
started_at String No The start date used to filter clips. The API returns only clips within the start and end date window. Specify the date and time in RFC3339 format.
ended_at String No The end date used to filter clips. If not specified, the time window is the start date plus one week. Specify the date and time in RFC3339 format.
first Integer No The maximum number of clips to return per page in the response. The minimum page size is 1 clip per page and the maximum is 100. The default is 20.
before String No The cursor used to get the previous page of results. The Pagination object in the response contains the cursor’s value. Read More
after String No The cursor used to get the next page of results. The Pagination object in the response contains the cursor’s value. Read More

Response Body

Field Type Description
data Object[] The list of video clips. For clips returned by game_id or broadcaster_id, the list is in descending order by view count. For lists returned by id, the list is in the same order as the input IDs.
   id String An ID that uniquely identifies the clip.
   url String A URL to the clip.
   embed_url String A URL that you can use in an iframe to embed the clip (see Embedding Video and Clips).
   broadcaster_id String An ID that identifies the broadcaster that the video was clipped from.
   broadcaster_name String The broadcaster’s display name.
   creator_id String An ID that identifies the user that created the clip.
   creator_name String The user’s display name.
   video_id String An ID that identifies the video that the clip came from. This field contains an empty string if the video is not available.
   game_id String The ID of the game that was being played when the clip was created.
   language String The ISO 639-1 two-letter language code that the broadcaster broadcasts in. For example, en for English. The value is other if the broadcaster uses a language that Twitch doesn’t support.
   title String The title of the clip.
   view_count Integer The number of times the clip has been viewed.
   created_at String The date and time of when the clip was created. The date and time is in RFC3339 format.
   thumbnail_url String A URL to a thumbnail image of the clip.
   duration float The length of the clip, in seconds. Precision is 0.1.
   vod_offset Integer The zero-based offset, in seconds, to where the clip starts in the video (VOD). Is null if the video is not available or hasn’t been created yet from the live stream (see video_id).

Note that there’s a delay between when a clip is created during a broadcast and when the offset is set. During the delay period, vod_offset is null. The delay is indeterminant but is typically minutes long.
pagination Object The information used to page through the list of results. The object is empty if there are no more pages left to page through. Read More
   cursor String The cursor used to get the next page of results. Set the request’s after or before query parameter to this value depending on whether you’re paging forwards or backwards.

Response Codes

Code Description
200 OK Successfully retrieved the list of video clips.
400 Bad Request
  • The id or game_id or broadcaster_id query parameter is required.
  • The id, game_id, and broadcaster_id query parameters are mutually exclusive; you may specify only one of them.
401 Unauthorized
  • The Authorization header is required and must contain an app access token or user access token.
  • The OAuth token is not valid.
  • The client ID specified in the Client-Id header does not match the client ID specified in the OAuth token.
404 Not Found
  • The ID in game_id was not found.

Example Request

Gets a clip by ID.

curl -X GET 'https://api.twitch.tv/helix/clips?id=AwkwardHelplessSalamanderSwiftRage' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
  "data": [
    {
      "id": "AwkwardHelplessSalamanderSwiftRage",
      "url": "https://clips.twitch.tv/AwkwardHelplessSalamanderSwiftRage",
      "embed_url": "https://clips.twitch.tv/embed?clip=AwkwardHelplessSalamanderSwiftRage",
      "broadcaster_id": "67955580",
      "broadcaster_name": "ChewieMelodies",
      "creator_id": "53834192",
      "creator_name": "BlackNova03",
      "video_id": "205586603",
      "game_id": "488191",
      "language": "en",
      "title": "babymetal",
      "view_count": 10,
      "created_at": "2017-11-30T22:34:18Z",
      "thumbnail_url": "https://clips-media-assets.twitch.tv/157589949-preview-480x272.jpg",
      "duration": 60,
      "vod_offset": 480
    }
  ]
}

Example Request

Gets the broadcaster’s top 5 clips based on views.

curl -X GET 'https://api.twitch.tv/helix/clips?broadcaster_id=1234&first=5' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
  "data": [
    {
      "id": "RandomClip1",
      "url": "https://clips.twitch.tv/AwkwardHelplessSalamanderSwiftRage",
      "embed_url": "https://clips.twitch.tv/embed?clip=RandomClip1",
      "broadcaster_id": "1234",
      "broadcaster_name": "JJ",
      "creator_id": "123456",
      "creator_name": "MrMarshall",
      "video_id": "",
      "game_id": "33103",
      "language": "en",
      "title": "random1",
      "view_count": 10,
      "created_at": "2017-11-30T22:34:18Z",
      "thumbnail_url": "https://clips-media-assets.twitch.tv/157589949-preview-480x272.jpg",
      "duration": 12.9,
      "vod_offset": 1957
    },
    ...
  ],
  "pagination": {
    "cursor": "eyJiIjpudWxsLCJhIjoiIn0"
  }
}

Get Code Status

Gets the status of one or more redemption codes for a Bits reward. Only client IDs approved by Twitch may request a redemption code’s status.

Rate limit: You may send at most one request per second per user.

URL

GET https://api.twitch.tv/helix/entitlements/codes

Authentication

Requires an app access token. The client ID in the access token must match a client ID that Twitch has approved to provide entitlements.

Request Query Parameters

Parameter Type Required? Description
code String Yes The redemption code to check. Include this parameter for each redemption code whose status you want to check. For example, code=1234&code=5678. You may specify a maximum of 20 codes.
user_id Integer Yes The ID of the user that owns the redemption code.

Response Body

Field Type Description
data Object[] The list of redemption codes and their status values.
   code String The redemption code.
   status String The redemption code’s status. Possible values are:
  • ALREADY_CLAIMED — The code has already been claimed. All codes are single-use.
  • EXPIRED — The code has expired and can no longer be claimed.
  • INACTIVE — The code has not been activated.
  • INCORRECT_FORMAT — The code is not properly formatted.
  • INTERNAL_ERROR — An internal or unknown error occurred when checking the code. Retry later.
  • NOT_FOUND — The code was not found.
  • UNUSED — The code has not been claimed.
  • USER_NOT_ELIGIBLE — The user is not eligible to redeem this code.

Response Codes

Code Description
200 OK Successfully retrieved the statuses of the specified codes.
400 Bad Request
  • The user_id query parameter is required.
  • The code query parameter is required.
  • The code query parameter may not contain a comma-delimited list of codes. Instead, repeat the parameter for each code. For example, code=1234&code=5678.
  • The code query parameter may not contain an empty string.
401 Unauthorized
  • The Authorization header is required and must specify an app access token.
  • The access token is not valid.
  • The ID in the Client-Id header must match the Client ID in the access token.
403 Forbidden
  • The API accepts only app access tokens.
  • The client ID specified in the access token is not approved for getting the statuses of the redemption codes.

Example Request

curl -X GET 'https://api.twitch.tv/helix/entitlements/codes?code=KUHXV-4GXYP-AKAKK&code=XZDDZ-5SIQR-RT5M3&user_id=156900877' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
  "data":[
    {
      "code":"KUHXV-4GXYP-AKAKK",
      "status":"UNUSED"
    },
    {
      "code":"XZDDZ-5SIQR-RT5M3",
      "status":"ALREADY_CLAIMED"
    }
  ]
}

Get Drops Entitlements

Gets an organization’s list of entitlements that have been granted to a game, a user, or both.

The following table identifies the request parameters that you may specify based on the type of access token used.

Access token type Parameter Description
App None If you don’t specify request parameters, the request returns all entitlements that your organization owns.
App user_id The request returns all entitlements for any game that the organization granted to the specified user.
App user_id, game_id The request returns all entitlements that the specified game granted to the specified user.
App game_id The request returns all entitlements that the specified game granted to all entitled users.
User None If you don’t specify request parameters, the request returns all entitlements for any game that the organization granted to the user identified in the access token.
User user_id Invalid.
User user_id, game_id Invalid.
User game_id The request returns all entitlements that the specified game granted to the user identified in the access token.

Authentication

Requires an app access token or user access token. The client ID in the access token must own the game.

URL

GET https://api.twitch.tv/helix/entitlements/drops

Request Query Parameters

Parameter Type Required? Description
id String No An ID that identifies the entitlement to get. Include this parameter for each entitlement you want to get. For example, id=1234&id=5678. You may specify a maximum of 100 IDs.
user_id String No An ID that identifies a user that was granted entitlements.
game_id String No An ID that identifies a game that offered entitlements.
fulfillment_status String No The entitlement’s fulfillment status. Used to filter the list to only those with the specified status. Possible values are:
  • CLAIMED
  • FULFILLED
after String No The cursor used to get the next page of results. The Pagination object in the response contains the cursor’s value. Read More
first Integer No The maximum number of entitlements to return per page in the response. The minimum page size is 1 entitlement per page and the maximum is 1000. The default is 20.

Response Body

Field Type Description
data Object[] The list of entitlements.
   id String An ID that identifies the entitlement.
   benefit_id String An ID that identifies the benefit (reward).
   timestamp String The UTC date and time (in RFC3339 format) of when the entitlement was granted.
   user_id String An ID that identifies the user who was granted the entitlement.
   game_id String An ID that identifies the game the user was playing when the reward was entitled.
   fulfillment_status String The entitlement’s fulfillment status. Possible values are:
  • CLAIMED
  • FULFILLED
   last_updated String The UTC date and time (in RFC3339 format) of when the entitlement was last updated.
pagination Object The information used to page through the list of results. The object is empty if there are no more pages left to page through. Read More
   cursor String The cursor used to get the next page of results. Set the request’s after query parameter to this value to page forward through the results.

Response Codes

Code Description
200 OK Successfully retrieved the entitlements.
400 Bad Request
  • The value in the fulfillment_status query parameter is not valid.
  • The ID in the user_id query parameter must match the user ID in the user access token.
  • The client in the access token is not associated with a known organization.
  • The owner of the client in the access token is not a member of the organization.
401 Unauthorized
  • The ID in the Client-Id header must match the Client ID in the access token.
  • The Authorization header is required and must specify an app access token or user access token.
  • The access token is not valid.
403 Fobidden
  • The organization associated with the client in the access token must own the game specified in the game_id query parameter.
  • The organization associated with the client in the access token must own the entitlements specified in the id query parameter.
500 Internal server error  

Example Request

curl -H GET 'helix/entitlements/drops?user_id=25009227&game_id=33214' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
  "data": [
    {
      "id": "fb78259e-fb81-4d1b-8333-34a06ffc24c0",
      "benefit_id": "74c52265-e214-48a6-91b9-23b6014e8041",
      "timestamp": "2019-01-28T04:17:53.325Z",
      "user_id": "25009227",
      "game_id": "33214",
      "fulfillment_status": "CLAIMED",
      "updated_at": "2019-01-28T04:17:53.325Z"
    },
    {
      "id": "862750a5-265e-4ab6-9f0a-c64df3d54dd0",
      "benefit_id": "74c52265-e214-48a6-91b9-23b6014e8041",
      "timestamp": "2019-01-28T04:16:53.325Z",
      "user_id": "25009227",
      "game_id": "33214",
      "fulfillment_status": "CLAIMED",
      "updated_at": "2021-06-15T04:16:53.325Z"
    },
    {
      "id": "d8879baa-3966-4d10-8856-15fdd62cce02",
      "benefit_id": "cdfdc5c3-65a2-43bc-8767-fde06eb4ab2c",
      "timestamp": "2019-01-28T04:15:53.325Z",
      "user_id": "25009227",
      "game_id": "33214",
      "fulfillment_status": "FULFILLED",
      "updated_at": "2019-01-28T04:17:53.325Z"
    },
    ...
  ],
  "pagination": {
    "cursor": "eyJiIjpudW..."
  }
}

Update Drops Entitlements

Updates the Drop entitlement’s fulfillment status.

The following table identifies which entitlements are updated based on the type of access token used.

Access token type Data that’s updated
App Updates all entitlements with benefits owned by the organization in the access token.
User Updates all entitlements owned by the user in the access token and where the benefits are owned by the organization in the access token.

Authentication

Requires an app access token or user access token. The client ID in the access token must own the game.

URL

PATCH https://api.twitch.tv/helix/entitlements/drops

Request Body

Field Type Required? Description
entitlement_ids String[] No A list of IDs that identify the entitlements to update. You may specify a maximum of 100 IDs.
fulfillment_status String No The fulfillment status to set the entitlements to. Possible values are:
  • CLAIMED — The user claimed the benefit.
  • FULFILLED — The developer granted the benefit that the user claimed.

Response Body

Field Type Description
data Object[] A list that indicates which entitlements were successfully updated and those that weren’t.
   status String A string that indicates whether the status of the entitlements in the ids field were successfully updated. Possible values are:
  • INVALID_ID — The entitlement IDs in the ids field are not valid.
  • NOT_FOUND — The entitlement IDs in the ids field were not found.
  • SUCCESS — The status of the entitlements in the ids field were successfully updated.
  • UNAUTHORIZED — The user or organization identified by the user access token is not authorized to update the entitlements.
  • UPDATE_FAILED — The update failed. These are considered transient errors and the request should be retried later.
   ids String[] The list of entitlements that the status in the status field applies to.

Response Codes

Code Description
200 OK Successfully requested the updates. Check the response to determine which updates succeeded.
400 Bad Request
  • The value in the fulfillment_status field is not valid.
  • The client in the access token is not associated with a known organization.
  • The owner of the client in the access token is not a member of the organization.
401 Unauthorized
  • The Authorization header is required and must specify an app access token or user access token.
  • The access token is not valid.
  • The ID in the Client-Id header must match the Client ID in the access token.
500 Internal server error  

Example Request

curl -H PATCH 'helix/entitlements/drops' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Content-Type: application/json' \
-d '{
  "fulfillment_status": "FULFILLED",
  "entitlement_ids": [
    "fb78259e-fb81-4d1b-8333-34a06ffc24c0",
    "862750a5-265e-4ab6-9f0a-c64df3d54dd0",
    "d8879baa-3966-4d10-8856-15fdd62cce02",
    "9a290126-7e3b-4f66-a9ae-551537893b65"
  ]
}'

Example Response

{
  "data": [
    {
      "status": "SUCCESS",
      "ids": [
        "fb78259e-fb81-4d1b-8333-34a06ffc24c0", "862750a5-265e-4ab6-9f0a-c64df3d54dd0"
      ]
    },
    {
      "status": "UNAUTHORIZED",
      "ids": [
        "d8879baa-3966-4d10-8856-15fdd62cce02"
      ]
    },
    {
      "status": "UPDATE_FAILED",
      "ids": [
        "9a290126-7e3b-4f66-a9ae-551537893b65"
      ]
    }
  ]
}

Redeem Code

Redeems one or more redemption codes. Redeeming a code credits the user’s account with the entitlement; for example, a Bits reward earned by playing a game.

Rate limit: You may send at most one request per second per user.

URL

POST https://api.twitch.tv/helix/entitlements/codes

Authentication

Requires an app access token. Only client IDs approved by Twitch may redeem codes on behalf of any Twitch user account.

Request Query Parameters

Parameter Type Required? Description
code String Yes The redemption code to redeem. To redeem multiple codes, include this parameter for each redemption code. For example, code=1234&code=5678. You may specify a maximum of 20 codes.
user_id String Yes An ID of the user that owns the redemption code to redeem.

Response Body

Field Type Description
data Object[] The list of redeemed codes.
   code String The redemption code.
   status String The redemption code’s status. Possible values are:
  • ALREADY_CLAIMED — The code has already been claimed. All codes are single-use.
  • EXPIRED — The code has expired and can no longer be claimed.
  • INACTIVE — The code has not been activated.
  • INCORRECT_FORMAT — The code is not properly formatted.
  • INTERNAL_ERROR — An internal or unknown error occurred when accessing the code. Retry later.
  • NOT_FOUND — The code was not found.
  • SUCCESSFULLY_REDEEMED — Successfully redeemed the code and credited the user's account with the entitlement.
  • UNUSED — The code has not been claimed.
  • USER_NOT_ELIGIBLE — The user is not eligible to redeem this code.

Response Codes

Code Description
200 OK Successfully redeemed the code.
400 Bad Request
  • The user_id query parameter is required.
  • The code query parameter is required.
  • The code query parameter may not contain a comma-delimited list of codes. Instead, repeat the parameter for each code. For example, code=1234&code=5678.
  • The code query parameter may not contain an empty string.
401 Unauthorized
  • The Authorization header is required and must specify an app access token.
  • The access token is not valid.
  • The ID in the Client-Id header must match the Client ID in the access token.
403 Forbidden
  • The API accepts only app access tokens.
  • The client specified in the access token is not approved to redeem codes.
500 Internal server error  

Example Request

curl -X POST 'https://api.twitch.tv/helix/entitlements/codes?user_id=12345&code=8CD5P-V3J92-2S6JY&code=PUN4G-HYFVP-MMFET' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
  "data":[
    {
      "code":"8CD5P-V3J92-2S6JY",
      "status":"SUCCESSFULLY_REDEEMED"
    },
    {
      "code":"PUN4G-HYFVP-MMFET",
      "status":"ALREADY_CLAIMED"
    }
  ]
}

Get Extension Configuration Segment

Gets the specified configuration segment from the specified extension.

Rate Limits: You may retrieve each segment a maximum of 20 times per minute.

Authorization

Requires a signed JSON Web Token (JWT) created by an Extension Backend Service (EBS). For signing requirements, see Signing the JWT. The signed JWT must include the role, user_id, and exp fields (see JWT Schema). The role field must be set to external.

URL

GET https://api.twitch.tv/helix/extensions/configurations

Request Query Parameters

Parameter Type Required? Description
broadcaster_id String No The ID of the broadcaster that installed the extension. This parameter is required if you set the segment parameter to broadcaster or developer. Do not specify this parameter if you set segment to global.
extension_id String Yes The ID of the extension that contains the configuration segment you want to get.
segment String Yes The type of configuration segment to get. Possible case-sensitive values are:
  • broadcaster
  • developer
  • global
You may specify one or more segments. To specify multiple segments, include the segment parameter for each segment to get. For example, segment=broadcaster&segment=developer. Ignores duplicate segments.

Response Body

Field Type Description
data Object[] The list of requested configuration segments. The list is returned in the same order that you specified the list of segments in the request.
   segment String The type of segment. Possible values are:
  • broadcaster
  • developer
  • global
   broadcaster_id String The ID of the broadcaster that installed the extension. The object includes this field only if the segment query parameter is set to developer or broadcaster.
   content String The contents of the segment. This string may be a plain-text string or a string-encoded JSON object.
   version String The version number that identifies this definition of the segment’s data.

Response Codes

Code Description
200 OK Successfully retrieved the configurations.
400 Bad Request
  • The extension_id query parameter is required.
  • The value in the segment query parameter is not valid.
  • The broadcaster_id query parameter is required if the segment query parameter is set to broadcaster or developer.
401 Unauthorized
  • The Authorization header is required and must specify a JWT token.
  • The JWT token is not valid.
  • The Client-Id header is required.
429 Too many requests
  • The app exceeded the number of requests that it may make per minute. See Rate Limits above.

Example Request

Gets the global configuration segment from the specified extension. Because the request gets the global segment, it must not include the broadcaster_id query parameter.


curl -X GET 'https://api.twitch.tv/helix/extensions/configurations?extension_id=<your extension id>&segment=global' \
-H 'Authorization: Bearer <your JWT token>' \
-H 'Client-Id: <your client ID>'

Example Response

The following example shows a global segment that contains a plain-text string in the content field.


{
  "data": [
    {
      "segment": "global",
      "content": "hello config!",
      "version": "0.0.1"
    }
  ]
}

The following example shows a global segment that contains a string-encoded JSON object in the content field.


{
  "data": [
    {
      "segment": "global",
      "content": "{\"foo\":\"bar\"}",
      "version": "0.0.1"
    }
  ]
}

Set Extension Configuration Segment

Updates a configuration segment. The segment is limited to 5 KB. Extensions that are active on a channel do not receive the updated configuration.

Rate Limits: You may update the configuration a maximum of 20 times per minute.

Authorization

Requires a signed JSON Web Token (JWT) created by an Extension Backend Service (EBS). For signing requirements, see Signing the JWT. The signed JWT must include the role, user_id, and exp fields (see JWT Schema). The role field must be set to external.

URL

PUT https://api.twitch.tv/helix/extensions/configurations

Request Body

Field Type Required? Description
extension_id String Yes The ID of the extension to update.
segment String Yes The configuration segment to update. Possible case-sensitive values are:
  • broadcaster
  • developer
  • global
broadcaster_id String No The ID of the broadcaster that installed the extension. Include this field only if the segment is set to developer or broadcaster.
content String No The contents of the segment. This string may be a plain-text string or a string-encoded JSON object.
version String No The version number that identifies this definition of the segment’s data. If not specified, the latest definition is updated.

Response Codes

Code Description
204 No Content Successfully updated the configuration.
400 Bad Request
  • The broadcaster_id field is required if segment is set to developer or broadcaster.
401 Unauthorized
  • The Authorization header is required and must specify a JWT token.
  • The JWT token is not valid.
  • The Client-Id header is required.

Example Request

curl -X PUT 'https://api.twitch.tv/helix/extensions/configurations' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Content-Type: application/json' \
-d '{
  "extension_id": "uo6dggojyb8d6soh92zknwmi5ej1q2",
  "segment": "global",
  "version": "0.0.1",
  "content": "hello config!"
}'

Set Extension Required Configuration

Updates the extension’s required_configuration string. Use this endpoint if your extension requires the broadcaster to configure the extension before activating it (to require configuration, you must select Custom/My Own Service in Extension Capabilities). For more information, see Required Configurations and Setting Required Configuration.

Authorization

Requires a signed JSON Web Token (JWT) created by an EBS. For signing requirements, see Signing the JWT. The signed JWT must include the role, user_id, and exp fields (see JWT Schema). Set the role field to external and the user_id field to the ID of the user that owns the extension.

URL

PUT https://api.twitch.tv/helix/extensions/required_configuration

Request Query Parameters

Parameter Type Required? Description
broadcaster_id String Yes The ID of the broadcaster that installed the extension on their channel.

Request Body

Parameter Type Required? Description
extension_id String Yes The ID of the extension to update.
extension_version String Yes The version of the extension to update.
required_configuration String Yes The required_configuration string to use with the extension.

Response Codes

Code Description
204 Not Found Successfully updated the extension’s required_configuration string.
400 Bad Request
  • The broadcaster_id query parameter is required.
  • The extension_id field is required.
  • The extension_version field is required.
  • The required_configuration field is required.
401 Unauthorized
  • The Authorization header is required and must specify a JWT token.
  • The JWT token is not valid.
  • The Client-Id header is required.

Example Request

curl -X PUT 'https://api.twitch.tv/helix/extensions/required_configuration?broadcaster_id=274637212' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Content-Type: application/json' \
-d '{
  "required_configuration": "RCS",
  "extension_id": "uo6dggojyb8d6soh92zknwmi5ej1q2",
  "extension_version": "0.0.1"
}'

Send Extension PubSub Message

Sends a message to one or more viewers. You can send messages to a specific channel or to all channels where your extension is active. This endpoint uses the same mechanism as the send JavaScript helper function used to send messages.

Rate Limits: You may send a maximum of 100 messages per minute per combination of extension client ID and broadcaster ID.

Authorization

Requires a signed JSON Web Token (JWT) created by an Extension Backend Service (EBS). For signing requirements, see Signing the JWT. The signed JWT must include the role, user_id, and exp fields (see JWT Schema) along with the channel_id and pubsub_perms fields. The role field must be set to external.

To send the message to a specific channel, set the channel_id field in the JWT to the channel’s ID and set the pubsub_perms.send array to broadcast.

{
  "exp": 1503343947,
  "user_id": "27419011",
  "role": "external",
  "channel_id": "27419011",
  "pubsub_perms": {
    "send":[
      "broadcast"
    ]
  }
}

To send the message to all channels on which your extension is active, set the channel_id field to all and set the pubsub_perms.send array to global.

{
  "exp": 1503343947,
  "user_id": "27419011",
  "role": "external",
  "channel_id": "all",
  "pubsub_perms": {
    "send":[
      "global"
    ]
  }
}

URL

POST https://api.twitch.tv/helix/extensions/pubsub

Request Body

Field Type Required? Description
target String[] Yes The target of the message. Possible values are:
  • broadcast
  • global
  • whisper-<user-id>
If is_global_broadcast is true, you must set this field to global. The broadcast and global values are mutually exclusive; specify only one of them.
broadcaster_id string Yes The ID of the broadcaster to send the message to. Don’t include this field if is_global_broadcast is set to true.
is_global_broadcast Boolean No A Boolean value that determines whether the message should be sent to all channels where your extension is active. Set to true if the message should be sent to all channels. The default is false.
message String Yes The message to send. The message can be a plain-text string or a string-encoded JSON object. The message is limited to a maximum of 5 KB.

Response Codes

Code Description
204 No Content Successfully sent the message.
400 Bad Request
  • The broadcaster_id field in the request's body may only be set if the is_global_broadcast field is set to false.
401 Unauthorized
  • The Authorization header is required and must specify a JWT token.
  • The JWT token is not valid.
  • The Client-Id header is required.
422 Unprocessable Entity
  • The message is too large.

Example Request

curl -X POST 'https://api.twitch.tv/helix/extensions/pubsub' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Content-Type: application/json' \
-d '{
  "message": "hello world!",
  "broadcaster_id": "141981764",
  "target": ["broadcast"]
}'

Get Extension Live Channels

Gets a list of broadcasters that are streaming live and have installed or activated the extension.

It may take a few minutes for the list to include or remove broadcasters that have recently gone live or stopped broadcasting.

Authorization

Requires an app access token or user access token.

URL

GET https://api.twitch.tv/helix/extensions/live

Request Query Parameters

Parameter Type Required? Description
extension_id String Yes The ID of the extension to get. Returns the list of broadcasters that are live and that have installed or activated this extension.
first Integer No The maximum number of items to return per page in the response. The minimum page size is 1 item per page and the maximum is 100 items per page. The default is 20.
after String No The cursor used to get the next page of results. The pagination field in the response contains the cursor’s value. Read More

Response Body

Field Type Description
data Object[] The list of broadcasters that are streaming live and that have installed or activated the extension.
   broadcaster_id String The ID of the broadcaster that is streaming live and has installed or activated the extension.
   broadcaster_name String The broadcaster’s display name.
   game_name String The name of the category or game being streamed.
   game_id String The ID of the category or game being streamed.
   title String The title of the broadcaster’s stream. May be an empty string if not specified.
pagination String This field contains the cursor used to page through the results. The field is empty if there are no more pages left to page through. Note that this field is a string compared to other endpoints that use a Pagination object. Read More

Response Codes

Code Description
200 OK Successfully retrieved the list of broadcasters.
400 Bad Request
  • The extension_id query parameter is required.
  • The pagination cursor is not valid.
401 Unauthorized
  • The Authorization header is required and must specify an app access token or user access token.
  • The access token is not valid.
  • The ID in the Client-Id header must match the client ID in the access token.
404 Not Found
  • The extension specified in the extension_id query parameter was not found or it's not being used in a live stream.

Example Request

curl -X GET 'https://api.twitch.tv/helix/extensions/live?extension_id=uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
  "data": [
    {
      "broadcaster_id": "252766116",
      "broadcaster_name": "swoosh_xii",
      "game_name": "Tom Clancy's Rainbow Six Siege",
      "game_id": "460630",
      "title": "[PS4] ITA/ENG UNRANKED CHILLIN' (SUB 1/15) - !instagram !donation !sens !team !youtube"
    },
    {
      "broadcaster_id": "264525686",
      "broadcaster_name": "gaddem_",
      "game_name": "For Honor",
      "game_id": "490382",
      "title": "any Kätzchen ? - 680 Rep + > Kompetitive Kitten"
    },
    {
      "broadcaster_id": "264787895",
      "broadcaster_name": "LenhadorGameplay",
      "game_name": "For Honor",
      "game_id": "490382",
      "title": "Vazou o novo personagem! *Triste*"
    }
  ],
  "pagination": "YVc1emRHRnNiQ015TmpJek5qazVOVHBoYWpKbGRIZDFaR0Z5YjNCMGN6UTJNMkZ1TUdwM2FHWnBZbm8yYW5rNjoy"
}

Get Extension Secrets

Gets an extension’s list of shared secrets.

Authorization

Requires a signed JSON Web Token (JWT) created by an Extension Backend Service (EBS). For signing requirements, see Signing the JWT. The signed JWT must include the role, user_id, and exp fields (see JWT Schema). The role field must be set to external.

URL

GET https://api.twitch.tv/helix/extensions/jwt/secrets

Request Query Paramters

Parameter Type Required? Description
extension_id String Yes The ID of the extension whose shared secrets you want to get.

Response Body

Field Type Description
data Object[] The list of shared secrets that the extension created.
   format_version Integer The version number that identifies this definition of the secret’s data.
   secrets Object[] The list of secrets.
      content String The raw secret that you use with JWT encoding.
      active_at String The UTC date and time (in RFC3339 format) that you may begin using this secret to sign a JWT.
      expires_at String The UTC date and time (in RFC3339 format) that you must stop using this secret to decode a JWT.

Response Codes

Code Description
200 OK Successfully retrieved the list of secrets.
400 Bad Request
  • The extension_id query parameter is required.
401 Unauthorized
  • The Authorization header is required and must specify a JWT token.
  • The JWT token is not valid.
  • The Client-Id header is required.

Example Request

curl -X GET 'https://api.twitch.tv/helix/extensions/jwt/secrets?extension_id=uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
  "data": [
    {
      "format_version": 1,
      "secrets": [
        {
          "content": "secret",
          "active_at": "2021-03-29T06:58:40.858343036Z",
          "expires_at": "2121-03-05T06:58:40.858343036Z"
        }
      ]
    }
  ]
}

Create Extension Secret

Creates a shared secret used to sign and verify JWT tokens. Creating a new secret removes the current secrets from service. Use this function only when you are ready to use the new secret it returns.

Authorization

Requires a signed JSON Web Token (JWT) created by an Extension Backend Service (EBS). For signing requirements, see Signing the JWT. The signed JWT must include the role, user_id, and exp fields (see JWT Schema). The role field must be set to external.

URL

POST https://api.twitch.tv/helix/extensions/jwt/secrets

Request Query Parameters

Parameter Type Required? Description
extension_id String Yes The ID of the extension to apply the shared secret to.
delay Integer No The amount of time, in seconds, to delay activating the secret. The delay should provide enough time for instances of the extension to gracefully switch over to the new secret. The minimum delay is 300 seconds (5 minutes). The default is 300 seconds.

Response Body

Field Type Description
data Object[] A list that contains the newly added secrets.
   format_version Integer The version number that identifies this definition of the secret’s data.
   secrets Object[] The list of secrets.
      content String The raw secret that you use with JWT encoding.
      active_at String The UTC date and time (in RFC3339 format) that you may begin using this secret to sign a JWT.
      expires_at String The UTC date and time (in RFC3339 format) that you must stop using this secret to decode a JWT.

Response Codes

Code Description
200 OK Successfully created the new secret.
400 Bad Request
  • The extension_id query parameter is required.
  • The delay specified in the delay query parameter is too short.
401 Unauthorized
  • The Authorization header is required and must specify a JWT token.
  • The JWT token is not valid.
  • The Client-Id header is required.

Example Request

curl -X POST 'https://api.twitch.tv/helix/extensions/jwt/secrets?extension_id=uo6dggojyb8d6soh92zknwmi5ej1q2&delay=600' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
  "data": [
    {
      "format_version": 1,
      "secrets": [
        {
          "content": "old-secret",
          "active_at": "2021-03-29T06:58:40.858343036Z",
          "expires_at": "2021-04-22T05:21:54.99261682Z"
        },
        {
          "content": "new-secret",
          "active_at": "2021-04-22T04:16:54.996365329Z",
          "expires_at": "2121-03-29T04:16:54.996365329Z"
        }
      ]
    }
  ]
}

Send Extension Chat Message

Sends a message to the specified broadcaster’s chat room. The extension’s name is used as the username for the message in the chat room. To send a chat message, your extension must enable Chat Capabilities (under your extension’s Capabilities tab).

Rate Limits: You may send a maximum of 12 messages per minute per channel.

Authorization

Requires a signed JSON Web Token (JWT) created by an Extension Backend Service (EBS). For signing requirements, see Signing the JWT. The signed JWT must include the role and user_id fields (see JWT Schema). The role field must be set to external.

URL

POST https://api.twitch.tv/helix/extensions/chat

Request Query Parameters

Parameter Type Required? Description
broadcaster_id String Yes The ID of the broadcaster that has activated the extension.

Request Body

Field Type Required? Description
text String Yes The message. The message may contain a maximum of 280 characters.
extension_id String Yes The ID of the extension that’s sending the chat message.
extension_version String Yes The extension’s version number.

Response Codes

Code Description
204 No Content Successfully sent the chat message.
400 Bad Request
  • The broadcaster_id query parameter is required.
  • The extension_id field in the request's body is required.
  • The extension_version field in the request's body is required.
  • The text field in the request's body is required.
  • The message is too long.
401 Unauthorized
  • The Authorization header is required and must specify a JWT token.
  • The ID in the broadcaster_id query parameter must match the channel_id claim in the JWT.
  • The JWT token is not valid.
  • The Client-Id header is required.

Example Request

curl -X POST 'https://api.twitch.tv/helix/extensions/chat?broadcaster_id=237757755' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Content-Type: application/json' \
-d '{
  "text": "Hello",
  "extension_id": "uo6dggojyb8d6soh92zknwmi5ej1q2",
  "extension_version": "0.0.9"
}

Get Extensions

Gets information about an extension.

Authorization

Requires a signed JSON Web Token (JWT) created by an Extension Backend Service (EBS). For signing requirements, see Signing the JWT. The signed JWT must include the role field (see JWT Schema), and the role field must be set to external.

URL

GET https://api.twitch.tv/helix/extensions

Request Query Parameters

Parameter Type Required? Description
extension_id String Yes The ID of the extension to get.
extension_version String No The version of the extension to get. If not specified, it returns the latest, released version. If you don’t have a released version, you must specify a version; otherwise, the list is empty.

Response Body

Field Type Description
data Object[] A list that contains the specified extension.
   author_name String The name of the user or organization that owns the extension.
   bits_enabled Boolean A Boolean value that determines whether the extension has features that use Bits. Is true if the extension has features that use Bits.
   can_install Boolean A Boolean value that determines whether a user can install the extension on their channel. Is true if a user can install the extension.

Typically, this is set to false if the extension is currently in testing mode and requires users to be allowlisted (the allowlist is configured on Twitch’s developer site under the Extensions -> Extension -> Version -> Access).
   configuration_location String The location of where the extension’s configuration is stored. Possible values are:
  • hosted — The Extensions Configuration Service hosts the configuration.
  • custom — The Extension Backend Service (EBS) hosts the configuration.
  • none — The extension doesn't require configuration.
   description String A longer description of the extension. It appears on the details page.
   eula_tos_url String A URL to the extension’s Terms of Service.
   has_chat_support Boolean A Boolean value that determines whether the extension can communicate with the installed channel’s chat. Is true if the extension can communicate with the channel’s chat room.
   icon_url String A URL to the default icon that’s displayed in the Extensions directory.
   icon_urls map[string]string A dictionary that contains URLs to different sizes of the default icon. The dictionary’s key identifies the icon’s size (for example, 24x24), and the dictionary’s value contains the URL to the icon.
   id String The extension’s ID.
   name String The extension’s name.
   privacy_policy_url String A URL to the extension’s privacy policy.
   request_identity_link Boolean A Boolean value that determines whether the extension wants to explicitly ask viewers to link their Twitch identity.
   screenshot_urls String[] A list of URLs to screenshots that are shown in the Extensions marketplace.
   state String The extension’s state. Possible values are:
  • Approved
  • AssetsUploaded
  • Deleted
  • Deprecated
  • InReview
  • InTest
  • PendingAction
  • Rejected
  • Released
   subscriptions_support_level String Indicates whether the extension can view the user’s subscription level on the channel that the extension is installed on. Possible values are:
  • none — The extension can't view the user’s subscription level.
  • optional — The extension can view the user’s subscription level.
   summary String A short description of the extension that streamers see when hovering over the discovery splash screen in the Extensions manager.
   support_email String The email address that users use to get support for the extension.
   version String The extension’s version number.
   viewer_summary String A brief description displayed on the channel to explain how the extension works.
   views Object Describes all views-related information such as how the extension is displayed on mobile devices.
      mobile Object Describes how the extension is displayed on mobile devices.
         viewer_url String The HTML file that is shown to viewers on mobile devices. This page is presented to viewers as a panel behind the chat area of the mobile app.
      panel Object Describes how the extension is rendered if the extension may be activated as a panel extension.
         viewer_url String The HTML file that is shown to viewers on the channel page when the extension is activated in a Panel slot.
         height Integer The height, in pixels, of the panel component that the extension is rendered in.
         can_link_external_content Boolean A Boolean value that determines whether the extension can link to non-Twitch domains.
      video_overlay Object Describes how the extension is rendered if the extension may be activated as a video-overlay extension.
         viewer_url String The HTML file that is shown to viewers on the channel page when the extension is activated on the Video - Overlay slot.
         can_link_external_content Boolean A Boolean value that determines whether the extension can link to non-Twitch domains.
      component Object Describes how the extension is rendered if the extension may be activated as a video-component extension.
         viewer_url String The HTML file that is shown to viewers on the channel page when the extension is activated in a Video - Component slot.
         aspect_ratio_x Integer The width value of the ratio (width : height) which determines the extension’s width, and how the extension’s iframe will resize in different video player environments.
         aspect_ratio_y Integer The height value of the ratio (width : height) which determines the extension’s height, and how the extension’s iframe will resize in different video player environments.
         autoscale Boolean A Boolean value that determines whether to apply CSS zoom. If true, a CSS zoom is applied such that the size of the extension is variable but the inner dimensions are fixed based on Scale Pixels. This allows your extension to render as if it is of fixed width and height. If false, the inner dimensions of the extension iframe are variable, meaning your extension must implement responsiveness.
         scale_pixels Integer The base width, in pixels, of the extension to use when scaling (see autoscale). This value is ignored if autoscale is false.
         target_height Integer The height as a percent of the maximum height of a video component extension. Values are between 1% - 100%.
         can_link_external_content Boolean A Boolean value that determines whether the extension can link to non-Twitch domains.
      config Object Describes the view that is shown to broadcasters while they are configuring your extension within the Extension Manager.
         viewer_url String The HTML file shown to broadcasters while they are configuring your extension within the Extension Manager.
         can_link_external_content Boolean A Boolean value that determines whether the extension can link to non-Twitch domains.
   allowlisted_config_urls String[] Allowlisted configuration URLs for displaying the extension (the allowlist is configured on Twitch’s developer site under the Extensions -> Extension -> Version -> Capabilities).
   allowlisted_panel_urls String[] Allowlisted panel URLs for displaying the extension (the allowlist is configured on Twitch’s developer site under the Extensions -> Extension -> Version -> Capabilities).

Response Codes

Code Description
200 OK Sccessfully retrieved the list of extensions.
400 Bad Request
  • The extension_id query parameter is required.
401 Unauthorized
  • The request must specify the Authorization header.
  • The Authorization header is required and must specify a JWT token.
  • The JWT token is not valid.
  • The request must specify the Client-Id header.
404 Not Found
  • The extension in the extension_id query parameter was not found.

Example Request

curl -X GET 'https://api.twitch.tv/helix/extensions?extension_id=uo6dggojyb8d6soh92zknwmi5ej1q2&extension_version=0.0.9' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
  "data": [
    {
      "author_name": "Twitch Developers",
      "bits_enabled": true,
      "can_install": false,
      "configuration_location": "hosted",
      "description": "An extension for testing all the features that we add to extensions",
      "eula_tos_url": "",
      "has_chat_support": true,
      "icon_url": "https://extensions-discovery-images.twitch.tv/pgn0bjv51epi7eaekt53tovjnc82qo/0.0.8/logob6c995d8-8b45-48cc-a748-b256e92ac1cd",
      "icon_urls": {
        "100x100": "https://extensions-discovery-images.twitch.tv/pgn0bjv51epi7eaekt53tovjnc82qo/0.0.8/logob6c995d8-8b45-48cc-a748-b256e92ac1cd",
        "24x24": "https://extensions-discovery-images.twitch.tv/pgn0bjv51epi7eaekt53tovjnc82qo/0.0.8/taskbar905b19da-e7e5-4d8f-beb7-f543a861ac1e",
        "300x200": "https://extensions-discovery-images.twitch.tv/pgn0bjv51epi7eaekt53tovjnc82qo/0.0.8/discoveryd9545b2c-5474-46d7-a523-1c3835d862ce"
      },
      "id": "pgn0bjv51epi7eaekt53tovjnc82qo",
      "name": "Official Developers Demo",
      "privacy_policy_url": "",
      "request_identity_link": true,
      "screenshot_urls": [
        "https://extensions-discovery-images.twitch.tv/pgn0bjv51epi7eaekt53tovjnc82qo/0.0.8/screenshotbdec475d-3d2f-4378-b334-941dfddc897a"
      ],
      "state": "Released",
      "subscriptions_support_level": "optional",
      "summary": "Test ALL the extensions features!",
      "support_email": "dx-extensions-test-dev@justin.tv",
      "version": "0.0.9",
      "viewer_summary": "Test ALL the extensions features!",
      "views": {
        "mobile": {
          "viewer_url": "https://pgn0bjv51epi7eaekt53tovjnc82qo.ext-twitch.tv/pgn0bjv51epi7eaekt53tovjnc82qo/0.0.9/f9a0d8aae0f9dd0b2d6ef3416b96bc79/index.html"
        },
        "panel": {
          "viewer_url": "https://pgn0bjv51epi7eaekt53tovjnc82qo.ext-twitch.tv/pgn0bjv51epi7eaekt53tovjnc82qo/0.0.9/f9a0d8aae0f9dd0b2d6ef3416b96bc79/index.html",
          "height": 300,
          "can_link_external_content": false
        },
        "video_overlay": {
          "viewer_url": "https://pgn0bjv51epi7eaekt53tovjnc82qo.ext-twitch.tv/pgn0bjv51epi7eaekt53tovjnc82qo/0.0.9/f9a0d8aae0f9dd0b2d6ef3416b96bc79/index.html",
          "can_link_external_content": false
        },
        "component": {
          "viewer_url": "https://pgn0bjv51epi7eaekt53tovjnc82qo.ext-twitch.tv/pgn0bjv51epi7eaekt53tovjnc82qo/0.0.9/f9a0d8aae0f9dd0b2d6ef3416b96bc79/index.html",
          "aspect_width": 0,
          "aspect_height": 0,
          "aspect_ratio_x": 48000,
          "aspect_ratio_y": 36000,
          "autoscale": true,
          "scale_pixels": 1024,
          "target_height": 5333,
          "size": 0,
          "zoom": false,
          "zoom_pixels": 0,
          "can_link_external_content": false
        }
      },
      "allowlisted_config_urls": [],
      "allowlisted_panel_urls": []
    }
  ]
}

Get Released Extensions

Gets information about a released extension. Returns extensions whose state is Released.

Authorization

Requires an app access token or user access token.

URL

GET https://api.twitch.tv/helix/extensions/released

Request Query Parameters

Parameter Type Required? Description
extension_id String Yes The ID of the extension to get.
extension_version String No The version of the extension to get. If not specified, it returns the latest version.

Response Body

Field Type Description
data Object[] A list that contains the specified extension.
   author_name String The name of the user or organization that owns the extension.
   bits_enabled Boolean A Boolean value that determines whether the extension has features that use Bits. Is true if the extension has features that use Bits.
   can_install Boolean A Boolean value that determines whether a user can install the extension on their channel. Is true if a user can install the extension.

Typically, this is set to false if the extension is currently in testing mode and requires users to be allowlisted (the allowlist is configured on Twitch’s developer site under the Extensions -> Extension -> Version -> Access).
   configuration_location String The location of where the extension’s configuration is stored. Possible values are:
  • hosted — The Extensions Configuration Service hosts the configuration.
  • custom — The Extension Backend Service (EBS) hosts the configuration.
  • none — The extension doesn't require configuration.
   description String A longer description of the extension. It appears on the details page.
   eula_tos_url String A URL to the extension’s Terms of Service.
   has_chat_support Boolean A Boolean value that determines whether the extension can communicate with the installed channel’s chat. Is true if the extension can communicate with the channel’s chat room.
   icon_url String A URL to the default icon that’s displayed in the Extensions directory.
   icon_urls map[string]string A dictionary that contains URLs to different sizes of the default icon. The dictionary’s key identifies the icon’s size (for example, 24x24), and the dictionary’s value contains the URL to the icon.
   id String The extension’s ID.
   name String The extension’s name.
   privacy_policy_url String A URL to the extension’s privacy policy.
   request_identity_link Boolean A Boolean value that determines whether the extension wants to explicitly ask viewers to link their Twitch identity.
   screenshot_urls String[] A list of URLs to screenshots that are shown in the Extensions marketplace.
   state String The extension’s state. Possible values are:
  • Approved
  • AssetsUploaded
  • Deleted
  • Deprecated
  • InReview
  • InTest
  • PendingAction
  • Rejected
  • Released
   subscriptions_support_level String Indicates whether the extension can view the user’s subscription level on the channel that the extension is installed on. Possible values are:
  • none — The extension can't view the user’s subscription level.
  • optional — The extension can view the user’s subscription level.
   summary String A short description of the extension that streamers see when hovering over the discovery splash screen in the Extensions manager.
   support_email String The email address that users use to get support for the extension.
   version String The extension’s version number.
   viewer_summary String A brief description displayed on the channel to explain how the extension works.
   views Object Describes all views-related information such as how the extension is displayed on mobile devices.
      mobile Object Describes how the extension is displayed on mobile devices.
         viewer_url String The HTML file that is shown to viewers on mobile devices. This page is presented to viewers as a panel behind the chat area of the mobile app.
      panel Object Describes how the extension is rendered if the extension may be activated as a panel extension.
         viewer_url String The HTML file that is shown to viewers on the channel page when the extension is activated in a Panel slot.
         height Integer The height, in pixels, of the panel component that the extension is rendered in.
         can_link_external_content Boolean A Boolean value that determines whether the extension can link to non-Twitch domains.
      video_overlay Object Describes how the extension is rendered if the extension may be activated as a video-overlay extension.
         viewer_url String The HTML file that is shown to viewers on the channel page when the extension is activated on the Video - Overlay slot.
         can_link_external_content Boolean A Boolean value that determines whether the extension can link to non-Twitch domains.
      component Object Describes how the extension is rendered if the extension may be activated as a video-component extension.
         viewer_url String The HTML file that is shown to viewers on the channel page when the extension is activated in a Video - Component slot.
         aspect_ratio_x Integer The width value of the ratio (width : height) which determines the extension’s width, and how the extension’s iframe will resize in different video player environments.
         aspect_ratio_y Integer The height value of the ratio (width : height) which determines the extension’s height, and how the extension’s iframe will resize in different video player environments.
         autoscale Boolean A Boolean value that determines whether to apply CSS zoom. If true, a CSS zoom is applied such that the size of the extension is variable but the inner dimensions are fixed based on Scale Pixels. This allows your extension to render as if it is of fixed width and height. If false, the inner dimensions of the extension iframe are variable, meaning your extension must implement responsiveness.
         scale_pixels Integer The base width, in pixels, of the extension to use when scaling (see autoscale). This value is ignored if autoscale is false.
         target_height Integer The height as a percent of the maximum height of a video component extension. Values are between 1% - 100%.
         can_link_external_content Boolean A Boolean value that determines whether the extension can link to non-Twitch domains.
      config Object Describes the view that is shown to broadcasters while they are configuring your extension within the Extension Manager.
         viewer_url String The HTML file shown to broadcasters while they are configuring your extension within the Extension Manager.
         can_link_external_content Boolean A Boolean value that determines whether the extension can link to non-Twitch domains.
   allowlisted_config_urls String[] Allowlisted configuration URLs for displaying the extension (the allowlist is configured on Twitch’s developer site under the Extensions -> Extension -> Version -> Capabilities).
   allowlisted_panel_urls String[] Allowlisted panel URLs for displaying the extension (the allowlist is configured on Twitch’s developer site under the Extensions -> Extension -> Version -> Capabilities).

Response Codes

Code Description
200 OK Successfully retrieved the extension.
400 Bad Request
  • The extension_id query parameter is required.
401 Unauthorized
  • The Authorization header must specify an app access token or user access token.
  • The access token is not valid.
  • The ID in the Client-Id header must match the client ID in the access token.
404 Not Found
  • The extension specified in the extension_id query parameter was not found or is not released.

Example Request

curl -X GET 'https://api.twitch.tv/helix/extensions/released?extension_version=0.0.9&extension_id=uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
  "data": [
    {
      "author_name": "Twitch Developer Experience",
      "bits_enabled": true,
      "can_install": false,
      "configuration_location": "hosted",
      "description": "An extension for testing all the features that we add to extensions",
      "eula_tos_url": "",
      "has_chat_support": true,
      "icon_url": "https://extensions-discovery-images.twitch.tv/pgn0bjv51epi7eaekt53tovjnc82qo/0.0.8/logob6c995d8-8b45-48cc-a748-b256e92ac1cd",
      "icon_urls": {
        "100x100": "https://extensions-discovery-images.twitch.tv/pgn0bjv51epi7eaekt53tovjnc82qo/0.0.8/logob6c995d8-8b45-48cc-a748-b256e92ac1cd",
        "24x24": "https://extensions-discovery-images.twitch.tv/pgn0bjv51epi7eaekt53tovjnc82qo/0.0.8/taskbar905b19da-e7e5-4d8f-beb7-f543a861ac1e",
        "300x200": "https://extensions-discovery-images.twitch.tv/pgn0bjv51epi7eaekt53tovjnc82qo/0.0.8/discoveryd9545b2c-5474-46d7-a523-1c3835d862ce"
      },
      "id": "pgn0bjv51epi7eaekt53tovjnc82qo",
      "name": "Official Developer Experience Demo",
      "privacy_policy_url": "",
      "request_identity_link": true,
      "screenshot_urls": [
        "https://extensions-discovery-images.twitch.tv/pgn0bjv51epi7eaekt53tovjnc82qo/0.0.8/screenshotbdec475d-3d2f-4378-b334-941dfddc897a"
      ],
      "state": "Released",
      "subscriptions_support_level": "optional",
      "summary": "Test ALL the extensions features!",
      "support_email": "dx-extensions-test-dev@justin.tv",
      "version": "0.0.9",
      "viewer_summary": "Test ALL the extensions features!",
      "views": {
        "mobile": {
          "viewer_url": "https://pgn0bjv51epi7eaekt53tovjnc82qo.ext-twitch.tv/pgn0bjv51epi7eaekt53tovjnc82qo/0.0.9/f9a0d8aae0f9dd0b2d6ef3416b96bc79/index.html"
        },
        "panel": {
          "viewer_url": "https://pgn0bjv51epi7eaekt53tovjnc82qo.ext-twitch.tv/pgn0bjv51epi7eaekt53tovjnc82qo/0.0.9/f9a0d8aae0f9dd0b2d6ef3416b96bc79/index.html",
          "height": 300,
          "can_link_external_content": false
        },
        "video_overlay": {
          "viewer_url": "https://pgn0bjv51epi7eaekt53tovjnc82qo.ext-twitch.tv/pgn0bjv51epi7eaekt53tovjnc82qo/0.0.9/f9a0d8aae0f9dd0b2d6ef3416b96bc79/index.html",
          "can_link_external_content": false
        },
        "component": {
          "viewer_url": "https://pgn0bjv51epi7eaekt53tovjnc82qo.ext-twitch.tv/pgn0bjv51epi7eaekt53tovjnc82qo/0.0.9/f9a0d8aae0f9dd0b2d6ef3416b96bc79/index.html",
          "aspect_width": 0,
          "aspect_height": 0,
          "aspect_ratio_x": 48000,
          "aspect_ratio_y": 36000,
          "autoscale": true,
          "scale_pixels": 1024,
          "target_height": 5333,
          "size": 0,
          "zoom": false,
          "zoom_pixels": 0,
          "can_link_external_content": false
        }
      },
      "allowlisted_config_urls": [],
      "allowlisted_panel_urls": []
    }
  ]
}

Get Extension Bits Products

Gets the list of Bits products that belongs to the extension. The client ID in the app access token identifies the extension.

Authorization

Requires an app access token. The client ID in the app access token must be the extension’s client ID.

URL

GET https://api.twitch.tv/helix/bits/extensions

Request Query Parameters

Parameter Type Required? Description
should_include_all Boolean No A Boolean value that determines whether to include disabled or expired Bits products in the response. The default is false.

Response Body

Field Type Description
data Object[] A list of Bits products that the extension created. The list is in ascending SKU order. The list is empty if the extension hasn’t created any products or they’re all expired or disabled.
   sku String The product’s SKU. The SKU is unique across an extension’s products.
   cost Object An object that contains the product’s cost information.
      amount Integer The product’s price.
      type String The type of currency. Possible values are:
  • bits
   in_development Boolean A Boolean value that indicates whether the product is in development. If true, the product is not available for public use.
   display_name String The product’s name as displayed in the extension.
   expiration String The date and time, in RFC3339 format, when the product expires.
   is_broadcast Boolean A Boolean value that determines whether Bits product purchase events are broadcast to all instances of an extension on a channel. The events are broadcast via the onTransactionComplete helper callback. Is true if the event is broadcast to all instances.

Response Codes

Code Description
200 OK Successfully retrieved the list of products.
400 Bad Request
  • The ID in the Client-Id header must belong to an extension.
401 Unauthorized
  • The Authorization header is required and must specify an app access token; you may not specify a user access token.
  • The OAuth token is not valid.
  • The ID in the Client-Id header must match the Client ID in the OAuth token.

Example Request

Gets the extension’s products including its disabled and expired products.

curl -X GET 'https://api.twitch.tv/helix/bits/extensions?should_include_all=true' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
  "data": [
    {
      "sku": "1010",
      "cost": {
        "amount": 990,
        "type": "bits"
      },
      "in_development": true,
      "display_name": "Rusty Crate 2",
      "expiration": "2021-05-18T09:10:13.397Z",
      "is_broadcast": false
    }
  ]
}

Update Extension Bits Product

Adds or updates a Bits product that the extension created. If the SKU doesn’t exist, the product is added. You may update all fields except the sku field.

Authorization

Requires an app access token. The client ID in the app access token must be the extension’s client ID.

URL

PUT https://api.twitch.tv/helix/bits/extensions

Request Body Parameters

Parameter Type Required? Description
sku String Yes The product’s SKU. The SKU must be unique within an extension. The product’s SKU cannot be changed. The SKU may contain only alphanumeric characters, dashes (-), underscores (_), and periods (.) and is limited to a maximum of 255 characters. No spaces.
cost Object Yes An object that contains the product’s cost information.
   amount Integer Yes The product’s price.
   type String Yes The type of currency. Possible values are:
  • bits — The minimum price is 1 and the maximum is 10000.
display_name String Yes The product’s name as displayed in the extension. The maximum length is 255 characters.
in_development Boolean No A Boolean value that indicates whether the product is in development. Set to true if the product is in development and not available for public use. The default is false.
expiration String No The date and time, in RFC3339 format, when the product expires. If not set, the product does not expire. To disable the product, set the expiration date to a date in the past.
is_broadcast Boolean No A Boolean value that determines whether Bits product purchase events are broadcast to all instances of the extension on a channel. The events are broadcast via the onTransactionComplete helper callback. The default is false.

Response Body

Field Type Description
data Object[] A list of Bits products that the extension created. The list is in ascending SKU order. The list is empty if the extension hasn’t created any products or they’re all expired or disabled.
   sku String The product’s SKU. The SKU is unique across an extension’s products.
   cost Object An object that contains the product’s cost information.
      amount Integer The product’s price.
      type String The type of currency. Possible values are:
  • bits
   in_development Boolean A Boolean value that indicates whether the product is in development. If true, the product is not available for public use.
   display_name String The product’s name as displayed in the extension.
   expiration String The date and time, in RFC3339 format, when the product expires.
   is_broadcast Boolean A Boolean value that determines whether Bits product purchase events are broadcast to all instances of an extension on a channel. The events are broadcast via the onTransactionComplete helper callback. Is true if the event is broadcast to all instances.

Response Codes

Code Description
200 OK Successfully created the product.
400 Bad Request
  • The sku field is required.
  • The value in the sku field is not valid. The SKU may contain only alphanumeric characters, dashes (-), underscores (_), and periods (.).
  • The cost object's amount field is required.
  • The value in the cost object's amount field is not valid.
  • The cost object's type field is required.
  • The value in the cost object's type field is not valid.
  • The display_name field is required.
  • The ID in the Client-Id header must belong to the extension.
401 Unauthorized
  • The Authorization header is required and must specify an app access token; you may not specify a user access token.
  • The OAuth token is not valid.
  • The ID in the Client-Id header must match the Client ID in the OAuth token.

Example Request

curl -X PUT 'https://api.twitch.tv/helix/bits/extensions' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Content-Type: application/json' \
-d {
  "sku": "1010",
  "cost": {
    "amount": 990,
    "type": "bits"
  },
  "in_development": true,
  "display_name": "Rusty Crate 2",
  "is_broadcast": true,
  "expiration": "2021-05-18T09:10:13.397Z"
}

Example Response

{
  "data": [
    {
      "sku": "1010",
      "cost": {
        "amount": 990,
        "type": "bits"
      },
      "in_development": true,
      "display_name": "Rusty Crate 2",
      "expiration": "2021-05-18T09:10:13.397Z",
      "is_broadcast": true
    }
  ]
}

Create EventSub Subscription

Creates an EventSub subscription.

Authentication

If you use webhooks to receive events, the request must specify an app access token. The request will fail if you use a user access token. If the subscription type requires user authorization, the user must have granted your app (client ID) permissions to receive those events before you subscribe to them. For example, to subscribe to channel.subscribe events, your app must get a user access token that includes the channel:read:subscriptions scope, which adds the required permission to your app access token’s client ID.

If you use WebSockets to receive events, the request must specify a user access token. The request will fail if you use an app access token. If the subscription type requires user authorization, the token must include the required scope. However, if the subscription type doesn’t include user authorization, the token may include any scopes or no scopes.

URL

POST https://api.twitch.tv/helix/eventsub/subscriptions

Request Body

Field Type Required? Description
type String Yes The type of subscription to create. For a list of subscriptions that you can create, see Subscription Types. Set this field to the value in the Name column of the Subscription Types table.
version String Yes The version number that identifies the definition of the subscription type that you want the response to use.
condition Object Yes A JSON object that contains the parameter values that are specific to the specified subscription type. For the object’s required and optional fields, see the subscription type’s documentation.
transport Object Yes The transport details that you want Twitch to use when sending you notifications.
   method String Yes The transport method. Possible values are:
  • webhook
  • websocket
   callback String No The callback URL where the notifications are sent. The URL must use the HTTPS protocol and port 443. See Processing an event.

Specify this field only if method is set to webhook.

NOTE: Redirects are not followed.
   secret String No The secret used to verify the signature. The secret must be an ASCII string that’s a minimum of 10 characters long and a maximum of 100 characters long. For information about how the secret is used, see Verifying the event message.

Specify this field only if method is set to webhook.
   session_id String No An ID that identifies the WebSocket to send notifications to. When you connect to EventSub using WebSockets, the server returns the ID in the Welcome message.

Specify this field only if method is set to websocket.

Response Body

Field Type Description
data Object[] A list that contains the single subscription that you created.
   id String An ID that identifies the subscription.
   status String The subscription’s status. Possible values are:
  • enabled — The subscription is enabled.
  • webhook_callback_verification_pending — The subscription is pending verification of the specified callback URL.
  • webhook_callback_verification_failed — The specified callback URL failed verification.
  • notification_failures_exceeded — The notification delivery failure rate was too high.
  • authorization_revoked — The authorization was revoked for one or more users specified in the Condition object.
  • user_removed — One of the users specified in the Condition object was removed.
  • version_removed — The subscribed to subscription type and version is no longer supported.
   type String The subscription’s type. See Subscription Types.
   version String The version number that identifies this definition of the subscription’s data.
   condition Object The subscription’s parameter values. This is a string-encoded JSON object whose contents are determined by the subscription type.
   created_at String The date and time (in RFC3339 format) of when the subscription was created.
   transport Object The transport details used to send the notifications.
      method String The transport method. Possible values are:
  • webhook
  • websocket
      callback String The callback URL where the notifications are sent. Included only if method is set to webhook.
      session_id String An ID that identifies the WebSocket that notifications are sent to. Included only if method is set to websocket.
      connected_at String The UTC date and time that the WebSocket connection was established. Included only if method is set to websocket.
   cost Integer The amount that the subscription counts against your limit. Learn More
total Integer The total number of subscriptions you’ve created.
total_cost Integer The sum of all of your subscription costs. Learn More
max_total_cost Integer The maximum total cost that you’re allowed to incur for all subscriptions you create.

Response Codes

Code Description
202 Accepted Successfully accepted the subscription request.
400 Bad Request
  • The condition field is required.
  • The user specified in the condition object does not exist.
  • The condition object is missing one or more required fields.
  • The combination of values in the version and type fields is not valid.
  • The length of the string in the secret field is not valid.
  • The URL in the transport's callback field is not valid. The URL must use the HTTPS protocol and the 443 port number.
  • The value specified in the method field is not valid.
  • The callback field is required if you specify the webhook transport method.
  • The session_id field is required if you specify the WebSocket transport method.
  • The combination of subscription type and version is not valid.
401 Unauthorized
  • The Authorization header is required and must specify an app access token if the transport method is webhook.
  • The Authorization header is required and must specify a user access token if the transport method is WebSocket.
  • The access token is not valid.
  • The ID in the Client-Id header must match the client ID in the access token.
403 Forbidden
  • The access token is missing the required scopes.
409 Conflict
  • A subscription already exists for the specified event type and condition combination.
429 Too Many Requests
  • The request exceeds the number of subscriptions that you may create with the same combination of type and condition values.

Example Request

Adds a user.update subscription.

curl -X POST 'https://api.twitch.tv/helix/eventsub/subscriptions' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz' \
-H 'Content-Type: application/json' \
-d '{"type":"user.update","version":"1","condition":{"user_id":"1234"},"transport":{"method":"webhook","callback":"https://this-is-a-callback.com","secret":"s3cre7"}}' 
# Twitch CLI example that adds a user.update subscription.

twitch api post /eventsub/subscriptions -b '{"type":"user.update","version":"1","condition":{"user_id":"1234"},"transport":{"method":"webhook","callback":"https://this-is-a-callback.com","secret":"s3cre7"}}'

Example Response


{
  "data": [
    {
      "id": "26b1c993-bfcf-44d9-b876-379dacafe75a",
      "status": "webhook_callback_verification_pending",
      "type": "user.update",
      "version": "1",
      "condition": {
        "user_id": "1234"
      },
      "created_at": "2020-11-10T14:32:18.730260295Z",
      "transport": {
        "method": "webhook",
        "callback": "https://this-is-a-callback.com"
      },
      "cost": 1
    }
  ],
  "total": 1,
  "total_cost": 1,
  "max_total_cost": 10000
}

Delete EventSub Subscription

Deletes an EventSub subscription.

Authentication

If you use webhooks to receive events, the request must specify an app access token. The request will fail if you use a user access token.

If you use WebSockets to receive events, the request must specify a user access token. The request will fail if you use an app access token. The token may include any scopes.

URL

DELETE https://api.twitch.tv/helix/eventsub/subscriptions

Request Query Parameters

Parameter Type Required? Description
id String Yes The ID of the subscription to delete.

Response Codes

Code Description
204 No Content Successfully deleted the subscription.
400 Bad Request
  • The id query parameter is required.
401 Unauthorized
  • The Authorization header is required and must specify an app access token.
  • The access token is not valid.
  • The ID in the Client-Id header must match the client ID in the access token.
404 Not Found
  • The subscription was not found.

Example Request

Deletes the specified EventSub subscription.

curl -X DELETE
'https://api.twitch.tv/helix/eventsub/subscriptions?id=26b1c993-bfcf-44d9-b876-379dacafe75a' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz' 
# Twitch CLI example that deletes the specified subscription.

twitch api delete /eventsub/subscriptions -q id=c839a466-034a-4d77-8d4d-c9a751516e7

Get EventSub Subscriptions

Gets a list of EventSub subscriptions that the client in the access token created.

Authentication

If you use webhooks to receive events, the request must specify an app access token. The request will fail if you use a user access token.

If you use WebSockets to receive events, the request must specify a user access token. The request will fail if you use an app access token. The token may include any scopes.

URL

GET https://api.twitch.tv/helix/eventsub/subscriptions

Request Query Parameters

Use the status, type, and user_id query parameters to filter the list of subscriptions that are returned. The filters are mutually exclusive; the request fails if you specify more than one filter.

Parameter Type Required? Description
status String No Filter subscriptions by its status. Possible values are:
  • enabled — The subscription is enabled.
  • webhook_callback_verification_pending — The subscription is pending verification of the specified callback URL.
  • webhook_callback_verification_failed — The specified callback URL failed verification.
  • notification_failures_exceeded — The notification delivery failure rate was too high.
  • authorization_revoked — The authorization was revoked for one or more users specified in the Condition object.
  • user_removed — One of the users specified in the Condition object was removed.
  • version_removed — The subscribed to subscription type and version is no longer supported.
type String No Filter subscriptions by subscription type. For a list of subscription types, see Subscription Types.
user_id String No Filter subscriptions by user ID. The response contains subscriptions where this ID matches a user ID that you specified in the Condition object when you created the subscription.
after String No The cursor used to get the next page of results. The pagination object in the response contains the cursor’s value.

Response Body

Field Type Description
data Object[] The list of subscriptions. The list is ordered by the oldest subscription first. The list is empty if the client hasn’t created subscriptions or there are no subscriptions that match the specified filter criteria.
   id String An ID that identifies the subscription.
   status String The subscription’s status. Possible values are:
  • enabled — The subscription is enabled.
  • webhook_callback_verification_pending — The subscription is pending verification of the specified callback URL.
  • webhook_callback_verification_failed — The specified callback URL failed verification.
  • notification_failures_exceeded — The notification delivery failure rate was too high.
  • authorization_revoked — The authorization was revoked for one or more users specified in the Condition object.
  • user_removed — One of the users specified in the Condition object was removed.
   type String The subscription’s type. See Subscription Types.
   version String The version number that identifies this definition of the subscription’s data.
   condition Object The subscription’s parameter values. This is a string-encoded JSON object whose contents are determined by the subscription type.
   created_at String The date and time (in RFC3339 format) of when the subscription was created.
   transport Object The transport details used to send the notifications.
      method String The transport method. Possible values are:
  • webhook
  • websocket
      callback String The callback URL where the notifications are sent. Included only if method is set to webhook.
      session_id String An ID that identifies the WebSocket that notifications are sent to. Included only if method is set to websocket.
      connected_at String The UTC date and time that the WebSocket connection was established. Included only if method is set to websocket.
      disconnected_at String The UTC date and time that the WebSocket connection was lost. Included only if method is set to websocket.
   cost Integer The amount that the subscription counts against your limit. Learn More
total Integer The total number of subscriptions that you’ve created.
total_cost Integer The sum of all of your subscription costs. Learn More
max_total_cost Integer The maximum total cost that you’re allowed to incur for all subscriptions that you create.
pagination Object An object that contains the cursor used to get the next page of subscriptions. The object is empty if there are no more pages to get. The number of subscriptions returned per page is undertermined.
   cursor String The cursor value that you set the after query parameter to.

Response Codes

Code Description
200 OK Successfully retrieved the subscriptions.
400 Bad Request
  • The request may specify only one filter query parameter. For example, either type or status or user_id.
  • The value in the type query parameter is not valid.
  • The value in the status query parameter is not valid.
  • The cursor specified in the after query parameter is not valid.
401 Unauthorized
  • The Authorization header is required and must specify an app access token.
  • The access token is not valid.
  • The ID in the Client-Id header must match the client ID in the access token.

Example Request

Gets a list of EventSub subscriptions that you created. The list is ordered by the oldest subscription first.

curl -X GET 'https://api.twitch.tv/helix/eventsub/subscriptions' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz' 
# Twitch CLI example that gets a list of EventSub subscriptions that you created.

twitch api get /eventsub/subscriptions 

Example Response

{
  "total": 2,
  "data": [
    {
      "id": "26b1c993-bfcf-44d9-b876-379dacafe75a",
      "status": "enabled",
      "type": "stream.online",
      "version": "1",
      "condition": {
        "broadcaster_user_id": "1234"
      },
      "created_at": "2020-11-10T20:08:33.12345678Z",
      "transport": {
        "method": "webhook",
        "callback": "https://this-is-a-callback.com"
      },
      "cost": 1
    },
    {
      "id": "35016908-41ff-33ce-7879-61b8dfc2ee16",
      "status": "webhook_callback_verification_pending",
      "type": "user.update",
      "version": "1",
      "condition": {
        "user_id": "1234"
      },
      "created_at": "2020-11-10T14:32:18.730260295Z",
      "transport": {
        "method": "webhook",
        "callback": "https://this-is-a-callback.com"
      },
      "cost": 0
    }
  ],
  "total_cost": 1,
  "max_total_cost": 10000,
  "pagination": {}
}

Get Top Games

Gets information about all broadcasts on Twitch.

Authentication

Requires an app access token or user access token.

URL

GET https://api.twitch.tv/helix/games/top

Request Query Parameters

Parameter Type Required ? Description
first Integer No The maximum number of items to return per page in the response. The minimum page size is 1 item per page and the maximum is 100 items per page. The default is 20.
after String No The cursor used to get the next page of results. The Pagination object in the response contains the cursor’s value. Read More
before String No The cursor used to get the previous page of results. The Pagination object in the response contains the cursor’s value. Read More

Response Body

Fields Type Description
data Object[] The list of broadcasts. The broadcasts are sorted by the number of viewers, with the most popular first.
   id String An ID that identifies the category or game.
   name String The category’s or game’s name.
   box_art_url String A URL to the category’s or game’s box art. You must replace the {width}x{height} placeholder with the size of image you want.
   igdb_id String The ID that IGDB uses to identify this game. If the IGDB ID is not available to Twitch, this field is set to an empty string.
pagination Object Contains the information used to page through the list of results. The object is empty if there are no more pages left to page through. Read More
   cursor String The cursor used to get the next page of results. Use the cursor to set the request’s after or before query parameter to get the next or previous page of results.

Response Codes

Code Description
200 OK Successfully retrieved the list of broadcasts.
400 Bad Request
  • The value in the first query parameter is not valid.
  • The cursor in the after or before query parameter is not valid.
401 Unauthorized
  • The Authorization header is required and must specify an app access token or user access token.
  • The access token is not valid.
  • The ID in the Client-Id header must match the client ID in the access token.

Example Request

curl -X GET 'https://api.twitch.tv/helix/games/top' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
  "data": [
    {
      "id": "493057",
      "name": "PUBG: BATTLEGROUNDS",
      "box_art_url": "https://static-cdn.jtvnw.net/ttv-boxart/493057-{width}x{height}.jpg",
      "igdb_id": "27789"
    },
    ...
  ],
  "pagination":{"cursor":"eyJiIjpudWxsLCJhIjp7Ik9mZnNldCI6MjB9fQ=="}
}

Get Games

Gets information about specified categories or games.

You may get up to 100 categories or games by specifying their ID or name. You may specify all IDs, all names, or a combination of IDs and names. If you specify a combination of IDs and names, the total number of IDs and names must not exceed 100.

Authentication

Requires an app access token or user access token.

URL

GET https://api.twitch.tv/helix/games

Request Query Parameters

Parameter Type Required? Description
id String Yes The ID of the category or game to get. Include this parameter for each category or game you want to get. For example, &id=1234&id=5678. You may specify a maximum of 100 IDs. The endpoint ignores duplicate and invalid IDs or IDs that weren’t found.
name String Yes The name of the category or game to get. The name must exactly match the category’s or game’s title. Include this parameter for each category or game you want to get. For example, &name=foo&name=bar. You may specify a maximum of 100 names. The endpoint ignores duplicate names and names that weren’t found.
igdb_id String Yes The IGDB ID of the game to get. Include this parameter for each game you want to get. For example, &igdb_id=1234&igdb_id=5678. You may specify a maximum of 100 IDs. The endpoint ignores duplicate and invalid IDs or IDs that weren’t found.

Response Body

Fields Type Description
data Object[] The list of categories and games. The list is empty if the specified categories and games weren’t found.
   id String An ID that identifies the category or game.
   name String The category’s or game’s name.
   box_art_url String A URL to the category’s or game’s box art. You must replace the {width}x{height} placeholder with the size of image you want.
   igdb_id String The ID that IGDB uses to identify this game. If the IGDB ID is not available to Twitch, this field is set to an empty string.

Response Codes

Code Description
200 OK Successfully retrieved the specified games.
400 Bad Request
  • The request must specify the id or name or igdb_id query parameter.
  • The combined number of game IDs (id and igdb_id) and game names that you specify in the request must not exceed 100.
401 Unauthorized
  • The Authorization header is required and must specify an app access token or user access token.
  • The access token is not valid.
  • The ID in the Client-Id header must match the client ID in the access token.

Example Request

curl -X GET 'https://api.twitch.tv/helix/games?id=33214' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
  "data": [
    {
      "id": "33214",
      "name": "Fortnite",
      "box_art_url": "https://static-cdn.jtvnw.net/ttv-boxart/33214-{width}x{height}.jpg",
      "igdb_id": "1905"
    }
    ...
  ],
  "pagination": {
    "cursor": "eyJiIjpudWxsLCJhIjp7IkN"
  }
}

Get Creator Goals

Gets the broadcaster’s list of active goals. Use this endpoint to get the current progress of each goal.

Instead of polling for the progress of a goal, consider subscribing to receive notifications when a goal makes progress using the channel.goal.progress subscription type. Read More

Authorization

Requires a user access token that includes the channel:read:goals scope.

URL

GET https://api.twitch.tv/helix/goals

Request Query Parameters

Parameter Type Required? Description
broadcaster_id String Yes The ID of the broadcaster that created the goals. This ID must match the user ID in the user access token.

Response Body

Field Type Description
data Object[] The list of goals. The list is empty if the broadcaster hasn’t created goals.
   id String An ID that identifies this goal.
   broadcaster_id String An ID that identifies the broadcaster that created the goal.
   broadcaster_name String The broadcaster’s display name.
   broadcaster_login String The broadcaster’s login name.
   type String The type of goal. Possible values are:
  • follower — The goal is to increase followers.
  • subscription — The goal is to increase subscriptions. This type shows the net increase or decrease in tier points associated with the subscriptions.
  • subscription_count — The goal is to increase subscriptions. This type shows the net increase or decrease in the number of subscriptions.
  • new_subscription — The goal is to increase subscriptions. This type shows only the net increase in tier points associated with the subscriptions (it does not account for users that unsubscribed since the goal started).
  • new_subscription_count — The goal is to increase subscriptions. This type shows only the net increase in the number of subscriptions (it does not account for users that unsubscribed since the goal started).
   description String A description of the goal. Is an empty string if not specified.
   current_amount Integer The goal’s current value.

The goal’s type determines how this value is increased or decreased.
  • If type is follower, this field is set to the broadcaster's current number of followers. This number increases with new followers and decreases when users unfollow the broadcaster.
  • If type is subscription, this field is increased and decreased by the points value associated with the subscription tier. For example, if a tier-two subscription is worth 2 points, this field is increased or decreased by 2, not 1.
  • If type is subscription_count, this field is increased by 1 for each new subscription and decreased by 1 for each user that unsubscribes.
  • If type is new_subscription, this field is increased by the points value associated with the subscription tier. For example, if a tier-two subscription is worth 2 points, this field is increased by 2, not 1.
  • If type is new_subscription_count, this field is increased by 1 for each new subscription.
   target_amount Integer The goal’s target value. For example, if the broadcaster has 200 followers before creating the goal, and their goal is to double that number, this field is set to 400.
   created_at string The UTC date and time (in RFC3339 format) that the broadcaster created the goal.

Response Codes

Code Description
200 OK Successfully retrieved the broadcaster’s goals.
400 Bad Request
  • The broadcaster_id query parameter is required.
401 Unauthorized
  • The Authorization header is required and must contain a user access token.
  • The user access token must include the channel:read:goals scope.
  • The ID in broadcaster_id must match the user ID in the user access token.
  • The access token is not valid.
  • The client ID specified in the Client-Id header does not match the client ID specified in the access token.

Example Request

curl -X GET 'https://api.twitch.tv/helix/goals?broadcaster_id=141981764' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' 
# Twitch CLI example that gets the broadcaster's goals.

twitch api get /goals -q broadcaster_id=141981764 

Example Response

{
  "data": [
    {
      "id": "1woowvbkiNv8BRxEWSqmQz6Zk92",
      "broadcaster_id": "141981764",
      "broadcaster_name": "TwitchDev",
      "broadcaster_login": "twitchdev",
      "type": "follower",
      "description": "Follow goal for Helix testing",
      "current_amount": 27062,
      "target_amount": 30000,
      "created_at": "2021-08-16T17:22:23Z"
    }
  ]
}

Get Hype Train Events

Gets information about the broadcaster’s current or most recent Hype Train event.

Instead of polling for events, consider subscribing to Hype Train events (Begin, Progress, End).

Authentication

Requires a user access token that includes the channel:read:hype_train scope.

URL

GET https://api.twitch.tv/helix/hypetrain/events

Request Query Parameters

Parameter Type Required? Description
broadcaster_id String Yes The ID of the broadcaster that’s running the Hype Train. This ID must match the User ID in the user access token.
first Integer No The maximum number of items to return per page in the response. The minimum page size is 1 item per page and the maximum is 100 items per page. The default is 1.
after String No The cursor used to get the next page of results. The Pagination object in the response contains the cursor’s value. Read More

Response Body

Field Type Description
data Object[] The list of Hype Train events. The list is empty if the broadcaster hasn’t run a Hype Train within the last 5 days.
   id String An ID that identifies this event.
   event_type String The type of event. The string is in the form, hypetrain.{event_name}. The request returns only progress event types (i.e., hypetrain.progression).
   event_timestamp String The UTC date and time (in RFC3339 format) that the event occurred.
   version String The version number of the definition of the event’s data. For example, the value is 1 if the data in event_data uses the first definition of the event’s data.
   event_data Object The event’s data.
      broadcaster_id String The ID of the broadcaster that’s running the Hype Train.
      cooldown_end_time string The UTC date and time (in RFC3339 format) that another Hype Train can start.
      expires_at String The UTC date and time (in RFC3339 format) that the Hype Train ends.
      goal Integer The value needed to reach the next level.
      id String An ID that identifies this Hype Train.
      last_contribution Object The most recent contribution towards the Hype Train’s goal.
         total Integer The total amount contributed. If type is BITS, total represents the amount of Bits used. If type is SUBS, total is 500, 1000, or 2500 to represent tier 1, 2, or 3 subscriptions, respectively.
         type String The contribution method used. Possible values are:
  • BITS — Cheering with Bits.
  • SUBS — Subscription activity like subscribing or gifting subscriptions.
  • OTHER — Covers other contribution methods not listed.
         user String The ID of the user that made the contribution.
      level Integer The highest level that the Hype Train reached (the levels are 1 through 5).
      started_at String The UTC date and time (in RFC3339 format) that this Hype Train started.
      top_contributions Object[] The top contributors for each contribution type. For example, the top contributor using BITS (by aggregate) and the top contributor using SUBS (by count).
         total Integer The total amount contributed. If type is BITS, total represents the amount of Bits used. If type is SUBS, total is 500, 1000, or 2500 to represent tier 1, 2, or 3 subscriptions, respectively.
         type String The contribution method used. Possible values are:
  • BITS — Cheering with Bits.
  • SUBS — Subscription activity like subscribing or gifting subscriptions.
  • OTHER — Covers other contribution methods not listed.
         user String The ID of the user that made the contribution.
      total Integer The current total amount raised.
pagination Object Contains the information used to page through the list of results. The object is empty if there are no more pages left to page through. Read More
   cursor String The cursor used to get the next page of results. Use the cursor to set the request’s after query parameter.

Response Codes

Code Description
200 OK Successfully retrieved the broadcaster’s Hype Train events.
401 Unauthorized
  • The ID in broadcaster_id must match the user ID in the user access token.
  • The Authorization header is required and must contain a user access token.
  • The user access token must include the channel:read:hype_train scope.
  • The access token is not valid.
  • The client ID specified in the Client-Id header does not match the client ID specified in the access token.

Example Request

curl -X GET
'https://api.twitch.tv/helix/hypetrain/events?broadcaster_id=270954519&first=1' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
  "data": [
    {
      "id": "1b0AsbInCHZW2SQFQkCzqN07Ib2",
      "event_type": "hypetrain.progression",
      "event_timestamp": "2020-04-24T20:07:24Z",
      "version": "1.0",
      "event_data": {
        "broadcaster_id": "270954519",
        "cooldown_end_time": "2020-04-24T20:13:21.003802269Z",
        "expires_at": "2020-04-24T20:12:21.003802269Z",
        "goal": 1800,
        "id": "70f0c7d8-ff60-4c50-b138-f3a352833b50",
        "last_contribution": {
          "total": 200,
          "type": "BITS",
          "user": "134247454"
        },
        "level": 2,
        "started_at": "2020-04-24T20:05:47.30473127Z",
        "top_contributions": [
          {
            "total": 600,
            "type": "BITS",
            "user": "134247450"
          }
        ],
        "total": 600
      }
    }
  ],
  "pagination": {
    "cursor": "eyJiIjpudWxsLCJhIjp7IkN1cnNvciI6IjI3MDk1NDUxOToxNTg3NzU4ODQ0OjFiMEFzYkluQ0haVzJTUUZRa0N6cU4wN0liMiJ9fQ"
  }
}

Check AutoMod Status

Checks whether AutoMod would flag the specified message for review.

AutoMod is a moderation tool that holds inappropriate or harassing chat messages for moderators to review. Moderators approve or deny the messages that AutoMod flags; only approved messages are released to chat. AutoMod detects misspellings and evasive language automatically. For information about AutoMod, see How to Use AutoMod.

Rate Limits: Rates are limited per channel based on the account type rather than per access token.

Account type Limit per minute Limit per hour
Normal 5 50
Affiliate 10 100
Partner 30 300

The above limits are in addition to the standard Twitch API rate limits. The rate limit headers in the response represent the Twitch rate limits and not the above limits.

Authorization

Requires a user access token that includes the moderation:read scope.

URL

POST https://api.twitch.tv/helix/moderation/enforcements/status

Request Query Parameters

Parameter Type Required? Description
broadcaster_id String Yes The ID of the broadcaster whose AutoMod settings and list of blocked terms are used to check the message. This ID must match the user ID in the access token.

Request Body

Field Type Required? Description
data Object[] Yes The list of messages to check. The list must contain at least one message and may contain up to a maximum of 100 messages.
   msg_id String Yes A caller-defined ID used to correlate this message with the same message in the response.
   msg_text String Yes The message to check.

Response Body

Field Type Description
data Object[] The list of messages and whether Twitch would approve them for chat.
   msg_id String The caller-defined ID passed in the request.
   is_permitted Boolean A Boolean value that indicates whether Twitch would approve the message for chat or hold it for moderator review or block it from chat. Is true if Twitch would approve the message; otherwise, false if Twitch would hold the message for moderator review or block it from chat.

Response Codes

Code Description
200 OK Successfully checked the messages.
400 Bad Request
  • The broadcaster_id query parameter is required.
  • The data field is required and the list must contain one or more messages to check.
  • The msg_id field is required.
  • The msg_text field is required.
401 Unauthorized
  • The Authorization header is required and must contain a user access token.
  • The user access token must include the moderation:read scope.
  • The access token is not valid.
  • The client ID specified in the Client-Id header does not match the client ID specified in the access token.
403 Forbidden
  • The ID in broadcaster_id must match the user ID in the user access token.
429 Too Many Requests
  • The broadcaster exceeded the number of chat message checks that they may make. See the endpoint's rate limits.

Example Request

curl -X POST 'https://api.twitch.tv/helix/moderation/enforcements/status?broadcaster_id=12345' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Content-Type: application/json' \
-d '{
  "data": [
    {
      "msg_id": "123",
      "msg_text": "Hello World!"
    },
    {
      "msg_id": "393",
      "msg_text": "Boooooo!"
    }
  ]
}'

Example Response

{
  "data": [
    {
      "msg_id": "123",
      "is_permitted": true
    },
    {
      "msg_id": "393",
      "is_permitted": false
    }
  ]
}

Manage Held AutoMod Messages

Allow or deny the message that AutoMod flagged for review. For information about AutoMod, see How to Use AutoMod.

To get messages that AutoMod is holding for review, subscribe to the automod-queue.<moderator_id>.<channel_id> topic using PubSub. PubSub sends a notification to your app when AutoMod holds a message for review.

Authorization

Requires a user access token that includes the moderator:manage:automod scope.

URL

POST https://api.twitch.tv/helix/moderation/automod/message

Request Body

Field Type Required? Description
user_id String Yes The moderator who is approving or denying the held message. This ID must match the user ID in the access token.
msg_id String Yes The ID of the message to allow or deny.
action String Yes The action to take for the message. Possible values are:
  • ALLOW
  • DENY

Response Codes

Code Description
204 No Content Successfully approved or denied the message.
400 Bad Request
  • The value in the action field is not valid.
  • The user_id field is required.
  • The msg_id field is required.
  • The action field is required.
401 Unauthorized
  • The ID in user_id must match the user ID in the user access token.
  • The Authorization header is required and must contain a user access token.
  • The user access token must include the moderator:manage:automod scope.
  • The access token is not valid.
  • The client ID specified in the Client-Id header does not match the client ID specified in the access token.
403 Forbidden
  • The user in user_id is not one of the broadcaster's moderators.
404 Not Found
  • The message specified in the msg_id field was not found.

Example Request

curl -X POST 'https://api.twitch.tv/helix/moderation/automod/message' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Content-Type: application/json' \
-d '{
  "user_id": "9327994",
  "msg_id": "836013710",
  "action": "ALLOW"
}'

Get AutoMod Settings

Gets the broadcaster’s AutoMod settings. The settings are used to automatically block inappropriate or harassing messages from appearing in the broadcaster’s chat room.

Authorization

Requires a user access token that includes the moderator:read:automod_settings scope.

URL

GET https://api.twitch.tv/helix/moderation/automod/settings

Request Query Parameters

Parameter Type Required? Description
broadcaster_id String Yes The ID of the broadcaster whose AutoMod settings you want to get.
moderator_id String Yes The ID of the broadcaster or a user that has permission to moderate the broadcaster’s chat room. This ID must match the user ID in the user access token.

Response Body

Field Type Description
data Object[] The list of AutoMod settings. The list contains a single object that contains all the AutoMod settings.
   broadcaster_id String The broadcaster’s ID.
   moderator_id String The moderator’s ID.
   overall_level Integer The default AutoMod level for the broadcaster. This field is null if the broadcaster has set one or more of the individual settings.
   disability Integer The Automod level for discrimination against disability.
   aggression Integer The Automod level for hostility involving aggression.
   sexuality_sex_or_gender Integer The AutoMod level for discrimination based on sexuality, sex, or gender.
   misogyny Integer The Automod level for discrimination against women.
   bullying Integer The Automod level for hostility involving name calling or insults.
   swearing Integer The Automod level for profanity.
   race_ethnicity_or_religion Integer The Automod level for racial discrimination.
   sex_based_terms Integer The Automod level for sexual content.

Response Codes

Code Description
200 OK Successfully retrieved the broadcaster’s AutoMod settings.
400 Bad Request
  • The broadcaster_id query parameter is required.
  • The moderator_id query parameter is required.
401 Unauthorized
  • The ID in moderator_id must match the user ID in the user access token.
  • The Authorization header is required and must contain a user access token.
  • The user access token must include the moderator:read:automod_settings scope.
  • The access token is not valid.
  • The client ID specified in the Client-Id header does not match the client ID specified in the access token.
403 Forbidden
  • The user in moderator_id is not one of the broadcaster's moderators.

Example Request

Gets the broadcaster’s AutoMod settings.

curl -X GET 'https://api.twitch.tv/helix/moderation/automod/settings?broadcaster_id=1234&moderator_id=5678' \
-H 'Authorization: Bearer 4a4x78f5wqvkybms7mxfist3jmzul' \
-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh'

Example Response

Shows what the response looks like if the broadcaster hasn’t enabled AutoMod (none of the settings are set).

{
  "data": [
    {
      "broadcaster_id": "1234",
      "moderator_id": "5678",
      "overall_level": null,
      "disability": 0,
      "aggression": 0,
      "sexuality_sex_or_gender": 0,
      "misogyny": 0,
      "bullying": 0,
      "swearing": 0,
      "race_ethnicity_or_religion": 0,
      "sex_based_terms": 0
    }
  ]
}

Update AutoMod Settings

Updates the broadcaster’s AutoMod settings. The settings are used to automatically block inappropriate or harassing messages from appearing in the broadcaster’s chat room.

Authorization

Requires a user access token that includes the moderator:manage:automod_settings scope.

URL

PUT https://api.twitch.tv/helix/moderation/automod/settings

Request Query Parameters

Parameter Type Required? Description
broadcaster_id String Yes The ID of the broadcaster whose AutoMod settings you want to update.
moderator_id String Yes The ID of the broadcaster or a user that has permission to moderate the broadcaster’s chat room. This ID must match the user ID in the user access token.

Request Body

Because PUT is an overwrite operation, you must include all the fields that you want set after the operation completes. Typically, you’ll send a GET request, update the fields you want to change, and pass that object in the PUT request.

You may set either overall_level or the individual settings like aggression, but not both.

Setting overall_level applies default values to the individual settings. However, setting overall_level to 4 does not necessarily mean that it applies 4 to all the individual settings. Instead, it applies a set of recommended defaults to the rest of the settings. For example, if you set overall_level to 2, Twitch provides some filtering on discrimination and sexual content, but more filtering on hostility (see the first example response).

If overall_level is currently set and you update swearing to 3, overall_level will be set to null and all settings other than swearing will be set to 0. The same is true if individual settings are set and you update overall_level to 3 — all the individual settings are updated to reflect the default level.

Note that if you set all the individual settings to values that match what overall_level would have set them to, Twitch changes AutoMod to use the default AutoMod level instead of using the individual settings.

Valid values for all levels are from 0 (no filtering) through 4 (most aggressive filtering). These levels affect how aggressively AutoMod holds back messages for moderators to review before they appear in chat or are denied (not shown).

Field Type Description
aggression Integer The Automod level for hostility involving aggression.
bullying Integer The Automod level for hostility involving name calling or insults.
disability Integer The Automod level for discrimination against disability.
misogyny Integer The Automod level for discrimination against women.
overall_level Integer The default AutoMod level for the broadcaster.
race_ethnicity_or_religion Integer The Automod level for racial discrimination.
sex_based_terms Integer The Automod level for sexual content.
sexuality_sex_or_gender Integer The AutoMod level for discrimination based on sexuality, sex, or gender.
swearing Integer The Automod level for profanity.

Response Body

Field Type Description
data Object[] The list of AutoMod settings. The list contains a single object that contains all the AutoMod settings.
   broadcaster_id String The broadcaster’s ID.
   moderator_id String The moderator’s ID.
   overall_level Integer The default AutoMod level for the broadcaster. This field is null if the broadcaster has set one or more of the individual settings.
   disability Integer The Automod level for discrimination against disability.
   aggression Integer The Automod level for hostility involving aggression.
   sexuality_sex_or_gender Integer The AutoMod level for discrimination based on sexuality, sex, or gender.
   misogyny Integer The Automod level for discrimination against women.
   bullying Integer The Automod level for hostility involving name calling or insults.
   swearing Integer The Automod level for profanity.
   race_ethnicity_or_religion Integer The Automod level for racial discrimination.
   sex_based_terms Integer The Automod level for sexual content.

Response Codes

Code Description
200 Ok Success.
400 Bad Request
  • The broadcaster_id is required.
  • The moderator_id is required.
  • The overall_level setting or one or more individual settings like aggression is required; the overall and individual settings are mutually exclusive, so don't set both.
  • The value of one or more AutoMod settings is not valid.
401 Unauthorized
  • The ID in moderator_id must match the user ID in the user access token.
  • The Authorization header is required and must contain a user access token.
  • The user access token must include the moderator:manage:automod_settings scope.
  • The access token is not valid.
  • The client ID specified in the Client-Id header does not match the client ID specified in the access token.
403 Forbidden
  • The user in moderator_id is not one of the broadcaster's moderators.

Example Request 1

This example updates the overall_level setting to 3.

curl -X PUT 'https://api.twitch.tv/helix/moderation/automod/settings?broadcaster_id=1234&moderator_id=5678' \
-H 'Authorization: Bearer 4a4x78f5wqvkybms7mxfist3jmzul' \
-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh'
​​-H 'Content-Type: application/json' \
-d '{"overall_level":3}'

Example Response 1

Notice in the response that not all settings are set to level 3.

{
  "data": [
    {
      "broadcaster_id": "1234",
      "moderator_id": "5678",
      "overall_level": 3,
      "disability": 3,
      "aggression": 3,
      "sexuality_sex_or_gender": 3,
      "misogyny": 3,
      "bullying": 2,
      "swearing": 0,
      "race_ethnicity_or_religion": 3,
      "sex_based_terms": 3
    }
  ]
}

If overall_level is set to 3 and you try to change swearing to 2, all other settings are set to 0. If the goal was to change the swearing setting and leave all the others unchanged, the request must have included all the other settings as well.

{
  "data": [
    {
      "broadcaster_id": "1234",
      "moderator_id": "5678",
      "overall_level": null,
      "disability": 0,
      "aggression": 0,
      "sexuality_sex_or_gender": 0,
      "misogyny": 0,
      "bullying": 0,
      "swearing": 2,
      "race_ethnicity_or_religion": 0,
      "sex_based_terms": 0
    }
  ]
}

Get Banned Users

Gets all users that the broadcaster banned or put in a timeout.

Authentication

Requires a user access token that includes the moderation:read scope.

URL

GET https://api.twitch.tv/helix/moderation/banned

Request Query Parameters

Parameter Type Required? Description
broadcaster_id String Yes The ID of the broadcaster whose list of banned users you want to get. This ID must match the user ID in the access token.
user_id String No A list of user IDs used to filter the results. To specify more than one ID, include this parameter for each user you want to get. For example, user_id=1234&user_id=5678. You may specify a maximum of 100 IDs.

The returned list includes only those users that were banned or put in a timeout. The list is returned in the same order that you specified the IDs.
first Integer No The maximum number of items to return per page in the response. The minimum page size is 1 item per page and the maximum is 100 items per page. The default is 20.
after String No The cursor used to get the next page of results. The Pagination object in the response contains the cursor’s value. Read More
before String No The cursor used to get the previous page of results. The Pagination object in the response contains the cursor’s value. Read More

Response Body

Field Type Description
data Object[] The list of users that were banned or put in a timeout.
   user_id String The ID of the banned user.
   user_login String The banned user’s login name.
   user_name String The banned user’s display name.
   expires_at String The UTC date and time (in RFC3339 format) of when the timeout expires, or an empty string if the user is permanently banned.
   created_at String The UTC date and time (in RFC3339 format) of when the user was banned.
   reason String The reason the user was banned or put in a timeout if the moderator provided one.
   moderator_id String The ID of the moderator that banned the user or put them in a timeout.
   moderator_login String The moderator’s login name.
   moderator_name String The moderator’s display name.
pagination Object Contains the information used to page through the list of results. The object is empty if there are no more pages left to page through. Read More
   cursor String The cursor used to get the next page of results. Use the cursor to set the request’s after query parameter.

Response Codes

Code Description
200 OK Successfully retrieved the list of banned users.
400 Bad Request
  • The broadcaster_id query parameter is required.
401 Unauthorized
  • The ID in broadcaster_id must match the user ID in the user access token.
  • The Authorization header is required and must contain a user access token.
  • The user access token must include the moderation:read scope.
  • The access token is not valid.
  • The client ID specified in the Client-Id header does not match the client ID specified in the access token.

Example Request

curl -X GET 'https://api.twitch.tv/helix/moderation/banned?broadcaster_id=198704263' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
  "data": [
    {
      "user_id": "423374343",
      "user_login": "glowillig",
      "user_name": "glowillig",
      "expires_at": "2022-03-15T02:00:28Z",
      "created_at": "2022-03-15T01:30:28Z",
      "reason": "Does not like pineapple on pizza.",
      "moderator_id": "141981764",
      "moderator_login": "twitchdev",
      "moderator_name": "TwitchDev"
    },
    {
      "user_id": "424596340",
      "user_login": "quotrok",
      "user_name": "quotrok",
      "expires_at": "2022-08-07T02:07:55Z",
      "created_at": "2022-08-07T02:02:55Z",
      "reason": "Inappropriate words.",
      "moderator_id": "141981764",
      "moderator_login": "twitchdev",
      "moderator_name": "TwitchDev"
    },
    ...
  ],
  "pagination": {
    "cursor": "eyJiIjpudWxsLCJhIjp7IkN1cnNvciI6IjEwMDQ3MzA2NDo4NjQwNjU3MToxSVZCVDFKMnY5M1BTOXh3d1E0dUdXMkJOMFcifX0"
  }
}

Ban User

Bans a user from participating in the specified broadcaster’s chat room or puts them in a timeout.

For information about banning or putting users in a timeout, see Ban a User and Timeout a User.

If the user is currently in a timeout, you can call this endpoint to change the duration of the timeout or ban them altogether. If the user is currently banned, you cannot call this method to put them in a timeout instead.

To remove a ban or end a timeout, see Unban user.

Authentication

Requires a user access token that includes the moderator:manage:banned_users scope.

URL

POST https://api.twitch.tv/helix/moderation/bans

Request Query Parameters

Parameter Type Required? Description
broadcaster_id String Yes The ID of the broadcaster whose chat room the user is being banned from.
moderator_id String Yes The ID of the broadcaster or a user that has permission to moderate the broadcaster’s chat room. This ID must match the user ID in the user access token.

Request Body

Field Type Required? Description
data Object Yes Identifies the user and type of ban.
   user_id String Yes The ID of the user to ban or put in a timeout.
   duration Integer No To ban a user indefinitely, don’t include this field.

To put a user in a timeout, include this field and specify the timeout period, in seconds. The minimum timeout is 1 second and the maximum is 1,209,600 seconds (2 weeks).

To end a user’s timeout early, set this field to 1, or use the Unban user endpoint.
   reason String No The reason the you’re banning the user or putting them in a timeout. The text is user defined and is limited to a maximum of 500 characters.

Response Body

Field Type Description
data Object[] A list that contains the user you successfully banned or put in a timeout.
   broadcaster_id String The broadcaster whose chat room the user was banned from chatting in.
   moderator_id String The moderator that banned or put the user in the timeout.
   user_id String The user that was banned or put in a timeout.
   created_at string The UTC date and time (in RFC3339 format) that the ban or timeout was placed.
   end_time String The UTC date and time (in RFC3339 format) that the timeout will end. Is null if the user was banned instead of being put in a timeout.

Response Codes

Code Description
200 OK Successfully banned the user or placed them in a timeout.
400 Bad Request
  • The broadcaster_id query parameter is required.
  • The moderator_id query parameter is required.
  • The user_id field is required.
  • The text in the reason field is too long.
  • The value in the duration field is not valid.
  • The user specified in the user_id field may not be banned.
  • The user specified in the user_id field may not be put in a timeout.
  • The user specified in the user_id field is already banned.
401 Unauthorized
  • The ID in moderator_id must match the user ID in the access token.
  • The Authorization header is required and must contain a user access token.
  • The user access token must include the moderator:manage:banned_users scope.
  • The access token is not valid.
  • The client ID specified in the Client-Id header does not match the client ID specified in the access token.
403 Forbidden
  • The user in moderator_id is not one of the broadcaster's moderators.
409 Conflict
  • You may not update the user's ban state while someone else is updating the state. For example, someone else is currently banning the user or putting them in a timeout, moving the user from a timeout to a ban, or removing the user from a ban or timeout. Please retry your request.
429 Too Many Requests
  • The app has exceeded the number of requests it may make per minute for this broadcaster.

Example Request 1

Bans a user (it doesn’t include the duration field).

curl -X POST 'https://api.twitch.tv/helix/moderation/bans?broadcaster_id=1234&moderator_id=5678' \
-H 'Authorization: Bearer 4a4x78f5wqvkybms7mxfist3jmzul' \
-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh' \
-H 'Content-Type: application/json' \
-d '{"data": {"user_id":"9876","reason":"no reason"}}'

Example Response 1

{
  "data": [
    {
      "broadcaster_id": "1234",
      "moderator_id": "5678",
      "user_id": "9876",
      "created_at": "2021-09-28T18:22:31Z",
      "end_time": null
    }
  ]
}

Example Request 2

Puts a user in a 5-minute timeout.

curl -X POST 'https://api.twitch.tv/helix/moderation/bans?broadcaster_id=1234&moderator_id=5678' \
-H 'Authorization: Bearer 4a4x78f5wqvkybms7mxfist3jmzul' \
-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh' \
-H 'Content-Type: application/json' \
-d '{"data": {"user_id":"9876","duration":300,"reason":"no reason"}}'

Example Response 2

{
  "data": [
    {
      "broadcaster_id": "1234",
      "moderator_id": "5678",
      "user_id": "9876",
      "created_at": "2021-09-28T19:27:31Z",
      "end_time": "2021-09-28T19:22:31Z"
    }
  ]
}

Example Request 3

Shows what happens if you try to place a banned user in a timeout. You can ban a user that’s already in a timeout but you can’t move a banned user into a timeout. To do this, you’d have to remove the ban and then place them in a timeout.

You’ll get the same response if you try to ban a user who is already banned.

curl -X POST 'https://api.twitch.tv/helix/moderation/bans?broadcaster_id=1234&moderator_id=5678' \
-H 'Authorization: Bearer 4a4x78f5wqvkybms7mxfist3jmzul' \
-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh' \
-H 'Content-Type: application/json' \
-d '{"data": {"user_id":"9876","duration":300,"reason":"no reason"}}'

Example Response 3

{ 
  "error": "Bad Request", 
  "status": 400, 
  "message": "user is already banned" 
}

Unban User

Removes the ban or timeout that was placed on the specified user.

To ban a user, see Ban user.

Authentication

Requires a user access token that includes the moderator:manage:banned_users scope.

URL

DELETE https://api.twitch.tv/helix/moderation/bans

Request Query Parameters

Parameter Type Required? Description
broadcaster_id String Yes The ID of the broadcaster whose chat room the user is banned from chatting in.
moderator_id String Yes The ID of the broadcaster or a user that has permission to moderate the broadcaster’s chat room. This ID must match the user ID in the user access token.
user_id String Yes The ID of the user to remove the ban or timeout from.

Response Codes

Code Description
204 No Content Successfully removed the ban or timeout.
400 Bad Request
  • The broadcaster_id query parameter is required.
  • The moderator_id query parameter is required.
  • The user_id query parameter is required.
  • The user specified in the user_id query parameter is not banned.
401 Unauthorized
  • The ID in moderator_id must match the user ID in the access token.
  • The Authorization header is required and must contain a user access token.
  • The user access token must include the moderator:manage:banned_users scope.
  • The access token is not valid.
  • The client ID specified in the Client-Id header does not match the client ID specified in the access token.
403 Forbidden
  • The user in moderator_id is not one of the broadcaster's moderators.
409 Conflict
  • You may not update the user's ban state while someone else is updating the state. For example, someone else is currently removing the ban or timeout, or they're moving the user from a timeout to a ban. Please retry your request.
429 Too Many Requests
  • The app has exceeded the number of requests it may make per minute for this broadcaster.

Example Request 1

Removes a ban or timeout from a user.

curl -X DELETE 'https://api.twitch.tv/helix/moderation/bans?broadcaster_id=1234&moderator_id=5678&user_id=9876' \
-H 'Authorization: Bearer 4a4x78f5wqvkybms7mxfist3jmzul' \
-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh'

Example Request 2

Tries to remove a ban or timeout from a user that is not currently banned or in a timeout.

curl -X DELETE 'https://api.twitch.tv/helix/moderation/bans?broadcaster_id=1234&moderator_id=5678&user_id=5432' \
-H 'Authorization: Bearer 4a4x78f5wqvkybms7mxfist3jmzul' \
-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh'

Example Response 2

{ 
  "error": "Bad Request", 
  "status": 400, 
  "message": "user is not banned" 
}

Get Blocked Terms

Gets the broadcaster’s list of non-private, blocked words or phrases. These are the terms that the broadcaster or moderator added manually or that were denied by AutoMod.

Authorization

Requires a user access token that includes the moderator:read:blocked_terms scope.

URL

GET https://api.twitch.tv/helix/moderation/blocked_terms

Request Query Parameters

Parameter Type Required? Description
broadcaster_id String Yes The ID of the broadcaster whose blocked terms you’re getting.
moderator_id String Yes The ID of the broadcaster or a user that has permission to moderate the broadcaster’s chat room. This ID must match the user ID in the user access token.
first Integer No The maximum number of items to return per page in the response. The minimum page size is 1 item per page and the maximum is 100 items per page. The default is 20.
after String No The cursor used to get the next page of results. The Pagination object in the response contains the cursor’s value.

Response Body

Field Type Description
data Object[] The list of blocked terms. The list is in descending order of when they were created (see the created_at timestamp).
  broadcaster_id String The broadcaster that owns the list of blocked terms.
  moderator_id String The moderator that blocked the word or phrase from being used in the broadcaster’s chat room.
  id String An ID that identifies this blocked term.
  text String The blocked word or phrase.
  created_at String The UTC date and time (in RFC3339 format) that the term was blocked.
  updated_at String The UTC date and time (in RFC3339 format) that the term was updated.

When the term is added, this timestamp is the same as created_at. The timestamp changes as AutoMod continues to deny the term.
  expires_at String The UTC date and time (in RFC3339 format) that the blocked term is set to expire. After the block expires, users may use the term in the broadcaster’s chat room.

This field is null if the term was added manually or was permanently blocked by AutoMod.
pagination Object Contains the information used to page through the list of results. The object is empty if there are no more pages left to page through. Read More
   cursor String The cursor used to get the next page of results. Use the cursor to set the request’s after query parameter.

Response Codes

Code Decription
200 OK Successfully retrieved the list of blocked terms.
400 Bad Request
  • The broadcaster_id query parameter is required.
  • The moderator_id query parameter is required.
401 Unauthorized
  • The ID in moderator_id must match the user ID in the user access token.
  • The Authorization header must contain a user access token.
  • The user access token must include the moderator:read:blocked_terms scope.
  • The access token is not valid.
  • The client ID specified in the Client-Id header does not match the client ID specified in the access token.
403 Forbidden
  • The user in moderator_id is not one of the broadcaster's moderators.

Example Request

Gets the last 10 blocked terms (see the first query parameter) that were added.

curl -X GET 'https://api.twitch.tv/helix/moderation/blocked_terms?broadcaster_id=1234&moderator_id=5678&first=10' \
-H 'Authorization: Bearer f4otqljtpbpg24v41v9gechs4yvwy' \
-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh'

Example Response

{
  "data": [
    {
      "broadcaster_id": "1234",
      "moderator_id": "5678",
      "id": "520e4d4e-0cda-49c7-821e-e5ef4f88c2f2",
      "text": "A phrase I’m not fond of",
      "created_at": "2021-09-29T19:45:37Z",
      "updated_at": "2021-09-29T19:45:37Z",
      "expires_at": null
    },

    . . .

  ],
  "pagination": {
    "cursor": "eyJiIjpudWxsLCJhIjp7IkN1cnNvciI6I..."
  }
}

Add Blocked Term

Adds a word or phrase to the broadcaster’s list of blocked terms. These are the terms that the broadcaster doesn’t want used in their chat room.

Authentication

Requires a user access token that includes the moderator:manage:blocked_terms scope.

URL

POST https://api.twitch.tv/helix/moderation/blocked_terms

Request Query Parameters

Parameter Type Required? Description
broadcaster_id String Yes The ID of the broadcaster that owns the list of blocked terms.
moderator_id String Yes The ID of the broadcaster or a user that has permission to moderate the broadcaster’s chat room. This ID must match the user ID in the user access token.

Request Body

Field Type Required? Description
text String Yes The word or phrase to block from being used in the broadcaster’s chat room. The term must contain a minimum of 2 characters and may contain up to a maximum of 500 characters.

Terms may include a wildcard character (*). The wildcard character must appear at the beginning or end of a word or set of characters. For example, *foo or foo*.

If the blocked term already exists, the response contains the existing blocked term.

Response Body

Field Type Description
data Object[] A list that contains the single blocked term that the broadcaster added.
   broadcaster_id String The broadcaster that owns the list of blocked terms.
   moderator_id String The moderator that blocked the word or phrase from being used in the broadcaster’s chat room.
   id String An ID that identifies this blocked term.
   text String The blocked word or phrase.
   created_at String The UTC date and time (in RFC3339 format) that the term was blocked.
   updated_at String The UTC date and time (in RFC3339 format) that the term was updated.

When the term is added, this timestamp is the same as created_at. The timestamp changes as AutoMod continues to deny the term.
   expires_at String The UTC date and time (in RFC3339 format) that the blocked term is set to expire. After the block expires, users may use the term in the broadcaster’s chat room.

This field is null if the term was added manually or was permanently blocked by AutoMod.

Response Codes

Code Decription
200 OK Successfully retrieved the list of blocked terms.
400 Bad Request
  • The broadcaster_id query parameter is required.
  • The moderator_id query parameter is required.
  • The text field is required.
  • The length of the term in the text field is either too short or too long.
401 Unauthorized
  • The ID in moderator_id must match the user ID in the user access token.
  • The Authorization header is required and must contain a user access token.
  • The user access token must include the moderator:manage:blocked_terms scope.
  • The access token is not valid.
  • The client ID specified in the Client-Id header does not match the client ID specified in the access token.
403 Forbidden
  • The user in moderator_id is not one of the broadcaster's moderators.

Example Request 1

Adds a blocked term. Adding the same term again will return the previously added term.

curl -X POST 'https://api.twitch.tv/helix/moderation/blocked_terms?broadcaster_id=1234&moderator_id=5678' \
-H 'Authorization: Bearer 789nj68b49pwqs9nh2y2jrlgzju3f' \
-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh' \
-H 'Content-Type: application/json' \
-d '{"text":"A phrase I’m not fond of"}'

Example Response 1

{
  "data": [
    {
      "broadcaster_id": "713936733",
      "moderator_id": "713936733",
      "id": "3bb6e5d3-afb1-416c-ad4e-21af970ccfe7",
      "text": "A phrase I’m not fond of",
      "created_at": "2021-09-29T15:36:45Z",
      "updated_at": "2021-09-29T15:36:45Z",
      "expires_at": null
    }
  ]
}

Example Request 2

Adds a term that uses the wildcard character (*).

curl -X POST 'https://api.twitch.tv/helix/moderation/blocked_terms?broadcaster_id=1234&moderator_id=5678' \
-H 'Authorization: Bearer 789nj68b49pwqs9nh2y2jrlgzju3f' \
-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh' \
-H 'Content-Type: application/json' \
-d '{"text":"crac*"}'

Example Response 2

{
  "data": [
    {
      "broadcaster_id": "1234",
      "moderator_id": "5678",
      "id": "520e4d4e-0cda-49c7-821e-e5ef4f88c2f2",
      "text": "crac*",
      "created_at": "2021-09-29T19:45:37Z",
      "updated_at": "2021-09-29T19:45:37Z",
      "expires_at": null
    }
  ]
}

Remove Blocked Term

Removes the word or phrase from the broadcaster’s list of blocked terms.

Authentication

Requires a user access token that includes the moderator:manage:blocked_terms scope.

URL

DELETE https://api.twitch.tv/helix/moderation/blocked_terms

Request Query Parameters

Parameter Type Required? Description
broadcaster_id String Yes The ID of the broadcaster that owns the list of blocked terms.
moderator_id String Yes The ID of the broadcaster or a user that has permission to moderate the broadcaster’s chat room. This ID must match the user ID in the user access token.
id String Yes The ID of the blocked term to remove from the broadcaster’s list of blocked terms.

Response Codes

Code Decription
204 No Content Successfully removed the blocked term. Also returned if the ID is not found.
400 Bad Request
  • The broadcaster_id query parameter is required.
  • The moderator_id query parameter is required.
  • The id query parameter is required.
401 Unauthorized
  • The ID in moderator_id must match the user ID in the user access token.
  • The Authorization header is required and must contain a user access token.
  • The user access token must include the moderator:manage:blocked_terms scope.
  • The access token is not valid.
  • The client ID specified in the Client-Id header does not match the client ID specified in the access token.
403 Forbidden
  • The user in moderator_id is not one of the broadcaster's moderators.

Example Request

Deletes the specified blocked term.

curl -X DELETE 'https://api.twitch.tv/helix/moderation/blocked_terms?broadcaster_id=1234&moderator_id=5678&id=c9fc79b8-0f63-4ef7-9d38-efd811e74ac2' \ 
-H 'Authorization: Bearer f4otqljtpbpg24v41v9gechs4yvwy' \
-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh'

Delete Chat Messages

Removes a single chat message or all chat messages from the broadcaster’s chat room.

Authentication

Requires a user access token that includes the moderator:manage:chat_messages scope.

URL

DELETE https://api.twitch.tv/helix/moderation/chat

Request Query Parameters

Parameter Type Required? Description
broadcaster_id String Yes The ID of the broadcaster that owns the chat room to remove messages from.
moderator_id String Yes The ID of the broadcaster or a user that has permission to moderate the broadcaster’s chat room. This ID must match the user ID in the user access token.
message_id String No The ID of the message to remove. The id tag in the PRIVMSG tag contains the message’s ID. Restrictions:
  • The message must have been created within the last 6 hours.
  • The message must not belong to the broadcaster.
  • The message must not belong to another moderator.
If not specified, the request removes all messages in the broadcaster’s chat room.

Response Codes

Code Description
204 No Content Successfully removed the specified messages.
400 Bad Request
  • You may not delete another moderator's messages.
  • You may not delete the broadcaster's messages.
401 Unauthorized
  • The Authorization header is required and must contain a user access token.
  • The user access token is missing the moderator:manage:chat_messages scope.
  • The OAuth token is not valid.
  • The client ID specified in the Client-Id header does not match the client ID specified in the OAuth token.
403 Forbidden
  • The user in moderator_id is not one of the broadcaster's moderators.
404 Not Found
  • The ID in message_id was not found.
  • The specified message was created more than 6 hours ago.

Example Request

Removes all messages from the broadcaster’s chat room (doesn’t include the message_id query parameter).

curl -X DELETE 'https://api.twitch.tv/helix/moderation/chat?broadcaster_id=11111&moderator_id=44444' \
-H 'Authorization: Bearer f4otqljtpbpg24v41v9gechs4yvwy' \
-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh'

Removes the specified message from the broadcaster’s chat room.

curl -X DELETE 'https://api.twitch.tv/helix/moderation/chat?broadcaster_id=11111&moderator_id=44444&message_id=abc-123-def' \ 
-H 'Authorization: Bearer f4otqljtpbpg24v41v9gechs4yvwy' \
-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh'

Get Moderators

Gets all users allowed to moderate the broadcaster’s chat room.

Authorization

Requires a user access token that includes the moderation:read scope. If your app also adds and removes moderators, you can use the channel:manage:moderators scope instead.

URL

GET https://api.twitch.tv/helix/moderation/moderators

Request Query Parameters

Parameter Type Required? Description
broadcaster_id String Yes The ID of the broadcaster whose list of moderators you want to get. This ID must match the user ID in the access token.
user_id String No A list of user IDs used to filter the results. To specify more than one ID, include this parameter for each moderator you want to get. For example, user_id=1234&user_id=5678. You may specify a maximum of 100 IDs.

The returned list includes only the users from the list who are moderators in the broadcaster’s channel. The list is returned in the same order as you specified the IDs.
first String No The maximum number of items to return per page in the response. The minimum page size is 1 item per page and the maximum is 100 items per page. The default is 20.
after String No The cursor used to get the next page of results. The Pagination object in the response contains the cursor’s value. Read More

Response Body

Field Type Description
data Object[] The list of moderators.
   user_id String The ID of the user that has permission to moderate the broadcaster’s channel.
   user_login String The user’s login name.
   user_name String The user’s display name.
pagination Object Contains the information used to page through the list of results. The object is empty if there are no more pages left to page through. Read More
   cursor String The cursor used to get the next page of results. Use the cursor to set the request’s after query parameter.

Response Codes

Code Description
200 OK Successfully retrieved the list of moderators.
400 Bad Request
  • The broadcaster_id query parameter is required.
401 Unauthorized
  • The ID in broadcaster_id must match the user ID found in the access token.
  • The Authorization header is required and must contain a user access token.
  • The user access token must include the moderation:read scope.
  • The access token is not valid.
  • The client ID specified in the Client-Id header does not match the client ID specified in the access token.

Example Request

curl -X GET 'https://api.twitch.tv/helix/moderation/moderators?broadcaster_id=198704263' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
  "data": [
    {
      "user_id": "424596340",
      "user_login": "quotrok",
      "user_name": "quotrok"
    },
    ...
  ],
  "pagination": {
    "cursor": "eyJiIjpudWxsLCJhIjp7IkN1cnNvciI6IjEwMDQ3MzA2NDo4NjQwNjU3MToxSVZCVDFKMnY5M1BTOXh3d1E0dUdXMkJOMFcifX0"
  }
}

Add Channel Moderator

Adds a moderator to the broadcaster’s chat room.

Rate Limits: The broadcaster may add a maximum of 10 moderators within a 10-second window.

Authorization

Requires a user access token that includes the channel:manage:moderators scope.

URL

POST https://api.twitch.tv/helix/moderation/moderators

Request Query Parameters

Parameter Type Required? Description
broadcaster_id String Yes The ID of the broadcaster that owns the chat room. This ID must match the user ID in the access token.
user_id String Yes The ID of the user to add as a moderator in the broadcaster’s chat room.

Response Codes

Code Description
204 No Content Successfully added the moderator.
400 Bad Request
  • The ID in broadcaster_id was not found.
  • The ID in user_id was not found.
  • The user in user_id is already a moderator in the broadcaster's chat room.
  • The user in user_id cannot become a moderator because they're banned from the channel.
401 Unauthorized
  • The Authorization header is required and must contain a user access token.
  • The user access token must include the channel:manage:moderators scope.
  • The access token is not valid.
  • The ID in the broadcaster_id query parameter must match the user ID in the access token.
  • The client ID specified in the Client-Id header does not match the client ID specified in the access token.
422 Unprocessable Entity
  • The user in user_id is a VIP. To make them a moderator, you must first remove them as a VIP (see Remove Channel VIP).
429 Too Many Requests
  • The broadcaster has exceeded the number of requests allowed within a 10-second window. See this endpoint's rate limits.

Example Request

curl -X POST 'https://api.twitch.tv/helix/moderation/moderators?broadcaster_id=11111&user_id=44444' \
-H 'Authorization: Bearer kpvy3cjboyptmdkiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfnys0nyan9c87zr6t'

Remove Channel Moderator

Removes a moderator from the broadcaster’s chat room.

Rate Limits: The broadcaster may remove a maximum of 10 moderators within a 10-second window.

Authorization

Requires a user access token that includes the channel:manage:moderators scope.

URL

DELETE https://api.twitch.tv/helix/moderation/moderators

Request Query Parameters

Parameter Type Required? Description
broadcaster_id String Yes The ID of the broadcaster that owns the chat room. This ID must match the user ID in the access token.
user_id String Yes The ID of the user to remove as a moderator from the broadcaster’s chat room.

Response Codes

Code Description
204 No Content Successfully removed the moderator.
400 Bad Request
  • The ID in broadcaster_id was not found.
  • The ID in user_id was not found.
  • The user in user_id is not a moderator in the broadcaster's chat room.
401 Unauthorized
  • The Authorization header is required and must contain a user access token.
  • The user access token must include the channel:manage:moderators scope.
  • The access token is not valid.
  • The ID in the broadcaster_id query parameter must match the user ID in the access token.
  • The client ID specified in the Client-Id header does not match the client ID specified in the access token.
429 Too Many Requests
  • The broadcaster has exceeded the number of requests allowed within a 10-second window. See this endpoint's rate limits.

Example Request

curl -X DELETE 'https://api.twitch.tv/helix/moderation/moderators?broadcaster_id=11111&user_id=44444' \
-H 'Authorization: Bearer kpvy3cjboyptmdkiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfnys0nyan9c87zr6t'

Get VIPs

Gets a list of the broadcaster’s VIPs.

Authorization

Requires a user access token that includes the channel:read:vips scope. If your app also adds and removes VIP status, you can use the channel:manage:vips scope instead.

URL

GET https://api.twitch.tv/helix/channels/vips

Request Query Parameters

Parameter Type Required? Description
user_id String No Filters the list for specific VIPs. To specify more than one user, include the user_id parameter for each user to get. For example, &user_id=1234&user_id=5678. The maximum number of IDs that you may specify is 100. Ignores the ID of those users in the list that aren’t VIPs.
broadcaster_id String Yes The ID of the broadcaster whose list of VIPs you want to get. This ID must match the user ID in the access token.
first Integer No The maximum number of items to return per page in the response. The minimum page size is 1 item per page and the maximum is 100. The default is 20.
after String No The cursor used to get the next page of results. The Pagination object in the response contains the cursor’s value. Read More

Response Body

Field Type Description
data Object[] The list of VIPs. The list is empty if the broadcaster doesn’t have VIP users.
   user_id String An ID that uniquely identifies the VIP user.
   user_name String The user’s display name.
   user_login String The user’s login name.
pagination Object Contains the information used to page through the list of results. The object is empty if there are no more pages left to page through. Read More
   cursor String The cursor used to get the next page of results. Use the cursor to set the request’s after query parameter.

Response Codes

Code Description
200 OK Successfully retrieved the broadcaster’s list of VIPs.
400 Bad Request
  • The broadcaster_id query parameter is required.
  • The ID in the user_id query parameter is not valid.
  • The number of user_id query parameters exceeds the maximum allowed.
401 Unauthorized
  • The Authorization header is required and must contain a user access token.
  • The user access token must include the channel:read:vips or channel:manage:vips scope.
  • The OAuth token is not valid.
  • The ID in the broadcaster_id query parameter must match the user ID in the access token.
  • The client ID specified in the Client-Id header does not match the client ID specified in the OAuth token.

Example Request

Gets a list of the broadcaster’s VIPs

curl -X GET 'https://api.twitch.tv/helix/channels/vips?broadcaster_id=123' \
-H 'Authorization: Bearer kpvy3cjboyptmdkiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfnys0nyan9c87zr6t'

Gets a filtered list of the broadcaster’s VIPs. The list in the response contains only those users that are VIPs.

curl -X GET 'https://api.twitch.tv/helix/channels/vips?broadcaster_id=123&user_id=456&user_id=678' \
-H 'Authorization: Bearer kpvy3cjboyptmdkiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfnys0nyan9c87zr6t'

Example Response

{
  "data": [
    {
      "user_id": "11111",
      "user_name": "UserDisplayName",
      "user_login": "userloginname"
    },
    ...
  ],
  "pagination": {
    "cursor": "eyJiIjpudWxsLCJhIjp7Ik9mZnNldCI6NX19"
  }
}

Add Channel VIP

Adds the specified user as a VIP in the broadcaster’s channel.

Rate Limits: The broadcaster may add a maximum of 10 VIPs within a 10-second window.

Authorization

Requires a user access token that includes the channel:manage:vips scope.

URL

POST https://api.twitch.tv/helix/channels/vips

Request Query Parameters

Parameter Type Required? Description
user_id String Yes The ID of the user to give VIP status to.
broadcaster_id String Yes The ID of the broadcaster that’s adding the user as a VIP. This ID must match the user ID in the access token.

Response Body

None

Response Codes

Code Description
204 No Content Successfully added the VIP.
400 Bad Request
  • The user in the user_id query parameter is blocked from the broadcaster's channel.
  • The ID in the broadcaster_id query parameter is not valid.
  • The ID in the user_id query parameter is not valid.
401 Unauthorized
  • The Authorization header is required and must contain a user access token.
  • The user access token must include the channel:manage:vips scope.
  • The OAuth token is not valid.
  • The ID in the broadcaster_id query parameter must match the user ID in the access token.
  • The client ID specified in the Client-Id header does not match the client ID specified in the OAuth token.
403 Forbidden
  • The ID in the broadcaster_id query parameter must match the user ID in the access token.
404 Not Found
  • The ID in broadcaster_id was not found.
  • The ID in user_id was not found.
409 Conflict The broadcaster doesn’t have available VIP slots. Read More
422 Unprocessable Entity
  • The user in user_id is a moderator. To make them a VIP, you must first remove them as a moderator (see Remove Channel Moderator).
  • The user in the user_id query parameter is already a VIP.
425 Too Early The broadcaster must complete the Build a Community requirement before they may assign VIPs.
429 Too Many Requests The broadcaster exceeded the number of VIP that they may add within a 10-second window. See Rate Limits for this endpoint above.

Example Request

Adds a VIP to the broadcaster’s chat room.

curl -X POST 'https://api.twitch.tv/helix/channels/vips?broadcaster_id=123&user_id=456' \
-H 'Authorization: Bearer kpvy3cjboyptmdkiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfnys0nyan9c87zr6t'

Remove Channel VIP

Removes the specified user as a VIP in the broadcaster’s channel.

If the broadcaster is removing the user’s VIP status, the ID in the broadcaster_id query parameter must match the user ID in the access token; otherwise, if the user is removing their VIP status themselves, the ID in the user_id query parameter must match the user ID in the access token.

Rate Limits: The broadcaster may remove a maximum of 10 VIPs within a 10-second window.

Authorization

Requires a user access token that includes the channel:manage:vips scope.

URL

DELETE https://api.twitch.tv/helix/channels/vips

Request Query Parameters

Parameter Type Required? Description
user_id String Yes The ID of the user to remove VIP status from.
broadcaster_id String Yes The ID of the broadcaster who owns the channel where the user has VIP status.

Response Body

None

Response Codes

Code Description
204 No Content Successfully removed the VIP status from the user.
400 Bad Request
  • The ID in broadcaster_id is not valid.
  • The ID in user_id is not valid.
401 Unauthorized
  • The Authorization header is required and must contain a user access token.
  • The user access token must include the channel:manage:vips scope.
  • The OAuth token is not valid.
  • The ID in the broadcaster_id query parameter must match the user ID in the access token.
  • The client ID specified in the Client-Id header does not match the client ID specified in the OAuth token.
403 Forbidden
  • The user in broadcaster_id doesn't have permission to remove the user's VIP status.
404 Not Found
  • The ID in broadcaster_id was not found.
  • The ID in user_id was not found.
422 Unprocessable Entity
  • The user in user_id is not a VIP in the broadcaster's channel.
429 Too Many Requests The broadcaster exceeded the number of VIPs that they may remove within a 10-second window. See Rate Limits for this endpoint above.

Example Request

Removes the VIP user from the broadcaster’s channel.

curl -X DELETE 'https://api.twitch.tv/helix/channels/vips?broadcaster_id=123&user_id=456' \
-H 'Authorization: Bearer kpvy3cjboyptmdkiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfnys0nyan9c87zr6t'

Update Shield Mode Status

BETA Activates or deactivates the broadcaster’s Shield Mode.

Twitch’s Shield Mode feature is like a panic button that broadcasters can push to protect themselves from chat abuse coming from one or more accounts. When activated, Shield Mode applies the overrides that the broadcaster configured in the Twitch UX. If the broadcaster hasn’t configured Shield Mode, it applies default overrides.

Authorization

Requires a user access token that includes the moderator:manage:shield_mode scope.

URL

PUT https://api.twitch.tv/helix/moderation/shield_mode

Request Query Parameters

Parameter Type Required? Description
broadcaster_id String Yes The ID of the broadcaster whose Shield Mode you want to activate or deactivate.
moderator_id String Yes The ID of the broadcaster or a user that is one of the broadcaster’s moderators. This ID must match the user ID in the access token.

Request Body

Field Type Required? Description
is_active Boolean Yes A Boolean value that determines whether to activate Shield Mode. Set to true to activate Shield Mode; otherwise, false to deactivate Shield Mode.

Response Body

Field Type Description
data Object[] A list that contains a single object with the broadcaster’s updated Shield Mode status.
   is_active Boolean A Boolean value that determines whether Shield Mode is active. Is true if Shield Mode is active; otherwise, false.
   moderator_id String An ID that identifies the moderator that last activated Shield Mode.
   moderator_login String The moderator’s login name.
   moderator_name String The moderator’s display name.
   last_activated_at String The UTC timestamp (in RFC3339 format) of when Shield Mode was last activated.

Response Codes

Code Description
200 OK Successfully updated the broadcaster’s Shield Mode status.
400 Bad Request
  • The broadcaster_id query parameter is required.
  • The ID in the broadcaster_id query parameter is not valid.
  • The is_active field is required.
  • The value in the is_active field is not valid.
401 Unauthorized
  • The ID in moderator_id must match the user ID in the user access token.
  • The Authorization header is required and must contain a user access token.
  • The user access token must include the moderator:manage:shield_mode scope.
  • The access token is not valid.
  • The client ID specified in the Client-Id header does not match the client ID specified in the access token.
403 Forbidden
  • The user in moderator_id is not one of the broadcaster's moderators.

Example Request

curl -X PUT 'https://api.twitch.tv/helix/moderation/shield_mode?broadcaster_id=12345&moderator_id=98765' \
-H 'Authorization: Bearer kpvy3cjboypmiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfn0yan9c87zr6t' \
-H 'Client-Type: application/json' \
-d '{"data":{"is_active":false}}'

Example Response

{
  "data": [
    {
      "is_active": false,
      "moderator_id": "98765",
      "moderator_name": "SimplySimple",
      "moderator_login": "simplysimple",
      "last_activated_at": "2022-07-26T17:16:03.123Z"
    }
  ]
}

Get Shield Mode Status

BETA Gets the broadcaster’s Shield Mode activation status.

To receive notification when the broadcaster activates and deactivates Shield Mode, subscribe to the channel.shield_mode.begin and channel.shield_mode.end subscription types.

Authorization

Requires a user access token that includes the moderator:read:shield_mode or moderator:manage:shield_mode scope.

URL

GET https://api.twitch.tv/helix/moderation/shield_mode

Request Query Parameters

Parameter Type Required? Description
broadcaster_id String Yes The ID of the broadcaster whose Shield Mode activation status you want to get.
moderator_id String Yes The ID of the broadcaster or a user that is one of the broadcaster’s moderators. This ID must match the user ID in the access token.

Response Body

Field Type Description
data Object[] A list that contains a single object with the broadcaster’s Shield Mode status.
   is_active Boolean A Boolean value that determines whether Shield Mode is active. Is true if the broadcaster activated Shield Mode; otherwise, false.
   moderator_id String An ID that identifies the moderator that last activated Shield Mode. Is an empty string if Shield Mode hasn’t been previously activated.
   moderator_login String The moderator’s login name. Is an empty string if Shield Mode hasn’t been previously activated.
   moderator_name String The moderator’s display name. Is an empty string if Shield Mode hasn’t been previously activated.
   last_activated_at String The UTC timestamp (in RFC3339 format) of when Shield Mode was last activated. Is an empty string if Shield Mode hasn’t been previously activated.

Response Codes

Code Description
200 OK Successfully retrieved the broadcaster’s Shield Mode activation status.
400 Bad Request
  • The broadcaster_id query parameter is required.
  • The ID in the broadcaster_id query parameter is not valid.
401 Unauthorized
  • The ID in moderator_id must match the user ID in the user access token.
  • The Authorization header is required and must contain a user access token.
  • The user access token must include the moderator:read:shield_mode or moderator:manage:shield_mode scope.
  • The access token is not valid.
  • The client ID specified in the Client-Id header does not match the client ID specified in the access token.
403 Forbidden
  • The user in moderator_id is not one of the broadcaster's moderators.

Example Request

curl -X GET 'https://api.twitch.tv/helix/moderation/shield_mode?broadcaster_id=12345&moderator_id=98765' \
-H 'Authorization: Bearer kpvy3cjboypmiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfn0yan9c87zr6t'

Example Response

{
  "data": [
    {
      "is_active": true,
      "moderator_id": "98765",
      "moderator_name": "SimplySimple",
      "moderator_login": "simplysimple",
      "last_activated_at": "2022-07-26T17:16:03.123Z"
    }
  ]
}

Get Polls

Gets a list of polls that the broadcaster created.

Polls are available for 90 days after they’re created.

Authorization

Requires a user access token that includes the channel:read:polls scope.

URL

GET https://api.twitch.tv/helix/polls

Request Query Parameters

Parameter Type Required? Description
broadcaster_id String Yes The ID of the broadcaster that created the polls. This ID must match the user ID in the user access token.
id String No A list of IDs that identify the polls to return. To specify more than one ID, include this parameter for each poll you want to get. For example, id=1234&id=5678. You may specify a maximum of 20 IDs.

Specify this parameter only if you want to filter the list that the request returns. The endpoint ignores duplicate IDs and those not owned by this broadcaster.
first String No The maximum number of items to return per page in the response. The minimum page size is 1 item per page and the maximum is 20 items per page. The default is 20.
after String No The cursor used to get the next page of results. The Pagination object in the response contains the cursor’s value. Read More

Response Body

Field Type Description
data Object[] A list of polls. The polls are returned in descending order of start time unless you specify IDs in the request, in which case they’re returned in the same order as you passed them in the request. The list is empty if the broadcaster hasn’t created polls.
   id String An ID that identifies the poll.
   broadcaster_id String An ID that identifies the broadcaster that created the poll.
   broadcaster_name String The broadcaster’s display name.
   broadcaster_login String The broadcaster’s login name.
   title String The question that viewers are voting on. For example, What game should I play next? The title may contain a maximum of 60 characters.
   choices Object[] A list of choices that viewers can choose from. The list will contain a minimum of two choices and up to a maximum of five choices.
      id String An ID that identifies this choice.
      title String The choice’s title. The title may contain a maximum of 25 characters.
      votes Integer The total number of votes cast for this choice.
      channel_points_votes Integer The number of votes cast using Channel Points.
      bits_votes Integer Not used; will be set to 0.
   bits_voting_enabled Boolean Not used; will be set to false.
   bits_per_vote Integer Not used; will be set to 0.
   channel_points_voting_enabled Boolean A Boolean value that indicates whether viewers may cast additional votes using Channel Points. For information about Channel Points, see Channel Points Guide.
   channel_points_per_vote Integer The number of points the viewer must spend to cast one additional vote.
   status String The poll’s status. Valid values are:
  • ACTIVE — The poll is running.
  • COMPLETED — The poll ended on schedule (see the duration field).
  • TERMINATED — The poll was terminated before its scheduled end.
  • ARCHIVED — The poll has been archived and is no longer visible on the channel.
  • MODERATED — The poll was deleted.
  • INVALID — Something went wrong while determining the state.
   duration Integer The length of time (in seconds) that the poll will run for.
   started_at String The UTC date and time (in RFC3339 format) of when the poll began.
   ended_at String The UTC date and time (in RFC3339 format) of when the poll ended. If status is ACTIVE, this field is set to null.
pagination Object Contains the information used to page through the list of results. The object is empty if there are no more pages left to page through. Read More
   cursor String The cursor used to get the next page of results. Use the cursor to set the request’s after query parameter.

Response Codes

Code Description
200 OK Successfully retrieved the broadcaster’s polls.
400 Bad Request
  • The broadcaster_id query parameter is required.
401 Unauthorized
  • The ID in broadcaster_id must match the user ID in the access token.
  • The Authorization header is required and must contain a user access token.
  • The user access token is missing the channel:read:polls scope.
  • The access token is not valid.
  • The client ID specified in the Client-Id header must match the client ID specified in the access token.
404 Not Found
  • None of the IDs in the id query parameters were found.

Example Request

Gets the specified broadcaster’s list of polls.

curl -X GET 'https://api.twitch.tv/helix/polls?broadcaster_id=141981764&id=ed961efd-8a3f-4cf5-a9d0-e616c590cd2a' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
  "data": [
    {
      "id": "ed961efd-8a3f-4cf5-a9d0-e616c590cd2a",
      "broadcaster_id": "55696719",
      "broadcaster_name": "TwitchDev",
      "broadcaster_login": "twitchdev",
      "title": "Heads or Tails?",
      "choices": [
        {
          "id": "4c123012-1351-4f33-84b7-43856e7a0f47",
          "title": "Heads",
          "votes": 0,
          "channel_points_votes": 0,
          "bits_votes": 0
        },
        {
          "id": "279087e3-54a7-467e-bcd0-c1393fcea4f0",
          "title": "Tails",
          "votes": 0,
          "channel_points_votes": 0,
          "bits_votes": 0
        }
      ],
      "bits_voting_enabled": false,
      "bits_per_vote": 0,
      "channel_points_voting_enabled": false,
      "channel_points_per_vote": 0,
      "status": "ACTIVE",
      "duration": 1800,
      "started_at": "2021-03-19T06:08:33.871278372Z"
    }
  ],
  "pagination": {}
}

Create Poll

Creates a poll that viewers in the broadcaster’s channel can vote on.

The poll begins as soon as it’s created. You may run only one poll at a time.

Authorization

Requires a user access token that includes the channel:manage:polls scope.

URL

POST https://api.twitch.tv/helix/polls

Request Body

Field Type Required? Description
broadcaster_id String Yes The ID of the broadcaster that’s running the poll. This ID must match the user ID in the user access token.
title String Yes The question that viewers will vote on. For example, What game should I play next? The question may contain a maximum of 60 characters.
choices Object[] Yes A list of choices that viewers may choose from. The list must contain a minimum of 2 choices and up to a maximum of 5 choices.
   title String Yes One of the choices the viewer may select. The choice may contain a maximum of 25 characters.
duration Integer Yes The length of time (in seconds) that the poll will run for. The minimum is 15 seconds and the maximum is 1800 seconds (30 minutes).
channel_points_voting_enabled Boolean No A Boolean value that indicates whether viewers may cast additional votes using Channel Points. If true, the viewer may cast more than one vote but each additional vote costs the number of Channel Points specified in channel_points_per_vote. The default is false (viewers may cast only one vote). For information about Channel Points, see Channel Points Guide.
channel_points_per_vote Integer No The number of points that the viewer must spend to cast one additional vote. The minimum is 1 and the maximum is 1000000. Set only if ChannelPointsVotingEnabled is true.

Response Body

Field Type Description
data Object[] A list that contains the single poll that you created.
   id String An ID that identifies the poll.
   broadcaster_id String An ID that identifies the broadcaster that created the poll.
   broadcaster_name String The broadcaster’s display name.
   broadcaster_login String The broadcaster’s login name.
   title String The question that viewers are voting on. For example, What game should I play next? The title may contain a maximum of 60 characters.
   choices Object[] A list of choices that viewers can choose from. The list will contain a minimum of two choices and up to a maximum of five choices.
      id String An ID that identifies this choice.
      title String The choice’s title. The title may contain a maximum of 25 characters.
      votes Integer The total number of votes cast for this choice.
      channel_points_votes Integer The number of votes cast using Channel Points.
      bits_votes Integer Not used; will be set to 0.
   bits_voting_enabled Boolean Not used; will be set to false.
   bits_per_vote Integer Not used; will be set to 0.
   channel_points_voting_enabled Boolean A Boolean value that indicates whether viewers may cast additional votes using Channel Points. For information about Channel Points, see Channel Points Guide.
   channel_points_per_vote Integer The number of points the viewer must spend to cast one additional vote.
   status String The poll’s status. Valid values are:
  • ACTIVE — The poll is running.
  • COMPLETED — The poll ended on schedule (see the duration field).
  • TERMINATED — The poll was terminated before its scheduled end.
  • ARCHIVED — The poll has been archived and is no longer visible on the channel.
  • MODERATED — The poll was deleted.
  • INVALID — Something went wrong while determining the state.
   duration Integer The length of time (in seconds) that the poll will run for.
   started_at String The UTC date and time (in RFC3339 format) of when the poll began.
   ended_at String The UTC date and time (in RFC3339 format) of when the poll ended. If status is ACTIVE, this field is set to null.

Response Codes

Code Description
200 OK Successfully created the poll.
400 Bad Request
  • The broadcaster_id field is required.
  • The title field is required.
  • The choices field is required.
  • The duration field is required.
  • The value in duration is outside the allowed range of values.
  • The value in channel_points_per_vote is outside the allowed range of values.
  • The value in bits_per_vote is outside the allowed range of values.
  • The poll's title is too long.
  • The choice's title is too long.
  • The choice's title failed AutoMod checks.
  • The number of choices in the poll may not be less than 2 or greater that 5.
  • The broadcaster already has a poll that's running; you may not create another poll until the current poll completes.
401 Unauthorized
  • The ID in broadcaster_id must match the user ID in the access token.
  • The Authorization header is required and must contain a user access token.
  • The user access token is missing the channel:manage:polls scope.
  • The access token is not valid.
  • The client ID specified in the Client-Id header does not match the client ID specified in the access token.

Example Request

Creates a poll for the specified broadcaster.

curl -X POST 'https://api.twitch.tv/helix/polls' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Content-Type: application/json' \
-d '{
  "broadcaster_id":"141981764",
  "title":"Heads or Tails?",
  "choices":[{
    "title":"Heads"
  },
  {
    "title":"Tails"
  }],
  "channel_points_voting_enabled":true,
  "channel_points_per_vote":100,
  "duration":1800
}'

Example Response

{
  "data": [
    {
      "id": "ed961efd-8a3f-4cf5-a9d0-e616c590cd2a",
      "broadcaster_id": "141981764",
      "broadcaster_name": "TwitchDev",
      "broadcaster_login": "twitchdev",
      "title": "Heads or Tails?",
      "choices": [
        {
          "id": "4c123012-1351-4f33-84b7-43856e7a0f47",
          "title": "Heads",
          "votes": 0,
          "channel_points_votes": 0,
          "bits_votes": 0
        },
        {
          "id": "279087e3-54a7-467e-bcd0-c1393fcea4f0",
          "title": "Tails",
          "votes": 0,
          "channel_points_votes": 0,
          "bits_votes": 0
        }
      ],
      "bits_voting_enabled": false,
      "bits_per_vote": 0,
      "channel_points_voting_enabled": true,
      "channel_points_per_vote": 100,
      "status": "ACTIVE",
      "duration": 1800,
      "started_at": "2021-03-19T06:08:33.871278372Z"
    }
  ]
}

End Poll

Ends an active poll. You have the option to end it or end it and archive it.

Authorization

Requires a user access token that includes the channel:manage:polls scope.

URL

PATCH https://api.twitch.tv/helix/polls

Request Body

Field Type Required? Description
broadcaster_id String Yes The ID of the broadcaster that’s running the poll. This ID must match the user ID in the user access token.
id String Yes The ID of the poll to update.
status String Yes The status to set the poll to. Possible case-sensitive values are:
  • TERMINATED — Ends the poll before the poll is scheduled to end. The poll remains publicly visible.
  • ARCHIVED — Ends the poll before the poll is scheduled to end, and then archives it so it's no longer publicly visible.

Response Body

Field Type Description
data Object[] A list that contains the poll that you ended.
   id String An ID that identifies the poll.
   broadcaster_id String An ID that identifies the broadcaster that created the poll.
   broadcaster_name String The broadcaster’s display name.
   broadcaster_login String The broadcaster’s login name.
   title String The question that viewers are voting on. For example, What game should I play next? The title may contain a maximum of 60 characters.
   choices Object[] A list of choices that viewers can choose from. The list will contain a minimum of two choices and up to a maximum of five choices.
      id String An ID that identifies this choice.
      title String The choice’s title. The title may contain a maximum of 25 characters.
      votes Integer The total number of votes cast for this choice.
      channel_points_votes Integer The number of votes cast using Channel Points.
      bits_votes Integer Not used; will be set to 0.
   bits_voting_enabled Boolean Not used; will be set to false.
   bits_per_vote Integer Not used; will be set to 0.
   channel_points_voting_enabled Boolean A Boolean value that indicates whether viewers may cast additional votes using Channel Points. For information about Channel Points, see Channel Points Guide.
   channel_points_per_vote Integer The number of points the viewer must spend to cast one additional vote.
   status String The poll’s status. Valid values are:
  • ACTIVE — The poll is running.
  • COMPLETED — The poll ended on schedule (see the duration field).
  • TERMINATED — The poll was terminated before its scheduled end.
  • ARCHIVED — The poll has been archived and is no longer visible on the channel.
  • MODERATED — The poll was deleted.
  • INVALID — Something went wrong while determining the state.
   duration Integer The length of time (in seconds) that the poll will run for.
   started_at String The UTC date and time (in RFC3339 format) of when the poll began.
   ended_at String The UTC date and time (in RFC3339 format) of when the poll ended. If status is ACTIVE, this field is set to null.

Response Codes

Code Description
200 OK Successfully ended the poll.
400 Bad Request
  • The broadcaster_id field is required.
  • The id field is required.
  • The status field is required.
  • The value in the status field is not valid.
  • The poll must be active to terminate or archive it.
401 Unauthorized
  • The ID in broadcaster_id must match the user ID in the user access token.
  • The Authorization header is required and must contain a user access token.
  • The user access token must include the channel:manage:polls scope.
  • The access token is not valid.
  • The client ID specified in the Client-Id header must match the client ID specified in the access token.

Example Request

Ends the specific poll, but allows the results to be visible for viewers.

curl -X PATCH 'https://api.twitch.tv/helix/polls' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Content-Type: application/json' \
-d '{
  "broadcaster_id":"141981764",
  "id":"ed961efd-8a3f-4cf5-a9d0-e616c590cd2a",
  "status":"TERMINATED"
}'

Example Response

{
  "data": [
    {
      "id": "ed961efd-8a3f-4cf5-a9d0-e616c590cd2a",
      "broadcaster_id": "141981764",
      "broadcaster_name": "TwitchDev",
      "broadcaster_login": "twitchdev",
      "title": "Heads or Tails?",
      "choices": [
        {
          "id": "4c123012-1351-4f33-84b7-43856e7a0f47",
          "title": "Heads",
          "votes": 0,
          "channel_points_votes": 0,
          "bits_votes": 0
        },
        {
          "id": "279087e3-54a7-467e-bcd0-c1393fcea4f0",
          "title": "Tails",
          "votes": 0,
          "channel_points_votes": 0,
          "bits_votes": 0
        }
      ],
      "bits_voting_enabled": false,
      "bits_per_vote": 0,
      "channel_points_voting_enabled": true,
      "channel_points_per_vote": 100,
      "status": "TERMINATED",
      "duration": 1800,
      "started_at": "2021-03-19T06:08:33.871278372Z",
      "ended_at": "2021-03-19T06:11:26.746889614Z"
    }
  ]
}

Get Predictions

Gets a list of Channel Points Predictions that the broadcaster created.

Authorization

Requires a user access token that includes the channel:read:predictions scope.

URL

GET https://api.twitch.tv/helix/predictions

Request Query Parameters

Parameter Type Required? Description
broadcaster_id String Yes The ID of the broadcaster whose predictions you want to get. This ID must match the user ID associated with the user access token.
id String No The ID of the prediction to get. To specify more than one ID, include this parameter for each prediction you want to get. For example, id=1234&id=5678. You may specify a maximum of 25 IDs. The endpoint ignores duplicate IDs and those not owned by the broadcaster.
first String No The maximum number of items to return per page in the response. The minimum page size is 1 item per page and the maximum is 25 items per page. The default is 20.
after String No The cursor used to get the next page of results. The Pagination object in the response contains the cursor’s value. Read More

Response Body

Field Type Description
data Object[] The broadcaster’s list of Channel Points Predictions. The list is sorted in descending ordered by when the prediction began (the most recent prediction is first). The list is empty if the broadcaster hasn’t created predictions.
   id String An ID that identifies this prediction.
   broadcaster_id String An ID that identifies the broadcaster that created the prediction.
   broadcaster_name String The broadcaster’s display name.
   broadcaster_login String The broadcaster’s login name.
   title String The question that the prediction asks. For example, Will I finish this entire pizza?
   winning_outcome_id String The ID of the winning outcome. Is null unless status is RESOLVED.
   outcomes Object[] The list of possible outcomes for the prediction.
      id String An ID that identifies this outcome.
      title String The outcome’s text.
      users Integer The number of unique viewers that chose this outcome.
      channel_points Integer The number of Channel Points spent by viewers on this outcome.
      top_predictors Object[] A list of viewers who were the top predictors; otherwise, null if none.
         user_id String An ID that identifies the viewer.
         user_name String The viewer’s display name.
         user_login String The viewer’s login name.
         channel_points_used Integer The number of Channel Points the viewer spent.
         channel_points_won Integer The number of Channel Points distributed to the viewer.
      color String The color that visually identifies this outcome in the UX. Possible values are:
  • BLUE
  • PINK
If the number of outcomes is two, the color is BLUE for the first outcome and PINK for the second outcome. If there are more than two outcomes, the color is BLUE for all outcomes.
   prediction_window Integer The length of time (in seconds) that the prediction will run for.
   status String The prediction’s status. Valid values are:
  • ACTIVE — The Prediction is running and viewers can make predictions.
  • CANCELED — The broadcaster canceled the Prediction and refunded the Channel Points to the participants.
  • LOCKED — The broadcaster locked the Prediction, which means viewers can no longer make predictions.
  • RESOLVED — The winning outcome was determined and the Channel Points were distributed to the viewers who predicted the correct outcome.
   created_at String The UTC date and time of when the Prediction began.
   ended_at String The UTC date and time of when the Prediction ended. If status is ACTIVE, this is set to null.
   locked_at String The UTC date and time of when the Prediction was locked. If status is not LOCKED, this is set to null.
pagination Object Contains the information used to page through the list of results. The object is empty if there are no more pages left to page through. Read More
   cursor String The cursor used to get the next page of results. Use the cursor to set the request’s after query parameter.

Response Codes

Code Description
200 OK Successfully retrieved the list of predictions.
400 Bad Request
  • The broadcaster_id query parameter is required.
401 Unauthorized
  • The ID in broadcaster_id must match the user ID in the access token.
  • The Authorization header is required and must contain a user access token.
  • The user access token must include the channel:read:predictions scope.
  • The access token is not valid.
  • The client ID specified in the Client-Id header does not match the client ID specified in the access token.

Example Request

Gets the specified broadcaster’s list of predictions.

curl -X GET 'https://api.twitch.tv/helix/predictions?broadcaster_id=55696719&id=d6676d5c-c86e-44d2-bfc4-100fb48f0656' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
  "data": [
    {
      "id": "d6676d5c-c86e-44d2-bfc4-100fb48f0656",
      "broadcaster_id": "55696719",
      "broadcaster_name": "TwitchDev",
      "broadcaster_login": "twitchdev",
      "title": "Will there be any leaks today?",
      "winning_outcome_id": null,
      "outcomes": [
        {
          "id": "021e9234-5893-49b4-982e-cfe9a0aaddd9",
          "title": "Yes",
          "users": 0,
          "channel_points": 0,
          "top_predictors": null,
          "color": "BLUE"
        },
        {
          "id": "ded84c26-13cb-4b48-8cb5-5bae3ec3a66e",
          "title": "No",
          "users": 0,
          "channel_points": 0,
          "top_predictors": null,
          "color": "PINK"
        }
      ],
      "prediction_window": 600,
      "status": "ACTIVE",
      "created_at": "2021-04-28T16:03:06.320848689Z",
      "ended_at": null,
      "locked_at": null
    }
  ],
  "pagination": {}
}

Create Prediction

Creates a Channel Points Prediction.

With a Channel Points Prediction, the broadcaster poses a question and viewers try to predict the outcome. The prediction runs as soon as it’s created. The broadcaster may run only one prediction at a time.

Authorization

Requires a user access token that includes the channel:manage:predictions scope.

URL

POST https://api.twitch.tv/helix/predictions

Request Body

Field Type Required? Description
broadcaster_id String Yes The ID of the broadcaster that’s running the prediction. This ID must match the user ID in the user access token.
title String Yes The question that the broadcaster is asking. For example, Will I finish this entire pizza? The title is limited to a maximum of 45 characters.
outcomes Object[] Yes The list of possible outcomes that the viewers may choose from. The list must contain a minimum of 2 choices and up to a maximum of 10 choices.
   title String Yes The text of one of the outcomes that the viewer may select. The title is limited to a maximum of 25 characters.
prediction_window Integer Yes The length of time (in seconds) that the prediction will run for. The minimum is 30 seconds and the maximum is 1800 seconds (30 minutes).

Response Body

Field Type Description
data Object[] A list that contains the single prediction that you created.
   id String An ID that identifies this prediction.
   broadcaster_id String An ID that identifies the broadcaster that created the prediction.
   broadcaster_name String The broadcaster’s display name.
   broadcaster_login String The broadcaster’s login name.
   title String The question that the prediction asks. For example, Will I finish this entire pizza?
   winning_outcome_id String The ID of the winning outcome. Is null unless status is RESOLVED.
   outcomes Object[] The list of possible outcomes for the prediction.
      id String An ID that identifies this outcome.
      title String The outcome’s text.
      users Integer The number of unique viewers that chose this outcome.
      channel_points Integer The number of Channel Points spent by viewers on this outcome.
      top_predictors Object[] A list of viewers who were the top predictors; otherwise, null if none.
         user_id String An ID that identifies the viewer.
         user_name String The viewer’s display name.
         user_login String The viewer’s login name.
         channel_points_used Integer The number of Channel Points the viewer spent.
         channel_points_won Integer The number of Channel Points distributed to the viewer.
      color String The color that visually identifies this outcome in the UX. Possible values are:
  • BLUE
  • PINK
If the number of outcomes is two, the color is BLUE for the first outcome and PINK for the second outcome. If there are more than two outcomes, the color is BLUE for all outcomes.
   prediction_window Integer The length of time (in seconds) that the prediction will run for.
   status String The prediction’s status. Valid values are:
  • ACTIVE — The Prediction is running and viewers can make predictions.
  • CANCELED — The broadcaster canceled the Prediction and refunded the Channel Points to the participants.
  • LOCKED — The broadcaster locked the Prediction, which means viewers can no longer make predictions.
  • RESOLVED — The winning outcome was determined and the Channel Points were distributed to the viewers who predicted the correct outcome.
   created_at String The UTC date and time of when the Prediction began.
   ended_at String The UTC date and time of when the Prediction ended. If status is ACTIVE, this is set to null.
   locked_at String The UTC date and time of when the Prediction was locked. If status is not LOCKED, this is set to null.

Response Codes

Code Description
200 OK Successfully created the Channel Points Prediction.
400 Bad Request
  • The broadcaster_id field is required.
  • The title field is required.
  • The outcomes field is required.
  • The prediction_window field is required.
  • The value in prediction_window is outside the allowed range of values.
  • The prediction's title is too long.
  • The outcome's title is too long.
  • The outcome's title failed AutoMod checks.
  • There must be 2 outcomes in the prediction.
  • The broadcaster already has a prediction that's running; you may not create another prediction until the current prediction is resolved or canceled.
401 Unauthorized
  • The ID in broadcaster_id must match the user ID in the access token.
  • The Authorization header is required and must contain a user access token.
  • The user access token must include the channel:manage:predictions scope.
  • The access token is not valid.
  • The client ID specified in the Client-Id header does not match the client ID specified in the access token.
429 Too Many Requests  

Example Request

Creates a Channel Points Prediction for the specified broadcaster.

curl -X POST 'https://api.twitch.tv/helix/predictions' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Content-Type: application/json' \
-d '{
  "broadcaster_id": "141981764",
  "title": "Any leeks in the stream?",
  "outcomes": [
    {
      "title": "Yes, give it time."
    },
    {
      "title": "Definitely not."
    }
  ],
  "prediction_window": 120
}'

Example Response

{
  "data": [
    {
      "id": "bc637af0-7766-4525-9308-4112f4cbf178",
      "broadcaster_id": "141981764",
      "broadcaster_name": "TwitchDev",
      "broadcaster_login": "twitchdev",
      "title": "Any leeks in the stream?",
      "winning_outcome_id": null,
      "outcomes": [
        {
          "id": "73085848-a94d-4040-9d21-2cb7a89374b7",
          "title": "Yes, give it time.",
          "users": 0,
          "channel_points": 0,
          "top_predictors": null,
          "color": "BLUE"
        },
        {
          "id": "906b70ba-1f12-47ea-9e95-e5f93d20e9cc",
          "title": "Definitely not.",
          "users": 0,
          "channel_points": 0,
          "top_predictors": null,
          "color": "PINK"
        }
      ],
      "prediction_window": 120,
      "status": "ACTIVE",
      "created_at": "2021-04-28T17:11:22.595914172Z",
      "ended_at": null,
      "locked_at": null
    }
  ]
}

End Prediction

Locks, resolves, or cancels a Channel Points Prediction.

Authorization

Requires a user access token that includes the channel:manage:predictions scope.

URL

PATCH https://api.twitch.tv/helix/predictions

Request Body

Field Type Required? Description
broadcaster_id String Yes The ID of the broadcaster that’s running the prediction. This ID must match the user ID in the user access token.
id String Yes The ID of the prediction to update.
status String Yes The status to set the prediction to. Possible case-sensitive values are:
  • RESOLVED — The winning outcome is determined and the Channel Points are distributed to the viewers who predicted the correct outcome.
  • CANCELED — The broadcaster is canceling the prediction and sending refunds to the participants.
  • LOCKED — The broadcaster is locking the prediction, which means viewers may no longer make predictions.
The broadcaster can update an active prediction to LOCKED, RESOLVED, or CANCELED; and update a locked prediction to RESOLVED or CANCELED.

The broadcaster has up to 24 hours after the prediction window closes to resolve the prediction. If not, Twitch sets the status to CANCELED and returns the points.
winning_outcome_id String No The ID of the winning outcome. You must set this parameter if you set status to RESOLVED.

Response Body

Field Type Description
data Object[] A list that contains the single prediction that you updated.
   id String An ID that identifies this prediction.
   broadcaster_id String An ID that identifies the broadcaster that created the prediction.
   broadcaster_name String The broadcaster’s display name.
   broadcaster_login String The broadcaster’s login name.
   title String The question that the prediction asks. For example, Will I finish this entire pizza?
   winning_outcome_id String The ID of the winning outcome. Is null unless status is RESOLVED.
   outcomes Object[] The list of possible outcomes for the prediction.
      id String An ID that identifies this outcome.
      title String The outcome’s text.
      users Integer The number of unique viewers that chose this outcome.
      channel_points Integer The number of Channel Points spent by viewers on this outcome.
      top_predictors Object[] A list of viewers who were the top predictors; otherwise, null if none.
         user_id String An ID that identifies the viewer.
         user_name String The viewer’s display name.
         user_login String The viewer’s login name.
         channel_points_used Integer The number of Channel Points the viewer spent.
         channel_points_won Integer The number of Channel Points distributed to the viewer.
      color String The color that visually identifies this outcome in the UX. Possible values are:
  • BLUE
  • PINK
If the number of outcomes is two, the color is BLUE for the first outcome and PINK for the second outcome. If there are more than two outcomes, the color is BLUE for all outcomes.
   prediction_window Integer The length of time (in seconds) that the prediction will run for.
   status String The prediction’s status. Valid values are:
  • ACTIVE — The Prediction is running and viewers can make predictions.
  • CANCELED — The broadcaster canceled the Prediction and refunded the Channel Points to the participants.
  • LOCKED — The broadcaster locked the Prediction, which means viewers can no longer make predictions.
  • RESOLVED — The winning outcome was determined and the Channel Points were distributed to the viewers who predicted the correct outcome.
   created_at String The UTC date and time of when the Prediction began.
   ended_at String The UTC date and time of when the Prediction ended. If status is ACTIVE, this is set to null.
   locked_at String The UTC date and time of when the Prediction was locked. If status is not LOCKED, this is set to null.

Response Codes

Code Description
200 OK Successfully updated the prediction.
400 Bad Request
  • The broadcaster_id field is required.
  • The id field is required.
  • The status field is required.
  • The winning_outcome_id field is required if status is RESOLVED.
  • The value in the status field is not valid.
  • To update the prediction's status to RESOLVED or CANCELED, its current status must be ACTIVE or LOCKED.
  • To update the prediction's status to LOCKED, its current status must be ACTIVE.
401 Unauthorized
  • The ID in broadcaster_id must match the user ID in the OAuth token.
  • The Authorization header is required and must contain a user access token.
  • The user access token must include the channel:manage:predictions scope.
  • The access token is not valid.
  • The client ID specified in the Client-Id header does not match the client ID specified in the access token.
404 Not Found
  • The prediction in the id field was not found.
  • The outcome in the winning_outcome_id field was not found.

Example Request

Resolves the specified Channel Points Prediction.

curl -X PATCH 'https://api.twitch.tv/helix/predictions' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Content-Type: application/json' \
-d  '{
  "broadcaster_id": "141981764",
  "id": "bc637af0-7766-4525-9308-4112f4cbf178",
  "status": "RESOLVED",
  "winning_outcome_id": "73085848-a94d-4040-9d21-2cb7a89374b7"
}'

Example Response

{
  "data": [
    {
      "id": "bc637af0-7766-4525-9308-4112f4cbf178",
      "broadcaster_id": "141981764",
      "broadcaster_name": "TwitchDev",
      "broadcaster_login": "twitchdev",
      "title": "Will we win all the games?",
      "winning_outcome_id": "73085848-a94d-4040-9d21-2cb7a89374b7",
      "outcomes": [
        {
          "id": "73085848-a94d-4040-9d21-2cb7a89374b7",
          "title": "yes",
          "users": 0,
          "channel_points": 0,
          "top_predictors": null,
          "color": "BLUE"
        },
        {
          "id": "86010b2e-9764-4136-9359-fd1c9c5a8033",
          "title": "no",
          "users": 0,
          "channel_points": 0,
          "top_predictors": null,
          "color": "PINK"
        }
      ],
      "prediction_window": 120,
      "status": "RESOLVED",
      "created_at": "2021-04-28T21:48:19.480371331Z",
      "ended_at": "2021-04-28T21:54:24.026833954Z",
      "locked_at": "2021-04-28T21:48:34.636685705Z"
    }
  ]
}

Start a raid

Raid another channel by sending the broadcaster’s viewers to the targeted channel.

When you call the API from a chat bot or extension, the Twitch UX pops up a window at the top of the chat room that identifies the number of viewers in the raid. The raid occurs when the broadcaster clicks Raid Now or after the 90-second countdown expires.

To determine whether the raid successfully occurred, you must subscribe to the Channel Raid event. For more information, see Get notified when a raid begins.

To cancel a pending raid, use the Cancel a raid endpoint.

Rate Limit: The limit is 10 requests within a 10-minute window.

Authorization

Requires a user access token that includes the channel:manage:raids scope.

URL

POST https://api.twitch.tv/helix/raids

Request Query Parameters

Parameter Type Required ? Description
from_broadcaster_id String Yes The ID of the broadcaster that’s sending the raiding party. This ID must match the user ID associated with the user access token.
to_broadcaster_id String Yes The ID of the broadcaster to raid.

Response Body

Field Type Description
data Object[] A list that contains a single object with information about the pending raid.
   created_at String The UTC date and time, in RFC3339 format, of when the raid was requested.
   is_mature Boolean A Boolean value that indicates whether the channel being raided contains mature content.

Response Codes

Code Description
200 OK Successfully requested to start a raid. To determine whether the raid successfully occurred (that is, the broadcaster clicked Raid Now or the countdown expired), you must subscribe to the Channel Raid event.
400 Bad Request
  • The raiding broadcaster is blocked from the targeted channel.
  • The targeted channel doesn't accept raids from this broadcaster.
  • There are too many viewers in the raiding party.
  • The IDs in from_broadcaster_id and to_broadcaster_id cannot be the same ID.
  • The ID in the from_broadcaster_id query parameter is not valid.
  • The ID in the to_broadcaster_id query parameter is not valid.
401 Unauthorized
  • The ID in from_broadcaster_id must match the user ID found in the request’s OAuth token.
  • The Authorization header is required and must contain a user access token.
  • The user access token must include the channel:manage:raids scope.
  • The access token is not valid.
  • The client ID specified in the Client-Id header does not match the client ID specified in the access token.
404 Not Found
  • The targeted channel was not found.
409 Conflict
  • The broadcaster is already in the process of raiding another channel.
429 Too Many Requests
  • The broadcaster exceeded the number of raid requests that they may make. The limit is 10 requests within a 10-minute window.

Example Request

curl -X POST 'https://api.twitch.tv/helix/raids?from_broadcaster_id=12345678&to_broadcaster_id=87654321' \
-H 'Authorization: Bearer kpvy3cjboyptmdkiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfnys0nyan9c87zr6t'

Example Response

{
  "data": [
    {
      "created_at": "2022-02-18T07:20:50.52Z",
      "is_mature": false
    }
  ]
}

Cancel a raid

Cancel a pending raid.

You can cancel a raid at any point up until the broadcaster clicks Raid Now in the Twitch UX or the 90-second countdown expires.

Rate Limit: The limit is 10 requests within a 10-minute window.

Authorization

Requires a user access token that includes the channel:manage:raids scope.

URL

DELETE https://api.twitch.tv/helix/raids

Request Query Parameters

Parameter Type Required? Description
broadcaster_id String Yes The ID of the broadcaster that initiated the raid. This ID must match the user ID associated with the user access token.

Response Codes

Code Description
204 No Content The pending raid was successfully canceled.
400 Bad Request
  • The ID in the broadcaster_id query parameter is not valid.
401 Unauthorized
  • The ID in broadcaster_id must match the user ID found in the request’s OAuth token.
  • The Authorization header is required and must contain a user access token.
  • The user access token must include the channel:manage:raids scope.
  • The access token is not valid.
  • The client ID specified in the Client-Id header does not match the client ID specified in the access token.
404 Not Found
  • The broadcaster doesn't have a pending raid to cancel.
429 Too Many Requests
  • The broadcaster exceeded the number of raid requests that they may make. The limit is 10 requests within a 10-minute window.

Example Request

curl -X DELETE 'https://api.twitch.tv/helix/raids?broadcaster_id=12345678' \
-H 'Authorization: Bearer kpvy3cjboyptmdkiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfnys0nyan9c87zr6t'

Get Channel Stream Schedule

Gets the broadcaster’s streaming schedule. You can get the entire schedule or specific segments of the schedule. Learn More

Authorization

Requires an app access token or user access token.

URL

GET https://api.twitch.tv/helix/schedule

Request Query Parameters

Parameter Type Required? Description
broadcaster_id String Yes The ID of the broadcaster that owns the streaming schedule you want to get.
id String No The ID of the scheduled segment to return. To specify more than one segment, include the ID of each segment you want to get. For example, id=1234&id=5678. You may specify a maximum of 100 IDs.
start_time String No The UTC date and time that identifies when in the broadcaster’s schedule to start returning segments. If not specified, the request returns segments starting after the current UTC date and time. Specify the date and time in RFC3339 format (for example, 2022-09-01T00:00:00Z).
utc_offset String No Not supported.
first Integer No The maximum number of items to return per page in the response. The minimum page size is 1 item per page and the maximum is 25 items per page. The default is 20.
after String No The cursor used to get the next page of results. The Pagination object in the response contains the cursor’s value. Read More

Response Body

Field Type Description
data Object The broadcaster’s streaming schedule.
   segments Object[] The list of broadcasts in the broadcaster’s streaming schedule.
      id String An ID that identifies this broadcast segment.
      start_time String The UTC date and time (in RFC3339 format) of when the broadcast starts.
      end_time String The UTC date and time (in RFC3339 format) of when the broadcast ends.
      title String The broadcast segment’s title.
      canceled_until String Indicates whether the broadcaster canceled this segment of a recurring broadcast. If the broadcaster canceled this segment, this field is set to the same value that’s in the end_time field; otherwise, it’s set to null.
      category Object The type of content that the broadcaster plans to stream or null if not specified.
         id String An ID that identifies the category that best represents the content that the broadcaster plans to stream. For example, the game’s ID if the broadcaster will play a game or the Just Chatting ID if the broadcaster will host a talk show.
         name String The name of the category. For example, the game’s title if the broadcaster will playing a game or Just Chatting if the broadcaster will host a talk show.
      is_recurring Boolean A Boolean value that determines whether the broadcast is part of a recurring series that streams at the same time each week or is a one-time broadcast. Is true if the broadcast is part of a recurring series.
   broadcaster_id String The ID of the broadcaster that owns the broadcast schedule.
   broadcaster_name String The broadcaster’s display name.
   broadcaster_login String The broadcaster’s login name.
   vacation Object The dates when the broadcaster is on vacation and not streaming. Is set to null if vacation mode is not enabled.
      start_time String The UTC date and time (in RFC3339 format) of when the broadcaster’s vacation starts.
      end_time String The UTC date and time (in RFC3339 format) of when the broadcaster’s vacation ends.
   pagination Object The information used to page through a list of results. The object is empty if there are no more pages left to page through. Read more.
      cursor String The cursor used to get the next page of results. Set the request’s after query parameter to this value.

Response Codes

Code Description
200 OK Successfully retrieved the broadcaster’s streaming schedule.
400 Bad Request
  • The broadcaster_id query parameter is required.
  • The ID in the broadcaster_id query parameter is not valid.
  • The ID in the id query parameter is not valid.
  • The format of the date and time in the start_time query parameter is not valid.
401 Unauthorized
  • The Authorization header is required and must specify a valid app access token or user access token.
  • The access token is not valid.
  • The ID in the Client-Id header must match the Client ID in the access token.
403 Forbidden
  • Only partners and affiliates may add non-recurring broadcast segments.
404 Not Found
  • The broadcaster has not created a streaming schedule.

Example Request

Gets the specified broadcaster’s streaming schedule.

curl -X GET 'https://api.twitch.tv/helix/schedule?broadcaster_id=141981764' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
  "data": {
    "segments": [
      {
        "id": "eyJzZWdtZW50SUQiOiJlNGFjYzcyNC0zNzFmLTQwMmMtODFjYS0yM2FkYTc5NzU5ZDQiLCJpc29ZZWFyIjoyMDIxLCJpc29XZWVrIjoyNn0=",
        "start_time": "2021-07-01T18:00:00Z",
        "end_time": "2021-07-01T19:00:00Z",
        "title": "TwitchDev Monthly Update // July 1, 2021",
        "canceled_until": null,
        "category": {
            "id": "509670",
            "name": "Science & Technology"
        },
        "is_recurring": false
      },
      ...
    ],
    "broadcaster_id": "141981764",
    "broadcaster_name": "TwitchDev",
    "broadcaster_login": "twitchdev",
    "vacation": null
  },
  "pagination": {}
}

Get Channel iCalendar

Gets the broadcaster’s streaming schedule as an iCalendar.

Authorization

The Client-Id and Authorization headers are not required.

URL

GET https://api.twitch.tv/helix/schedule/icalendar

Request Query Parameters

Parameter Type Required? Description
broadcaster_id String Yes The ID of the broadcaster that owns the streaming schedule you want to get.

Response Body

The response body contains the iCalendar data (see RFC5545).

The Content-Type response header is set to text/calendar.

Response Codes

Code Description
200 OK Successfully retrieved the broadcaster’s schedule as an iCalendar.
400 Bad Request
  • The broadcaster_id query parameter is required.
  • The ID in the broadcaster_id query parameter is not valid.

Example Request

Gets the specified broadcaster’s streaming schedule as an iCalendar.

curl -X GET 'https://api.twitch.tv/helix/schedule/icalendar?broadcaster_id=141981764'

Example Response

BEGIN:VCALENDAR
PRODID:-//twitch.tv//StreamSchedule//1.0
VERSION:2.0
CALSCALE:GREGORIAN
REFRESH-INTERVAL;VALUE=DURATION:PT1H
NAME:TwitchDev
BEGIN:VEVENT
UID:e4acc724-371f-402c-81ca-23ada79759d4
DTSTAMP:20210323T040131Z
DTSTART;TZID=/America/New_York:20210701T140000
DTEND;TZID=/America/New_York:20210701T150000
SUMMARY:TwitchDev Monthly Update // July 1, 2021
DESCRIPTION:Science & Technology.
CATEGORIES:Science & Technology
END:VEVENT
END:VCALENDAR%

Update Channel Stream Schedule

Updates the broadcaster’s schedule settings, such as scheduling a vacation.

Authorization

Requires a user access token that includes the channel:manage:schedule scope.

URL

PATCH https://api.twitch.tv/helix/schedule/settings

Request Query Parameters

Parameter Type Required? Description
broadcaster_id String Yes The ID of the broadcaster whose schedule settings you want to update. The ID must match the user ID in the user access token.
is_vacation_enabled Boolean No A Boolean value that indicates whether the broadcaster has scheduled a vacation. Set to true to enable Vacation Mode and add vacation dates, or false to cancel a previously scheduled vacation.
vacation_start_time String No The UTC date and time of when the broadcaster’s vacation starts. Specify the date and time in RFC3339 format (for example, 2021-05-16T00:00:00Z). Required if is_vacation_enabled is true.
vacation_end_time String No The UTC date and time of when the broadcaster’s vacation ends. Specify the date and time in RFC3339 format (for example, 2021-05-30T23:59:59Z). Required if is_vacation_enabled is true.
timezone String No The time zone that the broadcaster broadcasts from. Specify the time zone using IANA time zone database format (for example, America/New_York). Required if is_vacation_enabled is true.

Response Codes

Code Description
204 No Content Successfully updated the broadcaster’s schedule settings.
400 Bad Request
  • The broadcaster_id query parameter is required.
  • The ID in the broadcaster_id query parameter is not valid.
  • The format of the string in vacation_start_time is not valid.
  • The format of the string in vacation_end_time is not valid.
  • The date in vacation_end_time must be later than the date in vacation_start_time.
401 Unauthorized
  • The ID in the broadcaster_id query parameter must match the user ID in the user access token.
  • The Authorization header is required and must contain a user access token.
  • The user access token must include the channel:manage:schedule scope.
  • The access token is not valid.
  • The ID in the Client-Id header must match the client ID in the access token.
404 Not Found
  • The broadcaster's schedule was not found.

Example Request

Schedules the broadcaster’s vacation.

curl -X PATCH 'https://api.twitch.tv/helix/schedule/settings?broadcaster_id=141981764&is_vacation_enabled=true&vacation_start_time=2021-05-16T00:00:00Z&vacation_end_time=2021-05-23T00:00:00Z&timezone=America/New_York' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Create Channel Stream Schedule Segment

Adds a single or recurring broadcast to the broadcaster’s streaming schedule. For information about scheduling broadcasts, see Stream Schedule.

Authorization

Requires a user access token that includes the channel:manage:schedule scope.

URL

POST https://api.twitch.tv/helix/schedule/segment

Request Query Parameters

Parameter Type Required? Description
broadcaster_id String Yes The ID of the broadcaster that owns the schedule to add the broadcast segment to. This ID must match the user ID in the user access token.

Request Body

Field Type Required? Description
start_time String Yes The date and time that the broadcast segment starts. Specify the date and time in RFC3339 format (for example, 2021-07-01T18:00:00Z).
timezone String Yes The time zone where the broadcast takes place. Specify the time zone using IANA time zone database format (for example, America/New_York).
duration String Yes The length of time, in minutes, that the broadcast is scheduled to run. The duration must be in the range 30 through 1380 (23 hours).
is_recurring Boolean Yes A Boolean value that determines whether the broadcast recurs weekly. Is true if the broadcast recurs weekly. Only partners and affiliates may add non-recurring broadcasts.
category_id String No The ID of the category that best represents the broadcast’s content. To get the category ID, use the Search Categories endpoint.
title String No The broadcast’s title. The title may contain a maximum of 140 characters.

Response Body

Field Type Description
data Object The broadcaster’s streaming scheduled.
   segments Object[] A list that contains the single broadcast segment that you added.
      id String An ID that identifies this broadcast segment.
      start_time String The UTC date and time (in RFC3339 format) of when the broadcast starts.
      end_time String The UTC date and time (in RFC3339 format) of when the broadcast ends.
      title String The broadcast segment’s title.
      canceled_until String Indicates whether the broadcaster canceled this segment of a recurring broadcast. If the broadcaster canceled this segment, this field is set to the same value that’s in the end_time field; otherwise, it’s set to null.
      category Object The type of content that the broadcaster plans to stream or null if not specified.
         id String An ID that identifies the category that best represents the content that the broadcaster plans to stream. For example, the game’s ID if the broadcaster will play a game or the Just Chatting ID if the broadcaster will host a talk show.
         name String The name of the category. For example, the game’s title if the broadcaster will play a game or Just Chatting if the broadcaster will host a talk show.
      is_recurring Boolean A Boolean value that determines whether the broadcast is part of a recurring series that streams at the same time each week or is a one-time broadcast. Is true if the broadcast is part of a recurring series.
   broadcaster_id String The ID of the broadcaster that owns the broadcast schedule.
   broadcaster_name String The broadcaster’s display name.
   broadcaster_login String The broadcaster’s login name.
   vacation Object The dates when the broadcaster is on vacation and not streaming. Is set to null if vacation mode is not enabled.
      start_time String The UTC date and time (in RFC3339 format) of when the broadcaster’s vacation starts.
      end_time String The UTC date and time (in RFC3339 format) of when the broadcaster’s vacation ends.

Response Codes

Code Description
200 Ok Successfully added the broadcast segment.
400 Bad Request
  • The broadcaster_id query parameter is required.
  • The ID in the broadcaster_id query parameter is not valid.
  • The format of the date and time in the start_time field is not valid.
  • The value in the timezone field is not valid.
  • The value in the duration field is not valid.
  • The ID in the category_id field is not valid.
  • The string in the title field is too long.
401 Unauthorized
  • The ID in the broadcaster_id query parameter must match the user ID in the user access token.
  • The Authorization header is required and must contain a user access token.
  • The user access token must include the channel:manage:schedule scope.
  • The access token is not valid.
  • The ID in the Client-Id header must match the client ID in the access token.
403 Forbidden
  • Only partners and affiliates may add non-recurring broadcast segments.

Example Request

Adds a non-recurring broadcast to the broadcaster’s streaming schedule.

curl -X POST 'https://api.twitch.tv/helix/schedule/segment?broadcaster_id=141981764' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Content-Type: application/json' \
-d '{
  "start_time": "2021-07-01T18:00:00Z",
  "timezone": "America/New_York",
  "is_recurring": false,
  "duration": "60",
  "category_id": "509670",
  "title": "TwitchDev Monthly Update // July 1, 2021"
}'

Example Response

{
  "data": {
    "segments": [
      {
        "id": "eyJzZWdtZW50SUQiOiJlNGFjYzcyNC0zNzFmLTQwMmMtODFjYS0yM2FkYTc5NzU5ZDQiLCJpc29ZZWFyIjoyMDIxLCJpc29XZWVrIjoyNn0=",
        "start_time": "2021-07-01T18:00:00Z",
        "end_time": "2021-07-01T19:00:00Z",
        "title": "TwitchDev Monthly Update // July 1, 2021",
        "canceled_until": null,
        "category": {
            "id": "509670",
            "name": "Science & Technology"
        },
        "is_recurring": false
      }
    ],
    "broadcaster_id": "141981764",
    "broadcaster_name": "TwitchDev",
    "broadcaster_login": "twitchdev",
    "vacation": null
  }
}

Update Channel Stream Schedule Segment

Updates a scheduled broadcast segment.

For recurring segments, updating a segment’s title, category, duration, and timezone, changes all segments in the recurring schedule, not just the specified segment.

Authorization

Requires a user access token that includes the channel:manage:schedule scope.

URL

PATCH https://api.twitch.tv/helix/schedule/segment

Request Query Parameters

Parameter Type Required? Description
broadcaster_id String Yes The ID of the broadcaster who owns the broadcast segment to update. This ID must match the user ID in the user access token.
id String Yes The ID of the broadcast segment to update.

Request Body

Field Type Required? Description
start_time String No The date and time that the broadcast segment starts. Specify the date and time in RFC3339 format (for example, 2022-08-02T06:00:00Z).

NOTE: Only partners and affiliates may update a broadcast’s start time and only for non-recurring segments.
duration String No The length of time, in minutes, that the broadcast is scheduled to run. The duration must be in the range 30 through 1380 (23 hours).
category_id String No The ID of the category that best represents the broadcast’s content. To get the category ID, use the Search Categories endpoint.
title String No The broadcast’s title. The title may contain a maximum of 140 characters.
is_canceled Boolean No A Boolean value that indicates whether the broadcast is canceled. Set to true to cancel the segment.

NOTE: For recurring segments, the API cancels the first segment after the current UTC date and time and not the specified segment (unless the specified segment is the next segment after the current UTC date and time).
timezone String No The time zone where the broadcast takes place. Specify the time zone using IANA time zone database format (for example, America/New_York).

Response Body

Field Type Description
data Object The broadcaster’s streaming scheduled.
   segments Object[] A list that contains the single broadcast segment that you updated.
      id String An ID that identifies this broadcast segment.
      start_time String The UTC date and time (in RFC3339 format) of when the broadcast starts.
      end_time String The UTC date and time (in RFC3339 format) of when the broadcast ends.
      title String The broadcast segment’s title.
      canceled_until String Indicates whether the broadcaster canceled this segment of a recurring broadcast. If the broadcaster canceled this segment, this field is set to the same value that’s in the end_time field; otherwise, it’s set to null.
      category Object The type of content that the broadcaster plans to stream or null if not specified.
         id String An ID that identifies the category that best represents the content that the broadcaster plans to stream. For example, the game’s ID if the broadcaster will play a game or the Just Chatting ID if the broadcaster will host a talk show.
         name String The name of the category. For example, the game’s title if the broadcaster will play a game or Just Chatting if the broadcaster will host a talk show.
      is_recurring Boolean A Boolean value that determines whether the broadcast is part of a recurring series that streams at the same time each week or is a one-time broadcast. Is true if the broadcast is part of a recurring series.
   broadcaster_id String The ID of the broadcaster that owns the broadcast schedule.
   broadcaster_name String The broadcaster’s display name.
   broadcaster_login String The broadcaster’s login name.
   vacation Object The dates when the broadcaster is on vacation and not streaming. Is set to null if vacation mode is not enabled.
      start_time String The UTC date and time (in RFC3339 format) of when the broadcaster’s vacation starts.
      end_time String The UTC date and time (in RFC3339 format) of when the broadcaster’s vacation ends.

Response Codes

Code Description
200 OK Successfully updated the broadcast segment.
400 Bad Request
  • The broadcaster_id query parameter is required.
  • The ID in the broadcaster_id query parameter is not valid.
  • The id query parameter is required.
  • The ID in the id query parameter is not valid.
  • The format of the date and time in the start_time field is not valid.
  • The value in the timezone field is not valid.
  • The value in the duration field is not valid.
  • The ID in the category_id field is not valid.
  • The string in the title field is too long.
401 Unauthorized
  • The ID in the broadcaster_id query parameter must match the user ID in the user access token.
  • The Authorization header is required and must contain a user access token.
  • The user access token must include the channel:manage:schedule scope.
  • The access token is not valid.
  • The ID in the Client-Id header must match the client ID in the access token.
404 Not Found
  • The specified broadcast segment was not found.

Example Request

Updates the duration of a non-recurring broadcast segment.

curl -X PATCH 'https://api.twitch.tv/helix/schedule/segment?broadcaster_id=141981764&id=eyJzZWdtZW50SUQiOiJlNGFjYzcyNC0zNzFmLTQwMmMtODFjYS0yM2FkYTc5NzU5ZDQiLCJpc29ZZWFyIjoyMDIxLCJpc29XZWVrIjoyNn0=' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
-H 'Content-Type: application/json' \
-d '{
  "duration": "120"
}'

Example Response

{
  "data": {
    "segments": [
      {
        "id": "eyJzZWdtZW50SUQiOiJlNGFjYzcyNC0zNzFmLTQwMmMtODFjYS0yM2FkYTc5NzU5ZDQiLCJpc29ZZWFyIjoyMDIxLCJpc29XZWVrIjoyNn0=",
        "start_time": "2021-07-01T18:00:00Z",
        "end_time": "2021-07-01T20:00:00Z",
        "title": "TwitchDev Monthly Update // July 1, 2021",
        "canceled_until": null,
        "category": {
            "id": "509670",
            "name": "Science & Technology"
        },
        "is_recurring": false
      }
    ],
    "broadcaster_id": "141981764",
    "broadcaster_name": "TwitchDev",
    "broadcaster_login": "twitchdev",
    "vacation": null
  }
}

Delete Channel Stream Schedule Segment

Removes a broadcast segment from the broadcaster’s streaming schedule.

NOTE: For recurring segments, removing a segment removes all segments in the recurring schedule.

Authorization

Requires a user access token that includes the channel:manage:schedule scope.

URL

DELETE https://api.twitch.tv/helix/schedule/segment

Request Query Parameters

Parameter Type Required? Description
broadcaster_id String Yes The ID of the broadcaster that owns the streaming schedule. This ID must match the user ID in the user access token.
id String Yes The ID of the broadcast segment to remove.

Response Codes

Code Description
204 No Content Successfully removed the broadcast segment.
400 Bad Request
  • The broadcaster_id query parameter is required.
  • The ID in the broadcaster_id query parameter is not valid.
  • The id query parameter is required.
  • The ID in the id query parameter is not valid.
401 Unauthorized
  • The ID in the broadcaster_id query parameter must match the user ID in the user access token.
  • The Authorization header is required and must contain a user access token.
  • The user access token must include the channel:manage:schedule scope.
  • The access token is not valid.
  • The ID in the Client-Id header must match the client ID in the OAuth token.

Example Request

Removes the segment from the broadcaster’s streaming schedule.

curl -X DELETE 'https://api.twitch.tv/helix/schedule/segment?broadcaster_id=141981764&id=eyJzZWdtZW50SUQiOiI4Y2EwN2E2NC0xYTZkLTRjYWItYWE5Ni0xNjIyYzNjYWUzZDkiLCJpc29ZZWFyIjoyMDIxLCJpc29XZWVrIjoyMX0=' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Search Categories

Gets the games or categories that match the specified query.

To match, the category’s name must contain all parts of the query string. For example, if the query string is 42, the response includes any category name that contains 42 in the title. If the query string is a phrase like love computer, the response includes any category name that contains the words love and computer anywhere in the name. The comparison is case insensitive.

Authentication

Requires an app access token or user access token.

URL

GET https://api.twitch.tv/helix/search/categories

Request Query Parameters

Parameter Type Required? Description
query String Yes The URI-encoded search string. For example, encode #archery as %23archery and search strings like angel of death as angel%20of%20death.
first Integer No The maximum number of items to return per page in the response. The minimum page size is 1 item per page and the maximum is 100 items per page. The default is 20.
after String No The cursor used to get the next page of results. The Pagination object in the response contains the cursor’s value. Read More

Response Body

Field Type Description
data Object[] The list of games or categories that match the query. The list is empty if there are no matches.
   box_art_url String A URL to an image of the game’s box art or streaming category.
   name String The name of the game or category.
   id String An ID that uniquely identifies the game or category.

Response Codes

Code Description
200 OK Successfully retrieved the list of category names that matched the specified query string.
400 Bad Request
  • The query query parameter is required.
401 Unauthorized
  • The Authorization header is required and must contain an app access token or user access token.
  • The access token is not valid.
  • The client ID specified in the Client-Id header does not match the client ID specified in the access token.

Example Request

Gets the list of games and categories that contain fort in the name.

curl -X GET 'https://api.twitch.tv/helix/search/categories?query=fort' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'

Example Response

{
  "data": [
    {
      "id": "33214",
      "name": "Fortnite",
      "box_art_url": "https://static-cdn.jtvnw.net/ttv-boxart/33214-52x72.jpg"
    },
    ...
  ],
  "pagination": {
    "cursor": "eyJiIjpudWxsLCJhIjp7IkN"
  }
}

Search Channels

Gets the channels that match the specified query and have streamed content within the past 6 months.

The fields that the API uses for comparison depends on the value that the live_only query parameter is set to. If live_only is false, the API matches on the broadcaster’s login name. However, if live_only is true, the API matches on the broadcaster’s name and category name.

To match, the beginning of the broadcaster’s name or category must match the query string. The comparison is case insensitive. If the query string is angel_of_death, it matches all names that begin with angel_of_death. However, if the query string is a phrase like angel of death, it matches to names starting with angelofdeath or names starting with angel_of_death.

By default, the results include both live and offline channels. To get only live channels set the live_only query parameter to true.

Authentication

Requires an app access token or user access token.

URL

GET https://api.twitch.tv/helix/search/channels

Request Query Parameters

Parameter Type Required? Description
query String Yes The URI-encoded search string. For example, encode search strings like angel of death as angel%20of%20death.
live_only Boolean No A Boolean value that determines whether the response includes only channels that are currently streaming live. Set to true to get only channels that are streaming live; otherwise, false to get live and offline channels. The default is false.
first Integer No The maximum number of items to return per page in the response. The minimum page size is 1 item per page and the maximum is 100 items per page. The default is 20.
after String No The cursor used to get the next page of results. The Pagination object in the response contains the cursor’s value. Read More

Response Body

field Type Description
data Object[] The list of channels that match the query. The list is empty if there are no matches.
   broadcaster_language String The ISO 639-1 two-letter language code of the language used by the broadcaster. For example, en for English. If the broadcaster uses a language not in the list of supported stream languages, the value is other.
   broadcaster_login String The broadcaster’s login name.
   display_name String The broadcaster’s display name.
   game_id String The ID of the game that the broadcaster is playing or last played.
   game_name String The name of the game that the broadcaster is playing or last played.
   id String An ID that uniquely identifies the channel (this is the broadcaster’s ID).
   is_live Boolean A Boolean value that determines whether the broadcaster is streaming live. Is true if the broadcaster is streaming live; otherwise, false.
   tag_ids String[] The list of tags that apply to the stream. The list contains IDs only when the channel is steaming live. For a list of possible tags, see List of All Tags. The list doesn’t include Category Tags.
   thumbnail_url String A URL to a thumbnail of the broadcaster’s profile image.
   title String The stream’s title. Is an empty string if the broadcaster didn’t set it.
   started_at String The UTC date and time (in RFC3339 format) of when the broadcaster started streaming. The string is empty if the broadcaster is not streaming live.

Response Codes

Code Description
200 OK Successfully retrieved the list of category names that matched the specified query string.
400 Bad Request
  • The query query parameter is required.
401 Unauthorized
  • The Authorization header is required and must contain an app access token or user access token.
  • The access token is not valid.
  • The client ID specified in the Client-Id header does not match the client ID specified in the access token.

Example Request

Gets the list of live and offline channels where the broadcaster’s name contains loserfruit.

curl -X GET 'https://api.twitch.tv/helix/search/channels?query=loserfruit' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'

Example Response

{
  "data": [
    {
      "broadcaster_language": "en",
      "broadcaster_login": "loserfruit",
      "display_name": "Loserfruit",
      "game_id": "498000",
      "game_name": "House Flipper",
      "id": "41245072",
      "is_live": false,
      "tags_ids": [],
      "thumbnail_url": "https://static-cdn.jtvnw.net/jtv_user_pictures/fd17325a-7dc2-46c6-8617-e90ec259501c-profile_image-300x300.png",
      "title": "loserfruit",
      "started_at": ""
    },
    ...
  ],
  "pagination": {
    "cursor": "Mg=="
  }
}

Example Request

Gets the list of live channels where the broadcaster’s name or category name contains a_seagull.

curl -X GET 'https://api.twitch.tv/helix/search/channels?query=a_seagull&live_only=true' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'

Example Response

{
  "data": [
    {
      "broadcaster_language": "en",
      "broadcaster_login": "a_seagull",
      "display_name": "A_Seagull",
      "game_id": "506442",
      "game_name": "DOOM Eternal",
      "id": "19070311",
      "is_live": true,
      "tags_ids": [
        "6ea6bca4-4712-4ab9-a906-e3336a9d8039"
      ],
      "thumbnail_url": "https://static-cdn.jtvnw.net/jtv_user_pictures/a_seagull-profile_image-4d2d235688c7dc66-300x300.png",
      "title": "a_seagull",
      "started_at": "2020-03-18T17:56:00Z"
    }
  ],
  "pagination": {}
}

Get Soundtrack Current Track

Gets the Soundtrack track that the broadcaster is playing.

Authorization

Requires an app access token or user access token.

URL

GET https://api.twitch.tv/helix/soundtrack/current_track

Request Query Parameters

Parameter Type Required? Description
broadcaster_id String Yes The ID of the broadcaster that’s playing a Soundtrack track.

Response Body

Field Type Description
data Object[] A list that contains the single Soundtrack track that the broadcaster is playing.
   track Object Describes a track.
      album Object Describes the album that the track is found on.
        id String The album’s ASIN (Amazon Standard Identification Number).
        image_url String A URL to the album’s cover art.
        name String The album’s name. If the album contains explicit content, the name will contain [Explicit] in the string. For example, Let It Die [Explicit].
     artists Object[] The artists included on the track.
        creator_channel_id String The ID of the Twitch user that created the track. The string is empty if a Twitch user didn’t create the track.
        id String The artist’s ASIN (Amazon Standard Identification Number).
        name String The artist’s name. This can be the band’s name or the solo artist’s name.
     duration Integer The duration of the track, in seconds.
     id String The track’s ASIN (Amazon Standard Identification Number).
     isrc String The track’s ISRC (International Standard Recording Code).
     title String The track’s title. If the track contains explicit content, the title will contain [Explicit] in the string. For example, Let It Die [Explicit].
   source Object The source of the track that’s currently playing. For example, a playlist or station.
     content_type String The type of content that id maps to. Possible values are:
  • PLAYLIST
  • STATION
      id String The playlist’s or station’s ASIN (Amazon Standard Identification Number).
      image_url String A URL to the playlist’s or station’s image art.
      soundtrack_url String A URL to the playlist on Soundtrack. The string is empty if content-type is STATION.
      spotify_url String A URL to the playlist on Spotify. The string is empty if content-type is STATION.
      title String The playlist’s or station’s title.

Response Codes

Code Description
200 OK Successfully retrieved the track that the broadcaster is playing.
400 Bad Request
  • The broadcaster_id query parameter is required.
401 Unauthorized
  • The Authorization header is required and must specify an app access token or user access token.
  • The access token is not valid.
  • The ID in the Client-Id header must match the client ID in the access token.
404 Not Found
  • The broadcaster is not playing a track.

Example Request

curl -X GET 'https://api.twitch.tv/helix/soundtrack/current_track?broadcaster_id=1234' \
-H 'Authorization: Bearer 4a4x78f5wqvkybms7mxfist3jmzul' \
-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh'

Example Response

{
  "data": [
    {
      "track": {
        "artists": [
          {
            "id": "B07S7JG3TK",
            "name": "Enoth",
            "creator_channel_id": "39051113"
          }
        ],
        "id": "B08D6QFS38",
        "isrc": "CCXXXYYNNNNN",
        "duration": 153,
        "title": "Please stay",
        "album": {
          "id": "B08D6PMKYL",
          "name": "Summer 2020",
          "image_url": "https://m.media-amazon.com/images/I/51zs1JZY8tL.jpg"
        }
      },
      "source": {
        "id": "B08HCW84SF",
        "content_type": "PLAYLIST",
        "title": "Beats To Stream To",
        "image_url": "https://m.media-amazon.com/images/I/419WuvMXzEL.jpg",
        "soundtrack_url": "https://soundtrack.twitch.tv/playlist?playlistID=B08HCW84SF",
        "spotify_url": "https://open.spotify.com/playlist/1LOP14236oTUscowY3NvYN"
      }
    }
  ]
}

Get Soundtrack Playlist

Gets the Soundtrack playlist’s tracks.

Authorization

Requires an app access token or user access token.

URL

GET https://api.twitch.tv/helix/soundtrack/playlist

Request Query Parameters

Parameter Type Required? Description
id String Yes The ID of the playlist to get.
first Integer No The maximum number of items to return per page in the response. The minimum page size is 1 item per page and the maximum is 50 items per page. The default is 20.
after String No The cursor used to get the next page of results. The Pagination object in the response contains the cursor’s value. Read More

Response Body

Field Type Description
data Object[] The playlist’s list of tracks.
   album Object The album that includes this track.
      id String The album’s ASIN (Amazon Standard Identification Number).
      image_url String A URL to the album’s cover art.
      name String The album’s name. If the album contains explicit content, the name will contain [Explicit] in the string. For example, Let It Die [Explicit].
   artists Object[] The artists included on the track.
      creator_channel_id String The ID of the Twitch user that created the track. The string is empty if a Twitch user didn’t create the track.
      id String The artist’s ASIN (Amazon Standard Identification Number).
      name String The artist’s name. This can be the band’s name or the solo artist’s name.
   duration Integer The duration of the track, in seconds.
   id String The track’s ASIN (Amazon Standard Identification Number).
   isrc String The track’s ISRC (International Standard Recording Code).
   title String The track’s title. If the track contains explicit content, the title will contain [Explicit] in the string. For example, Let It Die [Explicit].
pagination Object Contains the information used to page through a list of results. The object is empty if there are no more pages to page through. Read More
   cursor String The cursor used to get the next page of results. Use the cursor to set the request’s after query parameter.

Response Codes

Code Description
200 OK Successfully retrieved the playlist.
400 Bad Request
  • The id query parameter is required.
  • The ID in the id query parameter is not a valid playlist ASIN.
401 Unauthorized
  • The Authorization header is required and must specify an app access token or user access token.
  • The access token is not valid.
  • The ID in the Client-Id header must match the client ID in the access token.
404 Not Found
  • The specified playlist was not found.

Example Request

curl -X GET 'https://api.twitch.tv/helix/soundtrack/playlist?id=B0912YMKSL' \
-H 'Authorization: Bearer 4a4x78f5wqvkybms7mxfist3jmzul' \
-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh'

Example Response

{
  "data": [
    {
      "artists": [
        {
          "id": "B002F8OLPK",
          "name": "BJ The Chicago Kid",
          "creator_channel_id": ""
        }
      ],
      "id": "B09J7FZ92D",
      "isrc": "QM24S2106597",
      "duration": 210,
      "title": "Smooth [Explicit]",
      "album": {
        "id": "B09J7B37VS",
        "name": "Smooth [Explicit]",
        "image_url": "https://m.media-amazon.com/images/I/316SDaD-XQL.jpg"
      }
    },
    {
      "artists": [
        {
          "id": "B071ZL7NDT",
          "name": "23 Unofficial",
          "creator_channel_id": "647990463"
        },
        {
          "id": "B073PHDDSK",
          "name": "KALLITECHNIS",
          "creator_channel_id": ""
        }
      ],
      "id": "B09C8344GZ",
      "isrc": "QM24S2105530",
      "duration": 154,
      "title": "OUTTA MY WAY",
      "album": {
        "id": "B09C794J2L",
        "name": "OUTTA MY WAY",
        "image_url": "https://m.media-amazon.com/images/I/515HYAEtpeL.jpg"
      }
    }
  ],
  "pagination": {
    "cursor": "eyJiIjpudWxsLCJhIjp7Ik9mZnNldCI6MjB9fQ"
  }
}

Get Soundtrack Playlists

Gets a list of Soundtrack playlists.

The response contains information about the playlists, such as their titles and descriptions. To get a playlist’s tracks, use Get Soundtrack Playlist endpoint.

Authorization

Requires an app access token or user access token.

URL

GET https://api.twitch.tv/helix/soundtrack/playlists

Request Query Parameters

Parameter Type Required? Description
id String No The ID of the playlist to get. Specify an ID only if you want to get a single playlist instead of all playlists.
first Integer No The maximum number of items to return per page in the response. The minimum page size is 1 item per page and the maximum is 50 items per page. The default is 20.
after String No The cursor used to get the next page of results. The Pagination object in the response contains the cursor’s value. Read More

Response Body

Field Type Description
data Object[] The list of Soundtrack playlists.
   description String A short description about the music that the playlist includes.
   id String The playlist’s ASIN (Amazon Standard Identification Number).
   image_url String A URL to the playlist’s image art. Is empty if the playlist doesn’t include art.
   title String The playlist’s title.
pagination Object Contains the information used to page through the list of results. The object is empty if there are no more pages left to page through. Read More
   cursor String The cursor used to get the next page of results. Use the cursor to set the request’s after query parameter.

Response Codes

Code Description
200 OK Successfully retrieved the list of playlists.
400 Bad Request
  • The ID in the id query parameter is not a valid playlist ASIN.
401 Unauthorized
  • The Authorization header is required and must specify an app access token or user access token.
  • The access token is not valid.
  • The ID in the Client-Id header must match the client ID in the access token.

Example Request

Gets all playlists.

curl -X GET 'https://api.twitch.tv/helix/soundtrack/playlists' \
-H 'Authorization: Bearer 4a4x78f5wqvkybms7mxfist3jmzul' \
-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh'

Example Response

{
  "data": [
    {
      "title": "Label Spotlight: Radio Juicy",
      "id": "B08P3N4ZPD",
      "image_url": "https://m.media-amazon.com/images/I/517kGzeaRhL.jpg",
      "description": "Journey through boom-bap, lo-fi, trap and ambient sounds, courtesy of esteemed label Radio Juicy."
    },
    {
      "title": "Fall Days",
      "id": "B09LVX24K7",
      "image_url": "https://m.media-amazon.com/images/I/41w3M-1KfXL.jpg",
      "description": "Turn a new leaf with these chill pop & indie tunes."
    },
    {
      "title": "Release Spotlight: JVNA",
      "id": "B09M7H78YL",
      "image_url": "https://m.media-amazon.com/images/I/419V2D2OlML.jpg",
      "description": "Twitch streamer, singer-songwriter and producer JVNA presents her debut album \"Hope in Chaos\"."
    },
    {
      "title": "Among Us",
      "id": "B08ZDWR371",
      "image_url": "https://m.media-amazon.com/images/I/414O3CYQguL.jpg",
      "description": "Traverse space, do tasks, and eject the Impostors in this official Among Us playlist!"
    }
  ],
  "pagination": {
    "cursor": "eyJiIjpudWxsLCJhIjp7Ik9mZnNldCI6MjB9fQ"
  }
}

Example Request

Gets a single playlist.

curl -X GET 'https://api.twitch.tv/helix/soundtrack/playlists?id=B0912YMKSL' \
-H 'Authorization: Bearer 4a4x78f5wqvkybms7mxfist3jmzul' \
-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh'

Example Response

{
  "data": [
    {
      "title": "Night Shift",
      "id": "B0912YMKSL",
      "image_url": "https://m.media-amazon.com/images/I/41UoIaB4VaL.jpg",
      "description": "R&B to ride out to."
    }
  ],
  "pagination": {}
}

Get Stream Key

Gets the channel’s stream key.

Authentication

Requires a user access token that includes the channel:read:stream_key scope.

URL

https://api.twitch.tv/helix/streams/key

Request Query Parameters

Parameter Type Required? Description
broadcaster_id String Yes The ID of the broadcaster that owns the channel. The ID must match the user ID in the access token.

Response Body

Field Type Description
data Object[] A list that contains the channel’s stream key.
   stream_key String The channel’s stream key.

Response Codes

Code Decription
200 OK Successfully retrieved the stream’s key.
400 Bad Request
  • The broadcaster_id field is required.
  • The ID in the broadcaster_id field is not valid.
401 Unauthorized
  • The ID in broadcaster_id must match the user ID in the access token.
  • The Authorization header is required and must contain a user access token.
  • The user access token must include the channel:read:stream_key scope.
  • The access token is not valid.
  • The client ID specified in the Client-Id header must match the client ID specified in the access token.

Example Request

curl -X GET 'https://api.twitch.tv/helix/streams/key' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
  "data": [
    {
      "stream_key": "live_44322889_a34ub37c8ajv98a0"
    },
  ]
}

Get Streams

Gets a list of all broadcasters that are streaming. The list is in descending order by the number of viewers watching the stream. Because viewers come and go during a stream, it’s possible to find duplicate or missing streams in the list as you page through the results.

Authentication

Requires an app access token or user access token.

URL

GET https://api.twitch.tv/helix/streams

Request Query Parameters

Parameter Type Required? Description
user_id String No A user ID used to filter the list of streams. Returns only the streams of those users that are broadcasting. You may specify a maximum of 100 IDs. To specify multiple IDs, include the user_id parameter for each user. For example, &user_id=1234&user_id=5678.
user_login String No A user login name used to filter the list of streams. Returns only the streams of those users that are broadcasting. You may specify a maximum of 100 login names. To specify multiple names, include the user_login parameter for each user. For example, &user_login=foo&user_login=bar.
game_id String No A game (category) ID used to filter the list of streams. Returns only the streams that are broadcasting the game (category). You may specify a maximum of 100 IDs. To specify multiple IDs, include the game_id parameter for each game. For example, &game_id=9876&game_id=5432.
type String No The type of stream to filter the list of streams by. Possible values are:
  • all
  • live
The default is all.
language String No A language code used to filter the list of streams. Returns only streams that broadcast in the specified language. Specify the language using an ISO 639-1 two-letter language code or other if the broadcast uses a language not in the list of supported stream languages.

You may specify a maximum of 100 language codes. To specify multiple languages, include the language parameter for each language. For example, &language=de&language=fr.
first Integer No The maximum number of items to return per page in the response. The minimum page size is 1 item per page and the maximum is 100 items per page. The default is 20.
before String No The cursor used to get the previous page of results. The Pagination object in the response contains the cursor’s value. Read More
after String No The cursor used to get the next page of results. The Pagination object in the response contains the cursor’s value. Read More

Response Body

Field Type Description
data Object[] The list of streams.
   id String An ID that identifies the stream. You can use this ID later to look up the video on demand (VOD).
   user_id String The ID of the user that’s broadcasting the stream.
   user_login String The user’s login name.
   user_name String The user’s display name.
   game_id String The ID of the category or game being played.
   game_name String The name of the category or game being played.
   type String The type of stream. Possible values are:
  • live
If an error occurs, this field is set to an empty string.
   title String The stream’s title. Is an empty string if not set.
   viewer_count Integer The number of users watching the stream.
   started_at String The UTC date and time (in RFC3339 format) of when the broadcast began.
   language String The language that the stream uses. This is an ISO 639-1 two-letter language code or other if the stream uses a language not in the list of supported stream languages.
   thumbnail_url String A URL to an image of a frame from the last 5 minutes of the stream. Replace the width and height placeholders in the URL ({width}x{height}) with the size of the image you want, in pixels.
   tag_ids String The IDs of the tags applied to the stream. To get a tag’s name, use the Get All Stream Tags endpoint. For a list of possible tags, see List of All Tags.
   is_mature Boolean A Boolean value that indicates whether the stream is meant for mature audiences.
pagination Object The information used to page through the list of results. The object is empty if there are no more pages left to page through. Read More
   cursor String The cursor used to get the next page of results. Set the request’s after or before query parameter to this value depending on whether you’re paging forwards or backwards.

Response Codes

Code Description
200 OK Successfully retrieved the list of streams.
400 Bad Request
  • The value in the type query parameter is not valid.
401 Unauthorized
  • The Authorization header is required and must specify an app access token or user access token.
  • The access token is not valid.
  • The ID in the Client-Id header must match the Client ID in the access token.

Example Request

Gets information about the 20 most active streams.

curl -X GET 'https://api.twitch.tv/helix/streams' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'

Example Response

{
  "data": [
    {
      "id": "41375541868",
      "user_id": "459331509",
      "user_login": "auronplay",
      "user_name": "auronplay",
      "game_id": "494131",
      "game_name": "Little Nightmares",
      "type": "live",
      "title": "hablamos y le damos a Little Nightmares 1",
      "viewer_count": 78365,
      "started_at": "2021-03-10T15:04:21Z",
      "language": "es",
      "thumbnail_url": "https://static-cdn.jtvnw.net/previews-ttv/live_user_auronplay-{width}x{height}.jpg",
      "tag_ids": [
        "d4bb9c58-2141-4881-bcdc-3fe0505457d1"
      ],
      "is_mature": false
    },
    ...
  ],
  "pagination": {
    "cursor": "eyJiIjp7IkN1cnNvciI6ImV5SnpJam8zT0RNMk5TNDBORFF4TlRjMU1UY3hOU3dpWkNJNlptRnNjMlVzSW5RaU9uUnlkV1Y5In0sImEiOnsiQ3Vyc29yIjoiZXlKeklqb3hOVGs0TkM0MU56RXhNekExTVRZNU1ESXNJbVFpT21aaGJITmxMQ0owSWpwMGNuVmxmUT09In19"
  }
}

Example Request

Gets streams for the specified logins. If the user is not live, the response doesn’t include them.

curl -X GET
'https://api.twitch.tv/helix/streams?user_login=afro&user_login=cohhcarnage&user_login=lana_lux' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
  "data": [
    {
      "id": "40952121085",
      "user_id": "101051819",
      "user_login": "afro",
      "user_name": "Afro",
      "game_id": "32982",
      "game_name": "Grand Theft Auto V",
      "type": "live",
      "title": "Jacob: Digital Den Laptops & Routers | NoPixel | !MAINGEAR !FCF",
      "viewer_count": 1490,
      "started_at": "2021-03-10T03:18:11Z",
      "language": "en",
      "thumbnail_url": "https://static-cdn.jtvnw.net/previews-ttv/live_user_afro-{width}x{height}.jpg",
      "tag_ids": [
        "6ea6bca4-4712-4ab9-a906-e3336a9d8039"
      ],
      "is_mature": false
    },
    ...
  ],
  "pagination": {}
}

Get Followed Streams

Gets a list of live streams of broadcasters that the specified user follows.

Authentication

Requires a user access token that includes the user:read:follows scope.

URL

GET https://api.twitch.tv/helix/streams/followed

Request Query Parameters

Parameter Type Required? Description
user_id String Yes The ID of the user whose list of followed streams you want to get. This ID must match the user ID in the access token.
first Integer No The maximum number of items to return per page in the response. The minimum page size is 1 item per page and the maximum is 100 items per page. The default is 100.
after String No The cursor used to get the next page of results. The Pagination object in the response contains the cursor’s value. Read More

Response Body

Field Type Description
data Object[] The list of live streams of broadcasters that the specified user follows. The list is in descending order by the number of viewers watching the stream. Because viewers come and go during a stream, it’s possible to find duplicate or missing streams in the list as you page through the results. The list is empty if none of the followed broadcasters are streaming live.
   id String An ID that identifies the stream. You can use this ID later to look up the video on demand (VOD).
   user_id String The ID of the user that’s broadcasting the stream.
   user_login String The user’s login name.
   user_name String The user’s display name.
   game_id String The ID of the category or game being played.
   game_name String The ID of the category or game being played.
   type String The type of stream. Possible values are:
  • live
If an error occurs, this field is set to an empty string.
   title String The stream’s title. Is an empty string if not set.
   viewer_count Integer The number of users watching the stream.
   started_at String The UTC date and time (in RFC3339 format) of when the broadcast began.
   language String The language that the stream uses. This is an ISO 639-1 two-letter language code or other if the stream uses a language not in the list of supported stream languages.
   thumbnail_url String A URL to an image of a frame from the last 5 minutes of the stream. Replace the width and height placeholders in the URL ({width}x{height}) with the size of the image you want, in pixels.
   tag_ids String The IDs of the tags applied to the stream. To get a tag’s name, use the Get All Stream Tags endpoint. For a list of possible tags, see List of All Tags.
   is_mature Boolean A Boolean value that indicates whether the stream is meant for mature audiences.
pagination Object The information used to page through the list of results. The object is empty if there are no more pages left to page through. Read More
   cursor String The cursor used to get the next page of results. Set the request’s after query parameter to this value.

Response Codes

Code Description
200 OK Successfully retrieved the list of tags.
400 Bad Request
  • The user_id query parameter is required.
401 Unauthorized
  • The ID in user_id must match the user ID found in the access token.
  • The Authorization header is required and must contain a user access token.
  • The user access token must include the user:read:follows scope.
  • The OAuth token is not valid.
  • The client ID specified in the Client-Id header does not match the client ID specified in the access token.

Example Request

Gets the streams that the broadcaster follows.

curl -X GET 'https://api.twitch.tv/helix/streams/followed?user_id=141981764' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'

Example Response

{
  "data": [
    {
      "id": "42170724654",
      "user_id": "132954738",
      "user_login": "aws",
      "user_name": "AWS",
      "game_id": "417752",
      "game_name": "Talk Shows & Podcasts",
      "type": "live",
      "title": "AWS Howdy Partner! Y'all welcome ExtraHop to the show!",
      "viewer_count": 20,
      "started_at": "2021-03-31T20:57:26Z",
      "language": "en",
      "thumbnail_url": "https://static-cdn.jtvnw.net/previews-ttv/live_user_aws-{width}x{height}.jpg",
      "tag_ids": [
        "6ea6bca4-4712-4ab9-a906-e3336a9d8039"
      ]
    },
    ...
  ],
  "pagination": {
    "cursor": "eyJiIjp7IkN1cnNvciI6ImV5SnpJam8zT0RNMk5TNDBORFF4TlRjMU1UY3hOU3dpWkNJNlptRnNjMlVzSW5RaU9uUnlkV1Y5In0sImEiOnsiQ3Vyc29yIjoiZXlKeklqb3hOVGs0TkM0MU56RXhNekExTVRZNU1ESXNJbVFpT21aaGJITmxMQ0owSWpwMGNuVmxmUT09In19"
  }
}

Create Stream Marker

Adds a marker to a live stream. A marker is an arbitrary point in a live stream that the broadcaster or editor wants to mark, so they can return to that spot later to create video highlights (see Video Producer, Highlights in the Twitch UX).

You may not add markers:

  • If the stream is not live
  • If the stream has not enabled video on demand (VOD)
  • If the stream is a premiere (a live, first-viewing event that combines uploaded videos with live chat)
  • If the stream is a rerun of a past broadcast, including past premieres.

Authentication

Requires a user access token that includes the channel:manage:broadcast scope.

URL

POST https://api.twitch.tv/helix/streams/markers

Request Body

Field Type Required? Description
user_id String Yes The ID of the broadcaster that’s streaming content. This ID must match the user ID in the access token or the user in the access token must be one of the broadcaster’s editors.
description String No A short description of the marker to help the user remember why they marked the location. The maximum length of the description is 140 characters.

Response Body

Field Type Description
data Object[] A list that contains the single marker that you added.
   id String An ID that identifies this marker.
   created_at String The UTC date and time (in RFC3339 format) of when the user created the marker.
   position_seconds Integer The relative offset (in seconds) of the marker from the beginning of the stream.
   description String A description that the user gave the marker to help them remember why they marked the location.

Response Codes

Code Description
200 OK Successfully created the marker.
400 Bad Request
  • The user_id field is required.
  • The length of the string in the description field is too long.
401 Unauthorized
  • The Authorization header is required and must contain a user access token.
  • The user access token must include the user:manage:broadcast scope.
  • The access token is not valid.
  • The client ID specified in the Client-Id header does not match the client ID specified in the access token.
403 Forbidden
  • The user in the access token is not authorized to create video markers for the user in the user_id field. The user in the access token must own the video or they must be one of the broadcaster's editors.
404 Not Found
  • The user in the user_id field is not streaming live.
  • The ID in the user_id field is not valid.
  • The user hasn't enabled video on demand (VOD).

Example Request

Creates a marker at the current location in user 123’s stream.

curl -X POST 'https://api.twitch.tv/helix/streams/markers' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Content-Type: application/json' \
-d '{"user_id":"123", "description":"hello, this is a marker!"}'

Example Response

{
  "data": [
     {
        "id": 123,
        "created_at": "2018-08-20T20:10:03Z",
        "description": "hello, this is a marker!",
        "position_seconds": 244
     }
  ]
}

Get Stream Markers

Gets a list of markers from the user’s most recent stream or from the specified VOD/video. A marker is an arbitrary point in a live stream that the broadcaster or editor marked, so they can return to that spot later to create video highlights (see Video Producer, Highlights in the Twitch UX).

Authentication

Requires a user access token that includes the user:read:broadcast scope.

URL

GET https://api.twitch.tv/helix/streams/markers

Request Query Parameter

Parameter Type Required? Description
user_id String Yes A user ID. The request returns the markers from this user’s most recent video. This ID must match the user ID in the access token or the user in the access token must be one of the broadcaster’s editors.

This parameter and the video_id query parameter are mutually exclusive.
video_id String Yes A video on demand (VOD)/video ID. The request returns the markers from this VOD/video. The user in the access token must own the video or the user must be one of the broadcaster’s editors.

This parameter and the user_id query parameter are mutually exclusive.
first String No The maximum number of items to return per page in the response. The minimum page size is 1 item per page and the maximum is 100 items per page. The default is 20.
before String No The cursor used to get the previous page of results. The Pagination object in the response contains the cursor’s value. Read More
after String No The cursor used to get the next page of results. The Pagination object in the response contains the cursor’s value. Read More

Response Body

Field Type Description
data Object[] The list of markers grouped by the user that created the marks.
   user_id String The ID of the user that created the marker.
   user_name String The user’s display name.
   user_login String The user’s login name.
   videos Object[] A list of videos that contain markers. The list contains a single video.
   video_id String An ID that identifies this video.
   markers Object[] The list of markers in this video. The list in ascending order by when the marker was created.
      id String An ID that identifies this marker.
      created_at String The UTC date and time (in RFC3339 format) of when the user created the marker.
      description String The description that the user gave the marker to help them remember why they marked the location. Is an empty string if the user didn’t provide one.
      position_seconds Integer The relative offset (in seconds) of the marker from the beginning of the stream.
      url String A URL that opens the video in Twitch Highlighter.
pagination Object The information used to page through the list of results. The object is empty if there are no more pages left to page through. Read More
   cursor String The cursor used to get the next page of results. Set the request’s after or before query parameter to this value depending on whether you’re paging forwards or backwards.

Response Codes

Code Description
200 OK Successfully retrieved the list of markers.
400 Bad Request
  • The request must specify either the user_id or video_id query parameter, but not both.
401 Unauthorized
  • The Authorization header is required and must contain a user access token.
  • The user access token must include the user:read:broadcast or user:manage:broadcast scope.
  • The access token is not valid.
  • The client ID specified in the Client-Id header does not match the client ID specified in the access token.
403 Forbidden
  • The user in the access token is not authorized to get the video's markers. The user in the access token must own the video or be one of the broadcaster's editors.
404 Not Found
  • The user specified in the user_id query parameter doesn't have videos.

Example Request

Gets the first 5 markers in the most recent stream of user 123.

curl -X GET
'https://api.twitch.tv/helix/streams/markers?user_id=123&first=5' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
  "data": [
    {
      "user_id": "123",
      "user_name": "TwitchName",
      "user_login": "twitchname",
      "videos": [
        {
          "video_id": "456",
          "markers": [
            {
              "id": "106b8d6243a4f883d25ad75e6cdffdc4",
              "created_at": "2018-08-20T20:10:03Z",
              "description": "hello, this is a marker!",
              "position_seconds": 244,
              "URL": "https://twitch.tv/twitchname/manager/highlighter/456?t=0h4m06s"
            },
            ...
          ]
        }
      ]
    }
  ],
  "pagination": {
    "cursor": "eyJiIjpudWxsLCJhIjoiMjk1MjA0Mzk3OjI1Mzpib29rbWFyazoxMDZiOGQ1Y"
  }
}

Get Broadcaster Subscriptions

Gets a list of users that subscribe to the specified broadcaster.

Authentication

Requires a user access token that includes the channel:read:subscriptions scope.

A Twitch extensions may use an app access token if the broadcaster has granted the channel:read:subscriptions scope from within the Twitch Extensions manager.

URL

GET https://api.twitch.tv/helix/subscriptions

Request Query Parameter

Parameter Type Required? Description
broadcaster_id String Yes The broadcaster’s ID. This ID must match the user ID in the access token.
user_id String No Filters the list to include only the specified subscribers. To specify more than one subscriber, include this parameter for each subscriber. For example, &user_id=1234&user_id=5678. You may specify a maximum of 100 subscribers.
first String No The maximum number of items to return per page in the response. The minimum page size is 1 item per page and the maximum is 100 items per page. The default is 20.
after String No The cursor used to get the next page of results. Do not specify if you set the user_id query parameter. The Pagination object in the response contains the cursor’s value. Read More
before String No The cursor used to get the previous page of results. Do not specify if you set the user_id query parameter. The Pagination object in the response contains the cursor’s value. Read More

Response Body

Field Type Description
data Object[] The list of users that subscribe to the broadcaster. The list is empty if the broadcaster has no subscribers.
   broadcaster_id String An ID that identifies the broadcaster.
   broadcaster_login String The broadcaster’s login name.
   broadcaster_name String The broadcaster’s display name.
   gifter_id String The ID of the user that gifted the subscription to the user. Is an empty string if is_gift is false.
   gifter_login String The gifter’s login name. Is an empty string if is_gift is false.
   gifter_name String The gifter’s display name. Is an empty string if is_gift is false.
   is_gift Boolean A Boolean value that determines whether the subscription is a gift subscription. Is true if the subscription was gifted.
   plan_name String The name of the subscription.
   tier String The type of subscription. Possible values are:
  • 1000 — Tier 1
  • 2000 — Tier 2
  • 3000 — Tier 3
   user_id String An ID that identifies the subscribing user.
   user_name String The user’s display name.
   user_login String The user’s login name.
pagination Object Contains the information used to page through the list of results. The object is empty if there are no more pages left to page through. Read More
   cursor String The cursor used to get the next or previous page of results. Use the cursor to set the request’s after or before query parameter depending on whether you’re paging forwards or backwards.
points Integer The current number of subscriber points earned by this broadcaster. Points are based on the subscription tier of each user that subscribes to this broadcaster. For example, a Tier 1 subscription is worth 1 point, Tier 2 is worth 2 points, and Tier 3 is worth 6 points. The number of points determines the number of emote slots that are unlocked for the broadcaster (see Subscriber Emote Slots).
total Integer The total number of users that subscribe to this broadcaster.

Response Codes

Code Description
200 OK Successfully retrieved the broadcaster’s list of subscribers.
400 Bad Request
  • The broadcaster_id query parameter is required.
401 Unauthorized
  • The ID in broadcaster_id must match the user ID found in the request’s OAuth token.
  • The Authorization header is required and must contain a user access token.
  • The user access token must include the channel:read:subscriptions scope.
  • The access token is not valid.
  • The client ID specified in the Client-Id header does not match the client ID specified in the access token.

Example Request

curl -X GET 'https://api.twitch.tv/helix/subscriptions?broadcaster_id=141981764' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
  "data": [
    {
      "broadcaster_id": "141981764",
      "broadcaster_login": "twitchdev",
      "broadcaster_name": "TwitchDev",
      "gifter_id": "12826",
      "gifter_login": "twitch",
      "gifter_name": "Twitch",
      "is_gift": true,
      "tier": "1000",
      "plan_name": "Channel Subscription (twitchdev)",
      "user_id": "527115020",
      "user_name": "twitchgaming",
      "user_login": "twitchgaming"
    },
    ...
  ],
  "pagination": {
    "cursor": "xxxx"
  },
  "total": 13,
  "points": 13
}

Check User Subscription

Checks whether the user subscribes to the broadcaster’s channel.

Authentication

Requires a user access token that includes the user:read:subscriptions scope.

A Twitch extensions may use an app access token if the broadcaster has granted the user:read:subscriptions scope from within the Twitch Extensions manager.

URL

GET https://api.twitch.tv/helix/subscriptions/user

Request Query Parameters

Parameter Type Required? Description
broadcaster_id String Yes The ID of a partner or affiliate broadcaster.
user_id String Yes The ID of the user that you’re checking to see whether they subscribe to the broadcaster in broadcaster_id. This ID must match the user ID in the access Token.

Response Body

Field Type Description
data Object[] A list that contains a single object with information about the user’s subscription.
   broadcaster_id String An ID that identifies the broadcaster.
   broadcaster_login String The broadcaster’s login name.
   broadcaster_name String The broadcaster’s display name.
   gifter_id String The ID of the user that gifted the subscription. The object includes this field only if is_gift is true.
   gifter_login String The gifter’s login name. The object includes this field only if is_gift is true.
   gifter_name String The gifter’s display name. The object includes this field only if is_gift is true.
   is_gift Boolean A Boolean value that determines whether the subscription is a gift subscription. Is true if the subscription was gifted.
   tier String The type of subscription. Possible values are:
  • 1000 — Tier 1
  • 2000 — Tier 2
  • 3000 — Tier 3

Response Codes

Code Description
200 OK The user subscribes to the broadcaster.
400 Bad Request
  • The broadcaster_id query parameter is required.
  • The user_id query parameter is required.
401 Unauthorized
  • The ID in user_id must match the user ID found in the request’s OAuth token.
  • The Authorization header is required and must contain a user access token.
  • The user access token must include the user:read:subscriptions scope.
  • The access token is not valid.
  • The client ID specified in the Client-Id header does not match the client ID specified in the access token.
404 Not Found
  • The user in user_id does not subscribe to the broadcaster in broadcaster_id.

Example Request

Checks whether the user subscribes to the broadcaster’s channel.

curl -X GET 'https://api.twitch.tv/helix/subscriptions/user?broadcaster_id=149747285&user_id=141981764' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'

Example Response

{
  "data": [
    {
      "broadcaster_id": "149747285",
      "broadcaster_name": "TwitchPresents",
      "broadcaster_login": "twitchpresents",
      "is_gift": false,
      "tier": "1000"
    }
  ]
}

Get All Stream Tags

Gets a list of all stream tags that Twitch defines. The broadcaster may apply any of these to their channel except automatic tags.

For an online list of the possible tags, see List of All Tags.

Authentication

Requires an app access token or user access token.

URL

GET https://api.twitch.tv/helix/tags/streams

Request Query Parameters

Parameter Type Required? Description
tag_id String No The ID of the tag to get. Used to filter the list of tags. To specify more than one tag, include the tag_id parameter for each tag to get. For example, tag_id=1234&tag_id=5678. The maximum number of IDs you may specify is 100. Ignores invalid IDs but not duplicate IDs.
first Integer No The maximum number of items to return per page in the response. The minimum page size is 1 item per page and the maximum is 100. The default is 20.
after String No The cursor used to get the next page of results. The Pagination object in the response contains the cursor’s value. Read More

Response Body

Field Type Description
data Object[] The list of stream tags that the broadcaster can apply to their channel.
   tag_id String An ID that identifies this tag.
   is_auto Boolean A Boolean value that determines whether the tag is an automatic tag. An automatic tag is one that Twitch adds to the stream. Broadcasters may not add automatic tags to their channel. The value is true if the tag is an automatic tag; otherwise, false.
   localization_names map[string,string] A dictionary that contains the localized names of the tag. The key is in the form, <locale>-<country/region>. For example, en-us. The value is the localized name.
   localization_descriptions map[string,string] A dictionary that contains the localized descriptions of the tag. The key is in the form, <locale>-<country/region>. For example, en-us. The value is the localized description.
pagination Object The information used to page through the list of results. The object is empty if there are no more pages left to page through. Read More
   cursor String The cursor used to get the next page of results. Set the request’s after query parameter to this value to page forwards through the results.

Response Codes

Code Description
200 OK Successfully retrieved the list of tags.
400 Bad Request
  • The tag_id query parameter is empty (for example, &tag_id=).
  • The list of tag IDs is too long.
401 Unauthorized
  • The Authorization header is required and must specify an app access token or user access token.
  • The access token is not valid.
  • The ID in the Client-Id header must match the Client ID in the access token.

Example Request

Gets the first page of stream tags that Twitch defines.

curl -X GET 'https://api.twitch.tv/helix/tags/streams' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
# Twitch CLI example that gets the first page of stream tags.
twitch api get /tags/streams

# Twitch CLI example that gets the specified stream tags.
twitch api get /tags/streams -q tag_id=39490173-ed5f-4271-96a8-26ab546ee1e9 -q tag_id=233f4789-1ad0-403c-aaf9-7d37a22264e7

Example Response

{
  "data": [
    {
      "tag_id": "621fb5bf-5498-4d8f-b4ac-db4d40d401bf",
      "is_auto": false,
      "localization_names": {
        "bg-bg": "Изчистване на 1 кредит",
        "cs-cz": "1 čistý kredit",
        "da-dk": "1 credit klaret",
        "de-de": "Mit 1 Leben abschließen",
        "el-gr": "1 μόνο πίστωση",
        "en-us": "1 Credit Clear",
        ...
      },
      "localization_descriptions": {
        "bg-bg": "За потоци с акцент върху завършване на аркадна игра с монети, в която не се използва продължаване",
        "cs-cz": "Pro vysílání s důrazem na plnění mincových arkádových her bez použití pokračování.",
        "da-dk": "Til streams med vægt på at gennemføre et arkadespil uden at bruge continues",
        "de-de": "Für Streams mit dem Ziel, ein Coin-op-Arcade-Game mit nur einem Leben abzuschließen.",
        "el-gr": "Για μεταδόσεις με έμφαση στην ολοκλήρωση παλαιού τύπου ηλεκτρονικών παιχνιδιών που λειτουργούν με κέρμα, χωρίς να χρησιμοποιούν συνέχειες",
        "en-us": "For streams with an emphasis on completing a coin-op arcade game without using any continues",
        ...
      }
    },
    ...
  ],
  "pagination": {
    "cursor": "eyJiI..."
  }
}

Get Stream Tags

Gets the list of stream tags that the broadcaster or Twitch added to their channel.

Authentication

Requires an app access token or user access token.

URL

GET https://api.twitch.tv/helix/streams/tags

Request Query Parameters

Parameter Type Required? Description
broadcaster_id String Yes The ID of the broadcaster whose stream tags you want to get.

Response Body

Field Type Description
data Object[] The list of stream tags. The list is empty if the broadcaster or Twitch hasn’t added tags to the broadcaster’s channel.
   tag_id String An ID that identifies this tag.
   is_auto Boolean A Boolean value that determines whether the tag is an automatic tag. An automatic tag is one that Twitch adds to the stream. Broadcasters may not add automatic tags to their channel. The value is true if the tag is an automatic tag; otherwise, false.
   localization_names map[string,string] A dictionary that contains the localized names of the tag. The key is in the form, <locale>-<coutry/region>. For example, en-us. The value is the localized name.
   localization_descriptions map[string,string] A dictionary that contains the localized descriptions of the tag. The key is in the form, <locale>-<coutry/region>. For example, en-us. The value is the localized description.

Response Codes

Code Description
200 OK Successfully retrieved the list of tags.
400 Bad Request
  • The broadcaster_id field is required.
  • The ID in the broadcaster_id field is not valid.
401 Unauthorized
  • The Authorization header is required and must specify an app access token or user access token.
  • The access token is not valid.
  • The ID in the Client-Id header must match the Client ID in the access token.

Example Request

Gets the TwitchGaming channel’s tags.

curl -X GET
'https://api.twitch.tv/helix/streams/tags?broadcaster_id=527115020' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
# Twitch CLI example that gets the TwitchGaming channel's tags.
twitch api get /streams/tags -q broadcaster_id=527115020

Example Response

{
  "data": [
    {
      "tag_id": "6ea6bca4-4712-4ab9-a906-e3336a9d8039",
      "is_auto": true,
      "localization_names": {
        "bg-bg": "английски",
        "cs-cz": "Angličtina",
        "da-dk": "Engelsk",
        "de-de": "Englisch",
        "el-gr": "Αγγλικά",
        "en-us": "English",
        ...
      },
      "localization_descriptions": {
        "bg-bg": "За потоци с използване на английски",
        "cs-cz": "Pro vysílání obsahující angličtinu.",
        "da-dk": "Til streams, hvori der indgår engelsk",
        "de-de": "Für Streams auf Englisch.",
        "el-gr": "Για μεταδόσεις που περιλαμβάνουν τη χρήση Αγγλικών",
        "en-us": "For streams featuring the use of English",
        ...
      }
    }
  ]
}

Replace Stream Tags

Applies one or more tags to the specified channel, overwriting existing tags.

NOTE: You may not specify automatic tags; the call fails if you specify automatic tags. Automatic tags are tags that Twitch applies to the channel. For a list of automatic tags, see List of All Tags. To get the list of possible tags programmatically, see Get All Stream Tags.

Authentication

Requires a user access token that includes the channel:manage:broadcast scope.

URL

PUT https://api.twitch.tv/helix/streams/tags

Request Query Parameters

Parameter Type Required? Description
broadcaster_id String Yes The ID of the broadcaster that owns the channel to apply the tags to. This ID must match the user ID in the access token.

Request Body

Field Type Required? Description
tag_ids String[] No A list of IDs that identify the tags to apply to the channel. You may specify a maximum of five tags.

To remove all tags from the channel, set tag_ids to an empty array.

Response Codes

Code Description
204 No Content Successfully replaced the stream’s tags.
400 Bad Request
  • The tag ID <value> is not valid.
  • The list of tag IDs is too long.
401 Unauthorized
  • The ID in broadcaster_id must match the user ID in the access token.
  • The Authorization header is required and must contain a user access token.
  • The user access token must include the channel:manage:broadcast scope.
  • The access token is not valid.
  • The client ID specified in the Client-Id header must match the client ID specified in the access token.
403 Forbidden
  • You may not add automatic tags.

Example Request

Applies two stream tags to channel 257788195.

curl -X PUT 'https://api.twitch.tv/helix/streams/tags?broadcaster_id=257788195' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Content-Type: application/json' \
-d '{"tag_ids":["621fb5bf-5498-4d8f-b4ac-db4d40d401bf","52d7e4cc-633d-46f5-818c-bb59102d9549"]}'
# Twitch CLI example that adds two stream tags to the channel.
twitch api put /streams/tags -q broadcaster_id=1234567 -b '{"tag_ids":["621fb5bf-5498-4d8f-b4ac-db4d40d401bf", "52d7e4cc-633d-46f5-818c-bb59102d9549"]}'

# Twitch CLI example that removes all stream tags from the channel.
twitch api put /streams/tags -q broadcaster_id=1234567 -b '{"tag_ids":[]}'

Get Channel Teams

Gets the list of Twitch teams that the broadcaster is a member of.

Authentication

Requires an app access token or user access token.

URL

GET https://api.twitch.tv/helix/teams/channel

Request Query Parameters

Parameter Type Required? Description
broadcaster_id String Yes The ID of the broadcaster whose teams you want to get.

Response Body

Field Type Description
data Object[] The list of teams that the broadcaster is a member of.
   broadcaster_id String An ID that identifies the broadcaster.
   broadcaster_login String The broadcaster’s login name.
   broadcaster_name String The broadcaster’s display name.
   background_image_url String A URL to the team’s background image.
   banner String A URL to the team’s banner.
   created_at String The UTC date and time (in RFC3339 format) of when the team was created.
   updated_at String The UTC date and time (in RFC3339 format) of the last time the team was updated.
   info String The team’s description. The description may contain formatting such as Markdown, HTML, newline (\n) characters, etc.
   thumbnail_url String A URL to a thumbnail image of the team’s logo.
   team_name String The team’s name.
   team_display_name String The team’s display name.
   id String An ID that identifies the team.

Response Codes

Code Description
200 OK Successfully retrieved the list of teams.
400 Bad Request
  • The broadcaster_id query parameter is required.
401 Unauthorized
  • The Authorization header must contain an app access token or user access token.
  • The access token is not valid.
  • The ID specified in the Client-Id header does not match the client ID specified in the access token.
404 Not Found
  • The broadcaster was not found.
  • The broadcaster is not a member of a team.

Example Request

Gets a list of Twitch Teams that the specified broadcaster is a member of.

curl -X GET 'https://api.twitch.tv/helix/teams/channel?broadcaster_id=96909659' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'

Example Response

{
  "data": [
    {
      "broadcaster_id": "96909659",
      "broadcaster_name": "CSharpFritz",
      "broadcaster_login": "csharpfritz",
      "background_image_url": null,
      "banner": null,
      "created_at": "2019-02-11T12:09:22Z",
      "updated_at": "2020-11-18T15:56:41Z",
      "info": "<p>An outgoing and enthusiastic group of friendly channels that write code, teach about technology, and promote the technical community.</p>",
      "thumbnail_url": "https://static-cdn.jtvnw.net/jtv_user_pictures/team-livecoders-team_logo_image-bf1d9a87ca81432687de60e24ad9593d-600x600.png",
      "team_name": "livecoders",
      "team_display_name": "Live Coders",
      "id": "6358"
    }
  ]
}

Get Teams

Gets information about the specified Twitch team. Read More

Authentication

Requires an app access token or user access token.

URL

GET https://api.twitch.tv/helix/teams

Request Query Parameters

Parameter Type Required? Description
name String Yes The name of the team to get. This parameter and the id parameter are mutually exclusive; you must specify the team’s name or ID but not both.
id String Yes The ID of the team to get. This parameter and the name parameter are mutually exclusive; you must specify the team’s name or ID but not both.

Response Body

Field Type Description
data Object[] A list that contains the single team that you requested.
   users Object[] The list of team members.
      user_id String An ID that identifies the team member.
      user_login String The team member’s login name.
      user_name String The team member’s display name.
   background_image_url String A URL to the team’s background image.
   banner String A URL to the team’s banner.
   created_at String The UTC date and time (in RFC3339 format) of when the team was created.
   updated_at String The UTC date and time (in RFC3339 format) of the last time the team was updated.
   info String The team’s description. The description may contain formatting such as Markdown, HTML, newline (\n) characters, etc.
   thumbnail_url String A URL to a thumbnail image of the team’s logo.
   team_name String The team’s name.
   team_display_name String The team’s display name.
   id String An ID that identifies the team.

Response Codes

Code Description
200 OK Successfully retrieved the team’s information.
400 Bad Request
  • The name or id query parameter is required.
  • Specify either the name or id query parameter but not both.
  • The ID in the id query parameter is not valid.
401 Unauthorized
  • The Authorization header must contain an app access token or user access token.
  • The access token is not valid.
  • The ID specified in the Client-Id header does not match the client ID specified in the access token.
404 Not Found
  • The specified team was not found.

Example Request

Gets information about the specified team.

curl -X GET 'https://api.twitch.tv/helix/teams?id=6358' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'

Example Response

{
  "data": [
    {
      "users": [
        {
          "user_id": "278217731",
          "user_name": "mastermndio",
          "user_login": "mastermndio"
        },
        {
          "user_id": "41284990",
          "user_name": "jenninexus",
          "user_login": "jenninexus"
        },
        ...
      ],
      "background_image_url": null,
      "banner": null,
      "created_at": "2019-02-11T12:09:22Z",
      "updated_at": "2020-11-18T15:56:41Z",
      "info": "<p>An outgoing and enthusiastic group of friendly channels that write code, teach about technology, and promote the technical community.</p>",
      "thumbnail_url": "https://static-cdn.jtvnw.net/jtv_user_pictures/team-livecoders-team_logo_image-bf1d9a87ca81432687de60e24ad9593d-600x600.png",
      "team_name": "livecoders",
      "team_display_name": "Live Coders",
      "id": "6358"
    }
  ]
}

Get Users

Gets information about one or more users.

You may look up users using their user ID, login name, or both but the sum total of the number of users you may look up is 100. For example, you may specify 50 IDs and 50 names or 100 IDs or names, but you cannot specify 100 IDs and 100 names.

If you don’t specify IDs or login names, the request returns information about the user in the access token if you specify a user access token.

To include the user’s verified email address in the response, you must use a user access token that includes the user:read:email scope.

Authentication

Requires an app access token or user access token.

URL

GET https://api.twitch.tv/helix/users

Request Query Parameters

Parameter Type Required? Description
id String No The ID of the user to get. To specify more than one user, include the id parameter for each user to get. For example, id=1234&id=5678. The maximum number of IDs you may specify is 100.
login String No The login name of the user to get. To specify more than one user, include the login parameter for each user to get. For example, login=foo&login=bar. The maximum number of login names you may specify is 100.

Response Body

Field Type Description
data Object[] The list of users.
   id String An ID that identifies the user.
   login String The user’s login name.
   display_name String The user’s display name.
   type String The type of user. Possible values are:
  • admin — Twitch administrator
  • global_mod
  • staff — Twitch staff
  • "" — Normal user
   broadcaster_type String The type of broadcaster. Possible values are:
   description String The user’s description of their channel.
   profile_image_url String A URL to the user’s profile image.
   offline_image_url String A URL to the user’s offline image.
   view_count Integer The number of times the user’s channel has been viewed.

NOTE: This field has been deprecated (see Get Users API endpoint – “view_count” deprecation). Any data in this field is not valid and should not be used.
   email String The user’s verified email address. The object includes this field only if the user access token includes the user:read:email scope.

If the request contains more than one user, only the user associated with the access token that provided consent will include an email address — the email address for all other users will be empty.
   created_at String The UTC date and time that the user’s account was created. The timestamp is in RFC3339 format.

Response Codes

Code Description
200 OK Successfully retrieved the specified users’ information.
400 Bad Request
  • The id or login query parameter is required unless the request uses a user access token.
  • The request exceeded the maximum allowed number of id and/or login query parameters.
401 Unauthorized
  • The Authorization header is required and must contain an app access token or user access token.
  • The access token is not valid.
  • The ID specified in the Client-Id header does not match the client ID specified in the access token.

Example Request

Gets information about the specified user.

curl -X GET 'https://api.twitch.tv/helix/users?id=141981764' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
  "data": [
    {
      "id": "141981764",
      "login": "twitchdev",
      "display_name": "TwitchDev",
      "type": "",
      "broadcaster_type": "partner",
      "description": "Supporting third-party developers building Twitch integrations from chatbots to game integrations.",
      "profile_image_url": "https://static-cdn.jtvnw.net/jtv_user_pictures/8a6381c7-d0c0-4576-b179-38bd5ce1d6af-profile_image-300x300.png",
      "offline_image_url": "https://static-cdn.jtvnw.net/jtv_user_pictures/3f13ab61-ec78-4fe6-8481-8682cb3b0ac2-channel_offline_image-1920x1080.png",
      "view_count": 5980557,
      "email": "not-real@email.com",
      "created_at": "2016-12-14T20:32:28Z"
    }
  ]
}

Update User

Updates the specified user’s information. The user ID in the OAuth token identifies the user whose information you want to update.

To include the user’s verified email address in the response, the user access token must also include the user:read:email scope.

Authentication

Requires a user access token that includes the user:edit scope.

URL

PUT https://api.twitch.tv/helix/users

Request Query Parameters

Parameter Type Required? Description
description string No The string to update the channel’s description to. The description is limited to a maximum of 300 characters.

To remove the description, specify this parameter but don’t set it’s value (for example, ?description=).

Response Body

Field Type Description
data Object[] A list contains the single user that you updated.
   id String An ID that identifies the user.
   login String The user’s login name.
   display_name String The user’s display name.
   type String The type of user. Possible values are:
  • admin — Twitch administrator
  • global_mod
  • staff — Twitch staff
  • "" — Normal user
   broadcaster_type String The type of broadcaster. Possible values are:
   description String The user’s description of their channel.
   profile_image_url String A URL to the user’s profile image.
   offline_image_url String A URL to the user’s offline image.
   view_count Integer The number of times the user’s channel has been viewed.

NOTE: This field has been deprecated (see Get Users API endpoint – “view_count” deprecation). Any data in this field is not valid and should not be used.
   email String The user’s verified email address. The object includes this field only if the user access token includes the user:read:email scope.

If the request contains more than one user, only the user associated with the access token that provided consent will include an email address — the email address for all other users will be empty.
   created_at String The UTC date and time that the user’s account was created. The timestamp is in RFC3339 format.

Response Codes

Code Description
200 OK Successfully updated the specified user’s information.
400 Bad Request
  • The string in the description query parameter is too long.
401 Unauthorized
  • The Authorization header is required and must contain a user access token.
  • The user access token must include the user:edit scope.
  • The access token is not valid.
  • The ID specified in the Client-Id header does not match the client ID specified in the access token.

Example Request

Updates the description of the specified user.

curl  -X PUT 'https://api.twitch.tv/helix/users?description=BaldAngel' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
  "data":[{
    "id": "44322889",
    "login": "dallas",
    "display_name": "dallas",
    "type": "staff",
    "broadcaster_type": "affiliate",
    "description": "BaldAngel",
    "profile_image_url": "https://static-cdn.jtvnw.net/jtv_user_pictures/4d1f36cbf1f0072d-profile_image-300x300.png",
    "offline_image_url": "https://static-cdn.jtvnw.net/jtv_user_pictures/dallas-channel_offline_image-2e82c1df2a464df7-1920x1080.jpeg",
    "view_count": 6995,
    "email": "not-real@email.com",
    "created_at": "2013-06-03T19:12:02.580593Z"
  }]
}

Get Users Follows

Gets information about users that are following other users. For example, you can use this endpoint to answer questions like “who is qotrok following,” “who is following qotrok,” or “is user X following user Y.”

Authentication

Requires an app access token or user access token.

URL

GET https://api.twitch.tv/helix/users/follows

Request Query Parameters

Parameter Type Required? Description
from_id String No A user ID. Specify this parameter to discover the users that this user is following.

You must specify this parameter, the to_id parameter, or both.
to_id String No A user ID. Specify this parameter to discover the users who are following this user.

You must specify this parameter, the from_id parameter, or both.
first Integer No The maximum number of items to return per page in the response. The minimum page size is 1 item per page and the maximum is 100. The default is 20.
after String No The cursor used to get the next page of results. The Pagination object in the response contains the cursor’s value. Read More

Response Body

Field Type Description
total Integer The number of items in the data field.
  • If the request includes only from_id, this is the total number of followed users.
  • If the request includes only to_id, this is the total number of followers.
  • If the request specifies both from_id and to_id, the total is 1 if the "from" user follows the "to" user; otherwise, the total is 0.
data Object[] The list of follower-followee relationship information. The list is in descending order by when the follow occurred (most recent follow first).
   from_id String The ID of the user that’s following the user in to_id.
   from_login String The follower’s login name.
   from_name String The follower’s display name.
   to_id String The ID of the user that’s being followed by the user in from_id.
   to_login String The login name of the user that’s being followed.
   to_name String The display name of the user that’s being followed.
   followed_at String The UTC date and time (in RFC3339 format) of when the user in from_id began following the user in to_id.
pagination Object Contains the information used to page through the list of results. The object is empty if there are no more pages left to page through. Read More
   cursor String The cursor used to get the next page of results. Use the cursor to set the request’s after query parameter.

Response Codes

Code Description
200 OK Successfully retrieved the follows information.
400 Bad Request
  • The from_id query parameter, to_id query parameter, or both parameters are required.
  • The ID in the from_id query parameter is not valid
  • The ID in the to_id query parameter is not valid.
401 Unauthorized
  • The Authorization header is required and must contain an app access token or user access token.
  • The access token is not valid.
  • The ID specified in the Client-Id header does not match the client ID specified in the access token.

Example Request

Gets the first 20 IDs of users who are following the specified user.

curl -X GET 'https://api.twitch.tv/helix/users/follows?to_id=23161357' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
   "total": 12345,
   "data":
   [
      {
         "from_id": "171003792",
         "from_login": "iiisutha067iii",
         "from_name": "IIIsutha067III",
         "to_id": "23161357",
         "to_name": "LIRIK",
         "followed_at": "2017-08-22T22:55:24Z"
      },
      {
         "from_id": "113627897",
         "from_login": "birdman616",
         "from_name": "Birdman616",
         "to_id": "23161357",
         "to_name": "LIRIK",
         "followed_at": "2017-08-22T22:55:04Z"
      },
      ...
   ],
   "pagination":{
     "cursor": "eyJiIjpudWxsLCJhIjoiMTUwMzQ0MTc3NjQyNDQyMjAwMCJ9"
   }
}

Get User Block List

Gets the list of users that the broadcaster has blocked. Read More

Authentication

Requires a user access token that includes the user:read:blocked_users scope.

URL

GET https://api.twitch.tv/helix/users/blocks

Request Query Parameters

Parameter Type Required? Description
broadcaster_id String Yes The ID of the broadcaster whose list of blocked users you want to get.
first Integer No The maximum number of items to return per page in the response. The minimum page size is 1 item per page and the maximum is 100. The default is 20.
after String No The cursor used to get the next page of results. The Pagination object in the response contains the cursor’s value. Read More

Response Body

Field Type Description
data Object[] The list of blocked users. The list is in descending order by when the user was blocked.
   user_id String An ID that identifies the blocked user.
   user_login String The blocked user’s login name.
   display_name String The blocked user’s display name.

Response Codes

Code Description
200 OK Successfully retrieved the broadcaster’s list of blocked users.
400 Bad Request
  • The broadcaster_id query parameter is required.
401 Unauthorized
  • The ID in broadcaster_id must match the user ID found in the request’s access token.
  • The Authorization header is required and must contain a user access token.
  • The user access token must include the user:read:blocked_users scope.
  • The access token is not valid.
  • The ID specified in the Client-Id header does not match the client ID specified in the access token.

Example Request

Gets the specified broadcaster’s list of blocked users.

curl -X GET 'https://api.twitch.tv/helix/users/blocks?broadcaster_id=141981764' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz' \

Example Response

{
  "data": [
    {
      "user_id": "135093069",
      "user_login": "bluelava",
      "display_name": "BlueLava"
    },
    {
      "user_id": "27419011",
      "user_login": "travistyoj",
      "display_name": "TravistyOJ"
    }
  ]
}

Block User

Blocks the specified user from interacting with or having contact with the broadcaster. The user ID in the OAuth token identifies the broadcaster who is blocking the user.

To learn more about blocking users, see Block Other Users on Twitch.

Authentication

Requires a user access token that includes the user:manage:blocked_users scope.

URL

PUT https://api.twitch.tv/helix/users/blocks

Request Query Parameters

Parameter Type Required? Description
target_user_id String Yes The ID of the user to block. The API ignores the request if the broadcaster has already blocked the user.
source_context String No The location where the harassment took place that is causing the brodcaster to block the user. Possible values are:
  • chat
  • whisper
.
reason String No The reason that the broadcaster is blocking the user. Possible values are:
  • harassment
  • spam
  • other

Response Codes

Code Description
204 No Content Successfully blocked the user.
400 Bad Request
  • The target_user_id query parameter is required.
  • The ID in target_user_id cannot be the same as the user ID in the access token.
  • The value in source_context is not valid.
  • The value in reason is not valid.
401 Unauthorized
  • The Authorization header is required and must contain a user access token.
  • The user access token must include the user:manage:blocked_users scope.
  • The access token is not valid.
  • The ID specified in the Client-Id header does not match the client ID specified in the access token.

Example Request

Blocks the specified user.

curl -X PUT 'https://api.twitch.tv/helix/users/blocks?target_user_id=198704263' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz' \

Unblock User

Removes the user from the broadcaster’s list of blocked users. The user ID in the OAuth token identifies the broadcaster who’s removing the block.

Authentication

Requires a user access token that includes the user:manage:blocked_users scope.

URL

DELETE https://api.twitch.tv/helix/users/blocks

Request Query Parameters

Parameter Type Required? Description
target_user_id String Yes The ID of the user to remove from the broadcaster’s list of blocked users. The API ignores the request if the broadcaster hasn’t blocked the user.

Response Codes

Code Description