{ "openapi": "3.0.0", "info": { "title": "Twitch API Swagger UI (Unofficial)", "description": "Unofficial Swagger UI for Twitch API.\n\nAll endpoints are generated automatically from the [twitch docs](https://dev.twitch.tv/docs/api/reference) page.\n\n__Features:__\n\n* Swagger UI for all Twitch API endpoints\n* Schemas for _Request Query Parameters_, _Request Body_, _Response Body_\n* Some additional schemas like _Clip_, _ChatBadge_, _Prediction_, _Game_, _Channel_, _Video_ etc.\n* Response codes and examples\n* Generated types for TypeScript: [ts-twitch-api](https://github.com/DmitryScaletta/ts-twitch-api)\n\n__Repository:__ [github.com/DmitryScaletta/twitch-api-swagger](https://github.com/DmitryScaletta/twitch-api-swagger)", "version": "helix" }, "servers": [ { "url": "https://api.twitch.tv/helix", "description": "Helix" } ], "security": [], "tags": [ { "name": "Ads" }, { "name": "Analytics" }, { "name": "Bits" }, { "name": "Channels" }, { "name": "Channel Points" }, { "name": "Charity" }, { "name": "Chat" }, { "name": "Clips" }, { "name": "Conduits" }, { "name": "CCLs" }, { "name": "Entitlements" }, { "name": "Extensions" }, { "name": "EventSub" }, { "name": "Games" }, { "name": "Goals" }, { "name": "Guest Star" }, { "name": "Hype Train" }, { "name": "Moderation" }, { "name": "Polls" }, { "name": "Predictions" }, { "name": "Raids" }, { "name": "Schedule" }, { "name": "Search" }, { "name": "Streams" }, { "name": "Subscriptions" }, { "name": "Tags" }, { "name": "Teams" }, { "name": "Users" }, { "name": "Videos" }, { "name": "Whispers" } ], "paths": { "/channels/commercial": { "post": { "summary": "Starts a commercial on the specified channel.", "description": "Starts a commercial on the specified channel.\n\n**NOTE**: Only partners and affiliates may run commercials and they must be streaming live at the time.\n\n**NOTE**: Only the broadcaster may start a commercial; the broadcaster’s editors and moderators may not start commercials on behalf of the broadcaster.\n\n__Authorization:__\n\nRequires one of the following:\n\n* A [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **channel:edit:commercial** scope.\n* BETA An [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens) where the application, through a prior authorization, has the **channel:edit:commercial** scope for the user represented by the `broadcaster_id` query parameter.", "tags": [ "Ads" ], "externalDocs": { "description": "Start Commercial", "url": "https://dev.twitch.tv/docs/api/reference#start-commercial" }, "operationId": "start-commercial", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartCommercialBody" }, "examples": { "Example": { "value": { "broadcaster_id": "141981764", "length": 60 }, "description": "This request starts a commercial." } } } } }, "responses": { "200": { "description": "Successfully started the commercial.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartCommercialResponse" }, "examples": { "Example": { "description": "_Request:_\n\nThis request starts a commercial.\n\n```bash\ncurl -X POST 'https://api.twitch.tv/helix/channels/commercial' \\\n-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \\\n-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n \"broadcaster_id\": \"141981764\",\n \"length\": 60\n}'\n```", "value": { "data": [ { "length": 60, "message": "", "retry_after": 480 } ] } } } } } }, "400": { "description": "* The _broadcaster\\_id_ query parameter is required.\n* The _length_ query parameter is required.\n* The ID in _broadcaster\\_id_ is not valid.\n* To start a commercial, the broadcaster must be streaming live.\n* 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": { "description": "* The ID in `broadcaster_id` must match the user ID found in the request’s OAuth token.\n* The Authorization header is required and must contain a user access token.\n* The user access token must include the **channel:edit:commercial** scope.\n* The OAuth token is not valid.\n* The client ID specified in the Client-Id header does not match the client ID specified in the OAuth token." }, "404": { "description": "* The ID in `broadcaster_id` was not found." }, "429": { "description": "* 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." } }, "security": [ { "twitch_auth": [ "channel:edit:commercial" ] } ] } }, "/channels/ads": { "get": { "summary": "Returns ad schedule related information.", "description": "This endpoint returns ad schedule related information, including snooze, when the last ad was run, when the next ad is scheduled, and if the channel is currently in pre-roll free time. Note that a new ad cannot be run until 8 minutes after running a previous ad.\n\n__Authorization:__\n\nRequires one of the following:\n\n* A [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **channel:read:ads** scope. The user ID associated with the token must match the `broadcaster_id` in the query parameter.\n* BETA An [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens) where the application, through a prior authorization, has the **channel:read:ads** scope for the user represented by the `broadcaster_id` query parameter.", "tags": [ "Ads" ], "externalDocs": { "description": "Get Ad Schedule", "url": "https://dev.twitch.tv/docs/api/reference#get-ad-schedule" }, "operationId": "get-ad-schedule", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "Provided `broadcaster_id` must match the `user_id` in the auth token.", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Returns the ad schedule information for the channel.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAdScheduleResponse" }, "examples": { "Example": { "description": "_Request:_\n\nRetrieves the ad schedule for the TwitchDev channel.\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/channels/ads?broadcaster_id=141981764' \\\n-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \\\n-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'\n```", "value": { "data": [ { "next_ad_at": "2023-08-01T23:08:18+00:00", "last_ad_at": "2023-08-01T23:08:18+00:00", "duration": "60", "preroll_free_time": "90", "snooze_count": "1", "snooze_refresh_at": "2023-08-01T23:08:18+00:00" } ] } } } } } }, "400": { "description": "The broadcaster ID is not valid." }, "500": { "description": "" } }, "security": [ { "twitch_auth": [ "channel:read:ads" ] } ] } }, "/channels/ads/schedule/snooze": { "post": { "summary": "Pushes back the timestamp of the upcoming automatic mid-roll ad by 5 minutes.", "description": "If available, pushes back the timestamp of the upcoming automatic mid-roll ad by 5 minutes. This endpoint duplicates the snooze functionality in the creator dashboard’s Ads Manager.\n\n__Authorization:__\n\nRequires one of the following:\n\n* A [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **channel:manage:ads** scope. The user ID associated with the token must match the `broadcaster_id` in the query parameter.\n* BETA An [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens) where the application, through a prior authorization, has the **channel:manage:ads** scope for the user represented by the `broadcaster_id` query parameter.", "tags": [ "Ads" ], "externalDocs": { "description": "Snooze Next Ad", "url": "https://dev.twitch.tv/docs/api/reference#snooze-next-ad" }, "operationId": "snooze-next-ad", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "Provided `broadcaster_id` must match the `user_id` in the auth token.", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "User’s next ad is successfully snoozed. Their _snooze\\_count_ is decremented and _snooze\\_refresh\\_time_ and _next\\_ad\\_at_ are both updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SnoozeNextAdResponse" }, "examples": { "Example": { "description": "_Request:_\n\nSnooze the next ad.\n\n```bash\ncurl -X POST 'https://api.twitch.tv/helix/channels/ads/schedule/snooze?broadcaster_id=123' \\\n-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \\\n-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'\n```", "value": { "data": [ { "snooze_count": "1", "snooze_refresh_at": "2023-08-01T23:08:18+00:00", "next_ad_at": "2023-08-01T23:08:18+00:00" } ] } } } } } }, "400": { "description": "* The channel is not currently live.\n* The broadcaster ID is not valid.\n* Channel does not have an upcoming scheduled ad break." }, "429": { "description": "Channel has no snoozes left." }, "500": { "description": "" } }, "security": [ { "twitch_auth": [ "channel:manage:ads" ] } ] } }, "/analytics/extensions": { "get": { "summary": "Gets an analytics report for one or more extensions.", "description": "Gets an analytics report for one or more extensions. The response contains the URLs used to download the reports (CSV files). [Learn More](https://dev.twitch.tv/docs/insights)\n\n__Authorization:__\n\nRequires a [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **analytics:read:extensions** scope.", "tags": [ "Analytics" ], "externalDocs": { "description": "Get Extension Analytics", "url": "https://dev.twitch.tv/docs/api/reference#get-extension-analytics" }, "operationId": "get-extension-analytics", "parameters": [ { "name": "extension_id", "in": "query", "description": "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.", "schema": { "type": "string" } }, { "name": "type", "in": "query", "description": "The type of analytics report to get. Possible values are: \n \n* overview\\_v2", "schema": { "type": "string", "enum": [ "overview_v2" ] } }, { "name": "started_at", "in": "query", "description": "The reporting window's start date, in RFC3339 format. Set the time portion to zeroes (for example, 2021-10-22T00:00:00Z). \n \nThe 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. \n \nThe report contains one row of data for each day in the reporting window.", "schema": { "type": "string", "format": "date-time" } }, { "name": "ended_at", "in": "query", "description": "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. \n \nSpecify 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.", "schema": { "type": "string", "format": "date-time" } }, { "name": "first", "in": "query", "description": "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. \n \n**NOTE**: While you may specify a maximum value of 100, the response will contain at most 20 URLs per page.", "schema": { "type": "integer", "format": "int32" } }, { "name": "after", "in": "query", "description": "The cursor used to get the next page of results. The **Pagination** object in the response contains the cursor’s value. [Read More](https://dev.twitch.tv/docs/api/guide#pagination) \n \nThis parameter is ignored if the _extension\\_id_ parameter is set.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the broadcaster's analytics reports.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetExtensionAnalyticsResponse" }, "examples": { "Example": { "description": "_Request:_\n\nGets the URLs for all reports for all extensions of the authenticated client. The request was issued on June 1, 2018.\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/analytics/extensions' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```", "value": { "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" } } } } } } }, "400": { "description": "* The start and end dates are optional but if you specify one, you must specify the other.\n* The end date must be equal to or later than the start date.\n* The cursor specified in the _after_ query parameter is not valid.\n* The resource supports only forward pagination (use the _after_ query parameter).\n* The _first_ query parameter is outside the allowed range of values." }, "401": { "description": "* The Authorization header is required and must contain a user access token.\n* The user access token must include the **analytics:read:extensions** scope.\n* The OAuth token is not valid.\n* The Client-Id header is required.\n* The client ID specified in the Client-Id header does not match the client ID specified in the OAuth token." }, "404": { "description": "* The extension specified in the _extension\\_id_ query parameter was not found." } }, "security": [ { "twitch_auth": [ "analytics:read:extensions" ] } ] } }, "/analytics/games": { "get": { "summary": "Gets an analytics report for one or more games.", "description": "Gets an analytics report for one or more games. The response contains the URLs used to download the reports (CSV files). [Learn more](https://dev.twitch.tv/docs/insights)\n\n__Authorization:__\n\nRequires a [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **analytics:read:games** scope.", "tags": [ "Analytics" ], "externalDocs": { "description": "Get Game Analytics", "url": "https://dev.twitch.tv/docs/api/reference#get-game-analytics" }, "operationId": "get-game-analytics", "parameters": [ { "name": "game_id", "in": "query", "description": "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.", "schema": { "type": "string" } }, { "name": "type", "in": "query", "description": "The type of analytics report to get. Possible values are: \n \n* overview\\_v2", "schema": { "type": "string", "enum": [ "overview_v2" ] } }, { "name": "started_at", "in": "query", "description": "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. \n \nThe 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. \n \nThe report contains one row of data for each day in the reporting window.", "schema": { "type": "string", "format": "date-time" } }, { "name": "ended_at", "in": "query", "description": "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. \n \nSpecify 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.", "schema": { "type": "string", "format": "date-time" } }, { "name": "first", "in": "query", "description": "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. \n \n**NOTE**: While you may specify a maximum value of 100, the response will contain at most 20 URLs per page.", "schema": { "type": "integer", "format": "int32" } }, { "name": "after", "in": "query", "description": "The cursor used to get the next page of results. The **Pagination** object in the response contains the cursor’s value. [Read More](https://dev.twitch.tv/docs/api/guide#pagination) \n \nThis parameter is ignored if _game\\_id_ parameter is set.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the broadcaster’s analytics reports.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetGameAnalyticsResponse" }, "examples": { "Example 1": { "description": "_Request:_\n\nGets the URL for a downloadable CSV report for game ID 493057, covering the period January 1, 2018 through March 1, 2018.\n\n```bash\ncurl -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' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```", "value": { "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 2": { "description": "_Request:_\n\nGets the first 5 URLs for all reports for all games of the authenticated client. The request was issued on June 14, 2018.\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/analytics/games?first=5' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```", "value": { "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" } } } } } } }, "400": { "description": "* The start and end dates are optional but if you specify one, you must specify the other.\n* The end date must be equal to or later than the start date.\n* The cursor specified in the _after_ query parameter is not valid.\n* The resource supports only forward pagination (use the _after_ query parameter).\n* The _first_ query parameter is outside the allowed range of values." }, "401": { "description": "* The Authorization header is required and must contain a user access token.\n* The user access token must include the **analytics:read:games** scope.\n* The OAuth token is not valid.\n* The Client-Id header is required.\n* The client ID specified in the Client-Id header does not match the client ID specified in the OAuth token." }, "404": { "description": "* The game specified in the _game\\_id_ query parameter was not found." } }, "security": [ { "twitch_auth": [ "analytics:read:games" ] } ] } }, "/bits/leaderboard": { "get": { "summary": "Gets the Bits leaderboard for the authenticated broadcaster.", "description": "Gets the Bits leaderboard for the authenticated broadcaster.\n\n__Authorization:__\n\nRequires a [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **bits:read** scope.", "tags": [ "Bits" ], "externalDocs": { "description": "Get Bits Leaderboard", "url": "https://dev.twitch.tv/docs/api/reference#get-bits-leaderboard" }, "operationId": "get-bits-leaderboard", "parameters": [ { "name": "count", "in": "query", "description": "The number of results to return. The minimum count is 1 and the maximum is 100\\. The default is 10.", "schema": { "type": "integer", "format": "int32" } }, { "name": "period", "in": "query", "description": "The time period over which data is aggregated (uses the PST time zone). Possible values are: \n \n* 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.\n* 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.\n* 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.\n* 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.\n* all — Default. The lifetime of the broadcaster's channel.", "schema": { "type": "string", "enum": [ "day", "week", "month", "year", "all" ] } }, { "name": "started_at", "in": "query", "description": "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. \n \nNote 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`. \n \nIf your start date uses the ‘+’ offset operator (for example, `2022-01-01T00:00:00.0+05:00`), you must URL encode the start date.", "schema": { "type": "string", "format": "date-time" } }, { "name": "user_id", "in": "query", "description": "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.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the broadcaster’s Bits leaderboard.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetBitsLeaderboardResponse" }, "examples": { "Example": { "description": "_Request:_\n\nGets information about the authenticated broadcaster’s top two Bits leaderboard entries for the specified week.\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/bits/leaderboard?count=2&period=week&started_at=2018-02-05T08%3A00%3A00Z' \\\n-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```", "value": { "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 } } } } } }, "400": { "description": "* The time period specified in the _period_ query parameter is not valid.\n* The _started\\_at_ query parameter is required if _period_ is not set to _all_.\n* The value in the _count_ query parameter is outside the range of allowed values." }, "401": { "description": "* The Authorization header is required and must specify a user access token.\n* The user access token must include the the **bits:read** scope.\n* The access token is not valid.\n* The ID in the Client-Id header must match the client ID in the access token." }, "403": { "description": "" } }, "security": [ { "twitch_auth": [ "bits:read" ] } ] } }, "/bits/cheermotes": { "get": { "summary": "Gets a list of Cheermotes that users can use to cheer Bits.", "description": "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.\n\n__Authorization:__\n\nRequires an [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens) or [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens).", "tags": [ "Bits" ], "externalDocs": { "description": "Get Cheermotes", "url": "https://dev.twitch.tv/docs/api/reference#get-cheermotes" }, "operationId": "get-cheermotes", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "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. \n \nIf the broadcaster uploaded Cheermotes, the `type` field in the response is set to **channel\\_custom**.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the Cheermotes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetCheermotesResponse" }, "examples": { "Example": { "description": "_Request:_\n\nGets a list of all global Cheermotes.\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/bits/cheermotes' \\\n-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \\\n-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'\n```\n\nGets a list of all global Cheermotes and any Cheermotes that the broadcaster has uploaded.\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/bits/cheermotes?broadcaster_id=41245072' \\\n-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \\\n-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'\n```", "value": { "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", "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", "1.5": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/dark/animated/1/1.5.gif" }, "static": { "1": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/dark/static/1/1.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", "1.5": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/dark/static/1/1.5.png" } }, "light": { "animated": { "1": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/light/animated/1/1.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", "1.5": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/light/animated/1/1.5.gif" }, "static": { "1": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/light/static/1/1.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", "1.5": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/light/static/1/1.5.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 } ] } } } } } }, "401": { "description": "* The Authorization header is required and must specify an app access token or user access token.\n* The ID in the Client-Id header must match the Client ID in the OAuth token." } }, "security": [ { "twitch_auth": [] } ] } }, "/extensions/transactions": { "get": { "summary": "Gets an extension’s list of transactions.", "description": "Gets an extension’s list of transactions. A transaction records the exchange of a currency (for example, Bits) for a digital product.\n\n__Authorization:__\n\nRequires an [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens).", "tags": [ "Bits" ], "externalDocs": { "description": "Get Extension Transactions", "url": "https://dev.twitch.tv/docs/api/reference#get-extension-transactions" }, "operationId": "get-extension-transactions", "parameters": [ { "name": "extension_id", "in": "query", "description": "The ID of the extension whose list of transactions you want to get.", "schema": { "type": "string" }, "required": true }, { "name": "id", "in": "query", "description": "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.", "schema": { "type": "array", "items": { "type": "string" } }, "explode": true }, { "name": "first", "in": "query", "description": "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.", "schema": { "type": "integer", "format": "int32" } }, { "name": "after", "in": "query", "description": "The cursor used to get the next page of results. The **Pagination** object in the response contains the cursor’s value. [Read More](https://dev.twitch.tv/docs/api/guide#pagination)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the list of transactions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetExtensionTransactionsResponse" }, "examples": { "Example": { "description": "_Request:_\n\n```bash\ncurl -X GET\n'https://api.twitch.tv/helix/extensions/transactions?extension_id=1234' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```", "value": { "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" } } } } } } }, "400": { "description": "* The _extension\\_id_ query parameter is required.\n* The request specified too many _id_ query parameters.\n* The pagination cursor is not valid." }, "401": { "description": "* The Authorization header is required and must specify an app access token.\n* The access token is not valid.\n* The ID in the _extension\\_id_ query parameter must match the client ID in the access token.\n* The ID in the Client-Id header must match the client ID in the access token." }, "404": { "description": "* One or more of the transaction IDs specified using the _id_ query parameter were not found." } }, "security": [ { "twitch_auth": [] } ] } }, "/channels": { "get": { "summary": "Gets information about one or more channels.", "description": "Gets information about one or more channels.\n\n__Authorization:__\n\nRequires an [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens) or [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens).", "tags": [ "Channels" ], "externalDocs": { "description": "Get Channel Information", "url": "https://dev.twitch.tv/docs/api/reference#get-channel-information" }, "operationId": "get-channel-information", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "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.", "schema": { "type": "array", "items": { "type": "string" } }, "required": true, "explode": true } ], "responses": { "200": { "description": "Successfully retrieved the list of channels.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetChannelInformationResponse" }, "examples": { "Example": { "description": "_Request:_\n\nGets information about the TwitchDev channel.\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/channels?broadcaster_id=141981764' \\\n-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \\\n-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'\n```", "value": { "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, "tags": [ "DevsInTheKnow" ], "content_classification_labels": [ "Gambling", "DrugsIntoxication", "MatureGame" ], "is_branded_content": false } ] } } } } } }, "400": { "description": "* The _broadcaster\\_id_ query parameter is required.\n* The broadcaster ID is not valid.\n* The number of _broadcaster\\_id_ query parameters exceeds the maximum allowed." }, "401": { "description": "* The Authorization header is required and must specify an app access token or user access token.\n* The OAuth token is not valid.\n* The ID in the Client-Id header must match the Client ID in the OAuth token." }, "429": { "description": "* The application exceeded the number of calls it may make per minute. For details, see [Rate Limits](https://dev.twitch.tv/docs/api/guide#twitch-rate-limits)." }, "500": { "description": "" } }, "security": [ { "twitch_auth": [] } ] }, "patch": { "summary": "Updates a channel’s properties.", "description": "Updates a channel’s properties.\n\n__Authorization:__\n\nRequires a [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **channel:manage:broadcast** scope.\n\n__Request Body:__\n\nAll fields are optional, but you must specify at least one field.", "tags": [ "Channels" ], "externalDocs": { "description": "Modify Channel Information", "url": "https://dev.twitch.tv/docs/api/reference#modify-channel-information" }, "operationId": "modify-channel-information", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster whose channel you want to update. This ID must match the user ID in the user access token.", "schema": { "type": "string" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModifyChannelInformationBody" }, "examples": { "Example 1": { "value": { "game_id": "33214", "title": "there are helicopters in the game? REASON TO PLAY FORTNITE found", "broadcaster_language": "en", "tags": [ "LevelingUp" ] } }, "Example 2": { "value": { "game_id": "SomeGameID", "content_classification_labels": [ { "id": "Gambling", "is_enabled": true }, { "id": "DrugsIntoxication", "is_enabled": false } ], "is_branded_content": true }, "description": "Set CCLs for a Channel" } } } } }, "responses": { "204": { "description": "Successfully updated the channel’s properties.\n\n__Examples__\n\n_Request:_\n\n```bash\ncurl -X PATCH 'https://api.twitch.tv/helix/channels?broadcaster_id=41245072' \\\n-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \\\n-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\"game_id\":\"33214\", \"title\":\"there are helicopters in the game? REASON TO PLAY FORTNITE found\", \"broadcaster_language\":\"en\", \"tags\":[\"LevelingUp\"]}'\n```\n\nSet CCLs for a Channel\n\n```bash\ncurl -X PATCH\n'https://api.twitch.tv/helix/channels?broadcaster_id=41245072' \\\n-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \\\n-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{ \n \"game_id\": \"SomeGameID\",\n \"content_classification_labels\": [\n {\"id\": \"Gambling\", \"is_enabled\": true}, \n {\"id\": \"DrugsIntoxication\", \"is_enabled\": false} \n ],\n \"is_branded_content\": true\n}'\n```" }, "400": { "description": "* The _broadcaster\\_id_ query parameter is required.\n* The request must update at least one property.\n* The `title` field may not contain an empty string.\n* The ID in `game_id` is not valid.\n* To update the `delay` field, the broadcaster must have partner status.\n* The list in the `tags` field exceeds the maximum number of tags allowed.\n* A tag in the `tags` field exceeds the maximum length allowed.\n* A tag in the `tags` field is empty.\n* A tag in the `tags` field contains special characters or spaces.\n* One or more tags in the `tags` field failed AutoMod review.\n* Game restricted for user's age and region" }, "401": { "description": "* User requests CCL for a channel they don’t own\n* The ID in _broadcaster\\_id_ must match the user ID found in the OAuth token.\n* The Authorization header is required and must specify a user access token.\n* The OAuth token must include the **channel:manage:broadcast** scope.\n* The OAuth token is not valid.\n* The ID in the Client-Id header must match the Client ID in the OAuth token." }, "403": { "description": "* User requested gaming CCLs to be added to their channel\n* Unallowed CCLs declared for underaged authorized user in a restricted country" }, "409": { "description": "User set the Branded Content flag too frequently" }, "500": { "description": "" } }, "security": [ { "twitch_auth": [ "channel:manage:broadcast" ] } ] } }, "/channels/editors": { "get": { "summary": "Gets the broadcaster’s list editors.", "description": "Gets the broadcaster’s list editors.\n\n__Authorization:__\n\nRequires a [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **channel:read:editors** scope.", "tags": [ "Channels" ], "externalDocs": { "description": "Get Channel Editors", "url": "https://dev.twitch.tv/docs/api/reference#get-channel-editors" }, "operationId": "get-channel-editors", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster that owns the channel. This ID must match the user ID in the access token.", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Successfully retrieved the broadcaster's list of editors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetChannelEditorsResponse" }, "examples": { "Example": { "description": "_Request:_\n\nGets the list of editors for TwitchDev.\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/channels/editors?broadcaster_id=141981764' \\\n-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \\\n-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz' \\\n```", "value": { "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" } ] } } } } } }, "400": { "description": "* The _broadcaster\\_id_ query parameter is required." }, "401": { "description": "* The ID in the _broadcaster\\_id_ query parameter must match the user ID found in the OAuth token.\n* The Authorization header is required and must specify a user access token.\n* The OAuth token must include the **channel:read:editors** scope.\n* The OAuth token is not valid.\n* The ID in the Client-Id header must match the Client ID in the OAuth token." } }, "security": [ { "twitch_auth": [ "channel:read:editors" ] } ] } }, "/channels/followed": { "get": { "summary": "Gets a list of broadcasters that the specified user follows. You can also use this endpoint to see whether a user follows a specific broadcaster.", "description": "Gets a list of broadcasters that the specified user follows. You can also use this endpoint to see whether a user follows a specific broadcaster.\n\n__Authorization:__\n\nRequires a [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **user:read:follows** scope.", "tags": [ "Channels" ], "externalDocs": { "description": "Get Followed Channels", "url": "https://dev.twitch.tv/docs/api/reference#get-followed-channels" }, "operationId": "get-followed-channels", "parameters": [ { "name": "user_id", "in": "query", "description": "A user’s ID. Returns the list of broadcasters that this user follows. This ID must match the user ID in the user OAuth token.", "schema": { "type": "string" }, "required": true }, { "name": "broadcaster_id", "in": "query", "description": "A broadcaster’s ID. Use this parameter to see whether the user follows this broadcaster. If specified, the response contains this broadcaster if the user follows them. If not specified, the response contains all broadcasters that the user follows.", "schema": { "type": "string" } }, { "name": "first", "in": "query", "description": "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.", "schema": { "type": "integer", "format": "int32" } }, { "name": "after", "in": "query", "description": "The cursor used to get the next page of results. The **Pagination** object in the response contains the cursor’s value. [Read more](https://dev.twitch.tv/docs/api/guide#pagination).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the broadcaster's list of followers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetFollowedChannelsResponse" }, "examples": { "Example 1": { "description": "_Request:_\n\nGets the list of broadcasters that the specified user follows.\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/channels/followed?user_id=123456' \\\n-H 'Authorization: Bearer kpvy3cjboyptmiacwr0c19hotn5s' \\\n-H 'Client-Id: hof5gwx0su6owfn0nyan9c87zr6t'\n```", "value": { "total": 8, "data": [ { "broadcaster_id": "11111", "broadcaster_login": "userloginname", "broadcaster_name": "UserDisplayName", "followed_at": "2022-05-24T22:22:08Z" } ], "pagination": { "cursor": "eyJiIjpudWxsLCJhIjp7Ik9mZnNldCI6NX19" } } }, "Example 2": { "description": "The `data` field is not an empty array, which means that the user does follow the specified broadcaster.\n\n_Request:_\n\nChecks whether the specified user follows the specified broadcaster.\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/channels/followed?user_id=123456&broadcaster_id=654321' \\\n-H 'Authorization: Bearer kpvy3cjboyptmiacwr0c19hotn5s' \\\n-H 'Client-Id: hof5gwx0su6owfn0nyan9c87zr6t'\n```", "value": { "total": 8, "data": [ { "broadcaster_id": "654321", "broadcaster_login": "basketweaver101", "broadcaster_name": "BasketWeaver101", "followed_at": "2022-05-24T22:22:08Z" } ], "pagination": {} } } } } } }, "400": { "description": "Possible reasons: \n \n* The _user\\_id_ query parameter is required.\n* The _broadcaster\\_id_ query parameter is not valid.\n* The _user\\_id_ query parameter is required." }, "401": { "description": "Possible reasons: \n \n* The ID in the _user\\_id_ query parameter must match the user ID in the access token.\n* The Authorization header is required and must contain a user access token.\n* The user access token is missing the **user:read:follows** scope.\n* The OAuth token is not valid.\n* The client ID specified in the Client-Id header does not match the client ID specified in the OAuth token." } }, "security": [ { "twitch_auth": [ "user:read:follows" ] } ] } }, "/channels/followers": { "get": { "summary": "Gets a list of users that follow the specified broadcaster. You can also use this endpoint to see whether a specific user follows the broadcaster.", "description": "Gets a list of users that follow the specified broadcaster. You can also use this endpoint to see whether a specific user follows the broadcaster.\n\n__Authorization:__\n\n* Requires a [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **moderator:read:followers** scope.\n* The ID in the broadcaster\\_id query parameter must match the user ID in the access token or the user ID in the access token must be a moderator for the specified broadcaster.\n\nThis endpoint will return specific follower information only if both of the above are true. If a scope is not provided or the user isn’t the broadcaster or a moderator for the specified channel, only the total follower count will be included in the response.", "tags": [ "Channels" ], "externalDocs": { "description": "Get Channel Followers", "url": "https://dev.twitch.tv/docs/api/reference#get-channel-followers" }, "operationId": "get-channel-followers", "parameters": [ { "name": "user_id", "in": "query", "description": "A user’s ID. Use this parameter to see whether the user follows this broadcaster. If specified, the response contains this user if they follow the broadcaster. If not specified, the response contains all users that follow the broadcaster. \n \nUsing this parameter requires both a user access token with the **moderator:read:followers** scope and the user ID in the access token match the broadcaster\\_id or be the user ID for a moderator of the specified broadcaster.", "schema": { "type": "string" } }, { "name": "broadcaster_id", "in": "query", "description": "The broadcaster’s ID. Returns the list of users that follow this broadcaster.", "schema": { "type": "string" }, "required": true }, { "name": "first", "in": "query", "description": "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.", "schema": { "type": "integer", "format": "int32" } }, { "name": "after", "in": "query", "description": "The cursor used to get the next page of results. The **Pagination** object in the response contains the cursor’s value. [Read more](https://dev.twitch.tv/docs/api/guide#pagination).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the broadcaster’s list of followers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetChannelFollowersResponse" }, "examples": { "Example 1": { "description": "_Request:_\n\nGets the list of users that follow the specified broadcaster.\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/channels/followers?broadcaster_id=123456' \\\n-H 'Authorization: Bearer kpvy3cjboyptmiacwr0c19hotn5s' \\\n-H 'Client-Id: hof5gwx0su6owfn0nyan9c87zr6t'\n```", "value": { "total": 8, "data": [ { "user_id": "11111", "user_name": "UserDisplayName", "user_login": "userloginname", "followed_at": "2022-05-24T22:22:08Z" } ], "pagination": { "cursor": "eyJiIjpudWxsLCJhIjp7Ik9mZnNldCI6NX19" } } }, "Example 2": { "description": "The `data` field is an empty array, which means the user doesn’t follow the specified broadcaster.\n\n_Request:_\n\nChecks whether the specified user follows the specified broadcaster.\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/channels/followers?broadcaster_id=123456&user_id=654321' \\\n-H 'Authorization: Bearer kpvy3cjboyptmiacwr0c19hotn5s' \\\n-H 'Client-Id: hof5gwx0su6owfn0nyan9c87zr6t'\n```", "value": { "total": 8, "data": [], "pagination": {} } } } } } }, "400": { "description": "Possible reasons: \n \n* The _broadcaster\\_id_ query parameter is required.\n* The _broadcaster\\_id_ query parameter is not valid." }, "401": { "description": "Possible reasons: \n \n* The ID in the _broadcaster\\_id_ query parameter must match the user ID in the access token or the user must be a moderator for the specified broadcaster.\n* The Authorization header is required and must contain a user access token.\n* The user access token is missing the **moderator:read:followers** scope.\n* The OAuth token is not valid.\n* The client ID specified in the Client-Id header does not match the client ID specified in the OAuth token.\n* The _user\\_id_ parameter was specified but either the user access token is missing the **moderator:read:followers** scope or the user is not the broadcaster or moderator for the specified channel" } }, "security": [ { "twitch_auth": [ "moderator:read:followers" ] } ] } }, "/channel_points/custom_rewards": { "post": { "summary": "Creates a Custom Reward in the broadcaster’s channel.", "description": "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.\n\n__Authorization:__\n\nRequires a [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **channel:manage:redemptions** scope.", "tags": [ "Channel Points" ], "externalDocs": { "description": "Create Custom Rewards", "url": "https://dev.twitch.tv/docs/api/reference#create-custom-rewards" }, "operationId": "create-custom-rewards", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster to add the custom reward to. This ID must match the user ID found in the OAuth token.", "schema": { "type": "string" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCustomRewardsBody" }, "examples": { "Example": { "value": { "title": "game analysis 1v1", "cost": 50000 }, "description": "Creates a custom reward." } } } } }, "responses": { "200": { "description": "Successfully created the custom reward.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCustomRewardsResponse" }, "examples": { "Example": { "description": "_Request:_\n\nCreates a custom reward.\n\n```bash\ncurl -X POST 'https://api.twitch.tv/helix/channel_points/custom_rewards?broadcaster_id=274637212' \\\n-H 'client-id: gx2pv4208cff0ig9ou7nk3riccffxt' \\\n-H 'Authorization: Bearer vjxv3i0l4zxru966wsnwji51tmpkj2' \\\n-H 'Content-Type: application/json' \\\n-d '{\n \"title\":\"game analysis 1v1\",\n \"cost\":50000\n}'\n```", "value": { "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 } ] } } } } } }, "400": { "description": "* The request exceeds the maximum number of rewards allowed per channel.\n* The _broadcaster\\_id_ query parameter is required.\n* The `title` field is required.\n* The `title` must contain a minimum of 1 character and a maximum of 45 characters.\n* The `title` must be unique amongst all of the broadcaster's custom rewards.\n* The `cost` field is required.\n* The `cost` field must contain a minimum of 1 point.\n* The `prompt` field is limited to a maximum of 200 characters.\n* If `is_max_per_stream_enabled` is **true**, the minimum value for `max_per_stream` is 1.\n* If `is_max_per_user_per_stream_enabled` is **true**, the minimum value for `max_per_user_per_stream` is 1.\n* If `is_global_cooldown_enabled` is **true**, the minimum value for `global_cooldown_seconds` is 1." }, "401": { "description": "* The Authorization header is required and must specify a user access token.\n* The user access token is missing the **channel:manage:redemptions** scope.\n* The OAuth token is not valid.\n* The ID in the Client-Id header must match the Client ID in the OAuth token." }, "403": { "description": "* The broadcaster is not a partner or affiliate." }, "500": { "description": "" } }, "security": [ { "twitch_auth": [ "channel:manage:redemptions" ] } ] }, "delete": { "summary": "Deletes a custom reward that the broadcaster created.", "description": "Deletes a custom reward that the broadcaster created.\n\nThe 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.\n\n__Authorization:__\n\nRequires a [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **channel:manage:redemptions** scope.", "tags": [ "Channel Points" ], "externalDocs": { "description": "Delete Custom Reward", "url": "https://dev.twitch.tv/docs/api/reference#delete-custom-reward" }, "operationId": "delete-custom-reward", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster that created the custom reward. This ID must match the user ID found in the OAuth token.", "schema": { "type": "string" }, "required": true }, { "name": "id", "in": "query", "description": "The ID of the custom reward to delete.", "schema": { "type": "string" }, "required": true } ], "responses": { "204": { "description": "Successfully deleted the custom reward.\n\n__Examples__\n\n_Request:_\n\nDeletes the specified custom reward.\n\n```bash\ncurl -X DELETE 'https://api.twitch.tv/helix/channel_points/custom_rewards?broadcaster_id=274637212&id=b045196d-9ce7-4a27-a9b9-279ed341ab28' \\\n-H 'Client-Id: gx2pv4208cff0ig9ou7nk3riccffxt' \\\n-H 'Authorization: Bearer vjxv3i0l4zxru966wsnwji51tmpkj2'\n```" }, "400": { "description": "* The _broadcaster\\_id_ query parameter is required.\n* The _id_ query parameter is required." }, "401": { "description": "* The Authorization header is required and must specify a user access token.\n* The user access token must include the **channel:manage:redemptions** scope.\n* The OAuth token is not valid.\n* The ID in the Client-Id header must match the Client ID in the OAuth token." }, "403": { "description": "* The ID in the Client-Id header must match the client ID used to create the custom reward.\n* The broadcaster is not a partner or affiliate." }, "404": { "description": "* The custom reward specified in the _id_ query parameter was not found." }, "500": { "description": "" } }, "security": [ { "twitch_auth": [ "channel:manage:redemptions" ] } ] }, "get": { "summary": "Gets a list of custom rewards that the specified broadcaster created.", "description": "Gets a list of custom rewards that the specified broadcaster created.\n\n**NOTE**: A channel may offer a maximum of 50 rewards, which includes both enabled and disabled rewards.\n\n__Authorization:__\n\nRequires a [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **channel:read:redemptions** or **channel:manage:redemptions** scope.", "tags": [ "Channel Points" ], "externalDocs": { "description": "Get Custom Reward", "url": "https://dev.twitch.tv/docs/api/reference#get-custom-reward" }, "operationId": "get-custom-reward", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster whose custom rewards you want to get. This ID must match the user ID found in the OAuth token.", "schema": { "type": "string" }, "required": true }, { "name": "id", "in": "query", "description": "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. \n \nDuplicate 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.", "schema": { "type": "array", "items": { "type": "string" } }, "explode": true }, { "name": "only_manageable_rewards", "in": "query", "description": "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**.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Successfully retrieved the broadcaster’s list of custom rewards.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetCustomRewardResponse" }, "examples": { "Example 1": { "description": "_Request:_\n\nGets the broadcaster’s list of custom rewards.\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/channel_points/custom_rewards?broadcaster_id=274637212'\n-H 'Client-Id: gx2pv4208cff0ig9ou7nk3riccffxt' \\\n-H 'Authorization: Bearer vjxv3i0l4zxru966wsnwji51tmpkj2'\n```", "value": { "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 2": { "description": "_Request:_\n\nGets the list of custom rewards that the calling Client ID can manage.\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/channel_points/custom_rewards?broadcaster_id=274637212&only_manageable_rewards=true'\n-H 'Client-Id: gx2pv4208cff0ig9ou7nk3riccffxt' \\\n-H 'Authorization: Bearer vjxv3i0l4zxru966wsnwji51tmpkj2'​​​​​​​\n```", "value": { "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 3": { "description": "_Request:_\n\nGets the specified custom reward.\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/channel_points/custom_rewards?broadcaster_id=274637212&id=92af127c-7326-4483-a52b-b0da0be61c01'\n-H 'Client-Id: gx2pv4208cff0ig9ou7nk3riccffxt' \\\n-H 'Authorization: Bearer vjxv3i0l4zxru966wsnwji51tmpkj2'​​​​​​​​​​​​​​\n```", "value": { "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 } ] } } } } } }, "400": { "description": "* The _broadcaster\\_id_ query parameter is required.\n* The request exceeds the maximum number of _id_ query parameters that you may specify." }, "401": { "description": "* The Authorization header must specify a user access token.\n* The user access token must include the **channel:read:redemptions** scope.\n* The OAuth token is not valid.\n* The ID in the Client-Id header must match the Client ID in the OAuth token." }, "403": { "description": "* The broadcaster is not a partner or affiliate." }, "404": { "description": "* All of the custom rewards specified using the _id_ query parameter were not found." }, "500": { "description": "" } }, "security": [ { "twitch_auth": [ "channel:read:redemptions", "channel:manage:redemptions" ] } ] }, "patch": { "summary": "Updates a custom reward.", "description": "Updates a custom reward. The app used to create the reward is the only app that may update the reward.\n\n__Authorization:__\n\nRequires a [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **channel:manage:redemptions** scope.\n\n__Request Body:__\n\nThe body of the request should contain only the fields you’re updating.", "tags": [ "Channel Points" ], "externalDocs": { "description": "Update Custom Reward", "url": "https://dev.twitch.tv/docs/api/reference#update-custom-reward" }, "operationId": "update-custom-reward", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster that’s updating the reward. This ID must match the user ID found in the OAuth token.", "schema": { "type": "string" }, "required": true }, { "name": "id", "in": "query", "description": "The ID of the reward to update.", "schema": { "type": "string" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCustomRewardBody" }, "examples": { "Example 1": { "value": { "is_enabled": false }, "description": "Disables the specified custom reward." }, "Example 2": { "value": { "title": "game analysis 2v2" }, "description": "Updates the reward’s title." } } } } }, "responses": { "200": { "description": "Successfully updated the custom reward.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCustomRewardResponse" }, "examples": { "Example 1": { "description": "_Request:_\n\nDisables the specified custom reward.\n\n```bash\ncurl -X PATCH 'https://api.twitch.tv/helix/channel_points/custom_rewards?broadcaster_id=274637212&id=92af127c-7326-4483-a52b-b0da0be61c01' \\\n-H 'client-id: gx2pv4208cff0ig9ou7nk3riccffxt' \\\n-H 'Authorization: Bearer vjxv3i0l4zxru966wsnwji51tmpkj2' \\\n-H 'Content-Type: application/json' \\\n-d '{\n \"is_enabled\": false\n }'\n```", "value": { "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 2": { "description": "_Request:_\n\nUpdates the reward’s title.\n\n```bash\ncurl -X PATCH 'https://api.twitch.tv/helix/channel_points/custom_rewards?broadcaster_id=274637212&id=92af127c-7326-4483-a52b-b0da0be61c01' \\\n-H 'client-id: gx2pv4208cff0ig9ou7nk3riccffxt' \\\n-H 'Authorization: Bearer vjxv3i0l4zxru966wsnwji51tmpkj2' \\\n-H 'Content-Type: application/json' \\\n-d '{\n \"title\": \"game analysis 2v2\"\n }'\n```", "value": { "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 } ] } } } } } }, "400": { "description": "ul>\n* The _broadcaster\\_id_ query parameter is required.\n* The _id_ query parameter is required.\n* The `title` must contain a minimum of 1 character and a maximum of 45 characters.\n* The `title` must be unique amongst all of the broadcaster's custom rewards.\n* The `cost` field must contain a minimum of 1 point.\n* The `prompt` field is limited to a maximum of 200 characters.\n* If `is_max_per_stream_enabled` is **true**, the minimum value for `max_per_stream` is 1.\n* If `is_max_per_user_per_stream_enabled` is **true**, the minimum value for `max_per_user_per_stream` is 1.\n* If `is_global_cooldown_enabled` is **true**, the minimum value for `global_cooldown_seconds` is 1 and the maximum is 604800." }, "401": { "description": "* The Authorization header is required and must specify a user access token.\n* The user access token must include the **channel:manage:redemptions** scope.\n* The OAuth token is not valide.\n* The ID in the Client-Id header must match the Client ID in the OAuth token." }, "403": { "description": "* The ID in the Client-Id header must match the client ID used to create the custom reward.\n* The broadcaster is not a partner or affiliate." }, "404": { "description": "* The custom reward specified in the _id_ query parameter was not found." }, "500": { "description": "" } }, "security": [ { "twitch_auth": [ "channel:manage:redemptions" ] } ] } }, "/channel_points/custom_rewards/redemptions": { "get": { "summary": "Gets a list of redemptions for a custom reward.", "description": "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.\n\n__Authorization:__\n\nRequires a [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **channel:read:redemptions** or **channel:manage:redemptions** scope.", "tags": [ "Channel Points" ], "externalDocs": { "description": "Get Custom Reward Redemption", "url": "https://dev.twitch.tv/docs/api/reference#get-custom-reward-redemption" }, "operationId": "get-custom-reward-redemption", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster that owns the custom reward. This ID must match the user ID found in the user OAuth token.", "schema": { "type": "string" }, "required": true }, { "name": "reward_id", "in": "query", "description": "The ID that identifies the custom reward whose redemptions you want to get.", "schema": { "type": "string" }, "required": true }, { "name": "status", "in": "query", "description": "The status of the redemptions to return. The possible case-sensitive values are: \n \n* CANCELED\n* FULFILLED\n* UNFULFILLED\n \n**NOTE**: This field is required only if you don’t specify the _id_ query parameter. \n \n**NOTE**: Canceled and fulfilled redemptions are returned for only a few days after they’re canceled or fulfilled.", "schema": { "type": "string", "enum": [ "CANCELED", "FULFILLED", "UNFULFILLED" ] } }, { "name": "id", "in": "query", "description": "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. \n \nDuplicate 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.", "schema": { "type": "array", "items": { "type": "string" } }, "explode": true }, { "name": "sort", "in": "query", "description": "The order to sort redemptions by. The possible case-sensitive values are: \n \n* OLDEST\n* NEWEST\n \nThe default is OLDEST.", "schema": { "type": "string", "enum": [ "OLDEST", "NEWEST" ] } }, { "name": "after", "in": "query", "description": "The cursor used to get the next page of results. The **Pagination** object in the response contains the cursor’s value. [Read more](https://dev.twitch.tv/docs/api/guide#pagination)", "schema": { "type": "string" } }, { "name": "first", "in": "query", "description": "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.", "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "Successfully retrieved the list of redeemed custom rewards.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetCustomRewardRedemptionResponse" }, "examples": { "Example 1": { "description": "_Request:_\n\nGets the list of redemptions that were canceled for the specified reward.\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/channel_points/custom_rewards/redemptions?broadcaster_id=274637212&reward_id=92af127c-7326-4483-a52b-b0da0be61c01&status=CANCELED' \\\n-H 'Client-Id: gx2pv4208cff0ig9ou7nk3riccffxt' \\\n-H 'Authorization: Bearer vjxv3i0l4zxru966wsnwji51tmpkj2'\n```", "value": { "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 2": { "description": "_Request:_\n\nGets redemptions by ID.\n\n```bash\ncurl -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' \\\n-H 'Client-Id: gx2pv4208cff0ig9ou7nk3riccffxt' \\\n-H 'Authorization: Bearer vjxv3i0l4zxru966wsnwji51tmpkj2'\n```", "value": { "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 } } ] } } } } } }, "400": { "description": "* The _broadcaster\\_id_ query parameter is required.\n* The _reward\\_id_ query parameter is required.\n* The _status_ query parameter is required if you didn't specify the _id_ query parameter.\n* The value in the _status_ query parameter is not valid.\n* The value in the _sort_ query parameter is not valid." }, "401": { "description": "* The Authorization header is required and must specify a user access token.\n* The user access token must include the **channel:read:redemptions** scope.\n* The OAuth token is not valid.\n* The ID in the Client-Id header must match the Client ID in the OAuth token." }, "403": { "description": "* The ID in the Client-Id header must match the client ID used to create the custom reward.\n* The broadcaster is not a partner or affiliate." }, "404": { "description": "* All of the redemptions specified using the _id_ query parameter were not found." }, "500": { "description": "" } }, "security": [ { "twitch_auth": [ "channel:read:redemptions", "channel:manage:redemptions" ] } ] }, "patch": { "summary": "Updates a redemption’s status.", "description": "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.\n\n__Authorization:__\n\nRequires a [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **channel:manage:redemptions** scope.", "tags": [ "Channel Points" ], "externalDocs": { "description": "Update Redemption Status", "url": "https://dev.twitch.tv/docs/api/reference#update-redemption-status" }, "operationId": "update-redemption-status", "parameters": [ { "name": "id", "in": "query", "description": "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.", "schema": { "type": "array", "items": { "type": "string" } }, "required": true, "explode": true }, { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster that’s updating the redemption. This ID must match the user ID in the user access token.", "schema": { "type": "string" }, "required": true }, { "name": "reward_id", "in": "query", "description": "The ID that identifies the reward that’s been redeemed.", "schema": { "type": "string" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRedemptionStatusBody" }, "examples": { "Example": { "value": { "status": "CANCELED" }, "description": "Updates a redemption’s status." } } } } }, "responses": { "200": { "description": "Successfully updated the redemption’s status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRedemptionStatusResponse" }, "examples": { "Example": { "description": "_Request:_\n\nUpdates a redemption’s status.\n\n```bash\ncurl -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' \\\n-H 'Client-Id: gx2pv4208cff0ig9ou7nk3riccffxt' \\\n-H 'Authorization: Bearer vjxv3i0l4zxru966wsnwji51tmpkj2' \\\n-H 'Content-Type: application/json' \\\n-d '{\n \"status\": \"CANCELED\"\n}'\n```", "value": { "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 } } ] } } } } } }, "400": { "description": "* The _broadcaster\\_id_ query parameter is required.\n* The _reward\\_id_ query parameter is required.\n* The _id_ query parameter is required.\n* The value in the _status_ query parameter is not valid." }, "401": { "description": "* The Authorization header is required and must specify a user access token.\n* The user access token must include the **channel:manage:redemptions** scope.\n* The OAuth token is not valid.\n* The ID in the Client-Id header must match the Client ID in the OAuth token." }, "403": { "description": "* The ID in the Client-Id header must match the client ID used to create the custom reward.\n* The broadcaster is not a partner or affiliate." }, "404": { "description": "* The custom reward specified in the _reward\\_id_ query parameter was not found.\n* The redemptions specified using the _id_ query parameter were not found or their statuses weren't marked as UNFULFILLED." }, "500": { "description": "" } }, "security": [ { "twitch_auth": [ "channel:manage:redemptions" ] } ] } }, "/charity/campaigns": { "get": { "summary": "Gets information about the broadcaster’s active charity campaign.", "description": "Gets information about the charity campaign that a broadcaster is running. For example, the campaign’s fundraising goal and the current amount of donations.\n\nTo 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](https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelcharity%5Fcampaignprogress) subscription type.\n\n__Authorization:__\n\nRequires a [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **channel:read:charity** scope.", "tags": [ "Charity" ], "externalDocs": { "description": "Get Charity Campaign", "url": "https://dev.twitch.tv/docs/api/reference#get-charity-campaign" }, "operationId": "get-charity-campaign", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster that’s currently running a charity campaign. This ID must match the user ID in the access token.", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Successfully retrieved information about the broadcaster’s active charity campaign.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetCharityCampaignResponse" }, "examples": { "Example": { "description": "_Request:_\n\nGets the broadcaster’s active charity campaign.\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/charity/campaigns?broadcaster_id=123456' \\\n-H 'Authorization: Bearer kpvy3cjboyptmiacwr0c19hotn5s' \\\n-H 'Client-Id: hof5gwx0su6owfn0nyan9c87zr6t'\n```", "value": { "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" } } ] } } } } } }, "400": { "description": "* The _broadcaster\\_id_ query parameter is required.\n* The _broadcaster\\_id_ query parameter is not valid." }, "401": { "description": "* The ID in the _broadcaster\\_id_ query parameter must match the user ID in the access token.\n* The Authorization header is required and must contain a user access token.\n* The user access token must include the **channel:read:charity** scope.\n* The access token is not valid.\n* The client ID specified in the Client-Id header must match the client ID specified in the access token." }, "403": { "description": "* The broadcaster is not a partner or affiliate." } }, "security": [ { "twitch_auth": [ "channel:read:charity" ] } ] } }, "/charity/donations": { "get": { "summary": "Gets the list of donations that users have made to the broadcaster’s active charity campaign.", "description": "Gets the list of donations that users have made to the broadcaster’s active charity campaign.\n\nTo receive events as donations occur, subscribe to the [channel.charity\\_campaign.donate](https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelcharity%5Fcampaigndonate) subscription type.\n\n__Authorization:__\n\nRequires a user access token that includes the **channel:read:charity** scope.", "tags": [ "Charity" ], "externalDocs": { "description": "Get Charity Campaign Donations", "url": "https://dev.twitch.tv/docs/api/reference#get-charity-campaign-donations" }, "operationId": "get-charity-campaign-donations", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster that’s currently running a charity campaign. This ID must match the user ID in the access token.", "schema": { "type": "string" }, "required": true }, { "name": "first", "in": "query", "description": "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.", "schema": { "type": "integer", "format": "int32" } }, { "name": "after", "in": "query", "description": "The cursor used to get the next page of results. The **Pagination** object in the response contains the cursor’s value. [Read More](https://dev.twitch.tv/docs/api/guide#pagination)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the list of donations that users contributed to the broadcaster’s charity campaign.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetCharityCampaignDonationsResponse" }, "examples": { "Example": { "description": "_Request:_\n\nGets the broadcaster’s active charity campaign.\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/charity/donations?broadcaster_id=123456' \\\n-H 'Authorization: Bearer kpvy3cjboyptmiacwr0c19hotn5s' \\\n-H 'Client-Id: hof5gwx0su6owfn0nyan9c87zr6t'\n```", "value": { "data": [ { "id": "a1b2c3-aabb-4455-d1e2f3", "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" } }, { "id": "z1y2x3-ccdd-6677-d1e2f3", "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" } } } } } } }, "400": { "description": "* The _broadcaster\\_id_ query parameter is required.\n* The _broadcaster\\_id_ query parameter is not valid." }, "401": { "description": "* The ID in the _broadcaster\\_id_ query parameter must match the user ID in the access token.\n* The Authorization header is required and must contain a user access token.\n* The user access token must include the **channel:read:charity** scope.\n* The access token is not valid.\n* The client ID specified in the Client-Id header must match the client ID specified in the access token." }, "403": { "description": "* The broadcaster is not a partner or affiliate." } }, "security": [ { "twitch_auth": [ "channel:read:charity" ] } ] } }, "/chat/chatters": { "get": { "summary": "Gets the list of users that are connected to the broadcaster’s chat session.", "description": "Gets the list of users that are connected to the broadcaster’s chat session.\n\n**NOTE**: There is a delay between when users join and leave a chat and when the list is updated accordingly.\n\nTo determine whether a user is a moderator or VIP, use the [Get Moderators](https://dev.twitch.tv/docs/api/reference#get-moderators) and [Get VIPs](https://dev.twitch.tv/docs/api/reference#get-vips) endpoints. You can check the roles of up to 100 users.\n\n__Authorization:__\n\nRequires one of the following:\n\n* A [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **moderator:read:chatters** scope.\n* BETA An [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens) where the application, through a prior authorization, has the **moderator:read:chatters** scope for the user represented by the `moderator_id` query parameter.", "tags": [ "Chat" ], "externalDocs": { "description": "Get Chatters", "url": "https://dev.twitch.tv/docs/api/reference#get-chatters" }, "operationId": "get-chatters", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster whose list of chatters you want to get.", "schema": { "type": "string" }, "required": true }, { "name": "moderator_id", "in": "query", "description": "The ID of the broadcaster or one of the broadcaster’s moderators. This ID must match the user ID in the user access token.", "schema": { "type": "string" }, "required": true }, { "name": "first", "in": "query", "description": "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.", "schema": { "type": "integer", "format": "int32" } }, { "name": "after", "in": "query", "description": "The cursor used to get the next page of results. The **Pagination** object in the response contains the cursor’s value. [Read More](https://dev.twitch.tv/docs/api/guide#pagination)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the broadcaster’s list of chatters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetChattersResponse" }, "examples": { "Example": { "description": "_Request:_\n\nGets the list of users that are connected to the specified broadcaster’s chat room.\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/chat/chatters?broadcaster_id=123456&moderator_id=654321' \\\n-H 'Authorization: Bearer kpvy3cjboyptmiacwr0c19hotn5s' \\\n-H 'Client-Id: hof5gwx0su6owfn0nyan9c87zr6t'\n```", "value": { "data": [ { "user_id": "128393656", "user_login": "smittysmithers", "user_name": "smittysmithers" } ], "pagination": { "cursor": "eyJiIjpudWxsLCJhIjp7Ik9mZnNldCI6NX19" }, "total": 8 } } } } } }, "400": { "description": "* The _broadcaster\\_id_ query parameter is required.\n* The ID in the _broadcaster\\_id_ query parameter is not valid.\n* The _moderator\\_id_ query parameter is required.\n* The ID in the _moderator\\_id_ query parameter is not valid." }, "401": { "description": "* The ID in the _moderator\\_id_ query parameter must match the user ID in the access token.\n* The Authorization header is required and must contain a user access token.\n* The user access token must include the **moderator:read:chatters** scope.\n* The access token is not valid.\n* The client ID specified in the Client-Id header does not match the client ID specified in the access token." }, "403": { "description": "* The user in the _moderator\\_id_ query parameter is not one of the broadcaster's moderators." } }, "security": [ { "twitch_auth": [ "moderator:read:chatters" ] } ] } }, "/chat/emotes": { "get": { "summary": "Gets the broadcaster’s list of custom emotes.", "description": "Gets the broadcaster’s list of custom emotes. 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](https://dev.twitch.tv/docs/irc/emotes)\n\nFor information about the custom emotes, see [subscriber emotes](https://help.twitch.tv/s/article/subscriber-emote-guide), [Bits tier emotes](https://help.twitch.tv/s/article/custom-bit-badges-guide?language=bg#slots), and [follower emotes](https://blog.twitch.tv/en/2021/06/04/kicking-off-10-years-with-our-biggest-emote-update-ever/).\n\n**NOTE:** With the exception of custom follower emotes, users may use custom emotes in any Twitch chat.\n\n__Authorization:__\n\nRequires an [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens) or [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens).", "tags": [ "Chat" ], "externalDocs": { "description": "Get Channel Emotes", "url": "https://dev.twitch.tv/docs/api/reference#get-channel-emotes" }, "operationId": "get-channel-emotes", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "An ID that identifies the broadcaster whose emotes you want to get.", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Successfully retrieved broadcaster's list of custom emotes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetChannelEmotesResponse" }, "examples": { "Example": { "description": "_Request:_\n\nGets custom emotes that the TwitchDev channel created.\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/chat/emotes?broadcaster_id=141981764' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```\n\n```bash\n# Twitch CLI example that gets the custom emotes for the specified channel.\n\ntwitch api get /chat/emotes -q broadcaster_id=141981764\n```", "value": { "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}}" } } } } } }, "400": { "description": "* The _broadcaster\\_id_ query parameter is required." }, "401": { "description": "* The Authorization header is required and must specify a valid app access token or user access token.\n* The OAuth token is not valid.\n* The ID in the Client-Id header must match the Client ID in the OAuth token." } }, "security": [ { "twitch_auth": [] } ] } }, "/chat/emotes/global": { "get": { "summary": "Gets all global emotes.", "description": "Gets the list of [global emotes](https://www.twitch.tv/creatorcamp/en/learn-the-basics/emotes/). Global emotes are Twitch-created emotes that users can use in any Twitch chat.\n\n[Learn More](https://dev.twitch.tv/docs/irc/emotes)\n\n__Authorization:__\n\nRequires an [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens) or [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens).\n\n__Request Query Parameters:__\n\nNone", "tags": [ "Chat" ], "externalDocs": { "description": "Get Global Emotes", "url": "https://dev.twitch.tv/docs/api/reference#get-global-emotes" }, "operationId": "get-global-emotes", "responses": { "200": { "description": "Successfully retrieved Twitch's list of global emotes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetGlobalEmotesResponse" }, "examples": { "Example": { "description": "_Request:_\n\nGets all global emotes.\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/chat/emotes/global' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```\n\n```bash\n# Twitch CLI example that gets all global emotes.\n\ntwitch api get /chat/emotes/global\n```", "value": { "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}}" } } } } } }, "401": { "description": "* The Authorization header is required and must specify a valid app access token or user access token.\n* The OAuth token is not valid.\n* The ID in the Client-Id header must match the Client ID in the OAuth token." } }, "security": [ { "twitch_auth": [] } ] } }, "/chat/emotes/set": { "get": { "summary": "Gets emotes for one or more specified emote sets.", "description": "Gets emotes for one or more specified emote sets.\n\nAn 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.\n\n[Learn More](https://dev.twitch.tv/docs/irc/emotes)\n\n__Authorization:__\n\nRequires an [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens) or [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens).", "tags": [ "Chat" ], "externalDocs": { "description": "Get Emote Sets", "url": "https://dev.twitch.tv/docs/api/reference#get-emote-sets" }, "operationId": "get-emote-sets", "parameters": [ { "name": "emote_set_id", "in": "query", "description": "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. \n \nTo get emote set IDs, use the [Get Channel Emotes](https://dev.twitch.tv/docs/api/reference#get-channel-emotes) API.", "schema": { "type": "array", "items": { "type": "string" } }, "required": true, "explode": true } ], "responses": { "200": { "description": "Successfully retrieved the emotes for the specified emote sets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetEmoteSetsResponse" }, "examples": { "Example": { "description": "_Request:_\n\nGets the emotes for the TwitchDev subscriber emote set.\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/chat/emotes/set?emote_set_id=301590448' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```\n\n```bash\n# Twitch CLI example that gets the emotes for the specified emote set.\n\ntwitch api get /chat/emotes/set -q emote_set_id=301590448\n```", "value": { "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}}" } } } } } }, "400": { "description": "* The _emote\\_set\\_id_ query parameter is required.\n* The number of _emote\\_set\\_id_ query parameters exceeds the maximum allowed." }, "401": { "description": "* The Authorization header is required and must specify a valid app access token or user access token.\n* The OAuth token is not valid.\n* The ID in the Client-Id header must match the Client ID in the OAuth token." } }, "security": [ { "twitch_auth": [] } ] } }, "/chat/badges": { "get": { "summary": "Gets the broadcaster’s list of custom chat badges.", "description": "Gets the broadcaster’s list of custom chat badges. The list is empty if the broadcaster hasn’t created custom chat badges. For information about custom badges, see [subscriber badges](https://help.twitch.tv/s/article/subscriber-badge-guide) and [Bits badges](https://help.twitch.tv/s/article/custom-bit-badges-guide).\n\n__Authorization:__\n\nRequires an [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens) or [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens).", "tags": [ "Chat" ], "externalDocs": { "description": "Get Channel Chat Badges", "url": "https://dev.twitch.tv/docs/api/reference#get-channel-chat-badges" }, "operationId": "get-channel-chat-badges", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster whose chat badges you want to get.", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Successfully retrieved the broadcaster’s custom chat badges.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetChannelChatBadgesResponse" }, "examples": { "Example": { "description": "_Request:_\n\nGet the list of custom chat badges that the BlueLava Twitch channel created.\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/chat/badges?broadcaster_id=135093069' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```", "value": { "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", "title": "cheer 1", "description": "cheer 1", "click_action": "visit_url", "click_url": "https://bits.twitch.tv" } ] }, { "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", "title": "Subscriber", "description": "Subscriber", "click_action": "subscribe_to_channel", "click_url": null } ] } ] } } } } } }, "400": { "description": "* The _broadcaster\\_id_ query parameter is required." }, "401": { "description": "* The Authorization header is required and must specify a valid app access token or user access token.\n* The OAuth token is not valid.\n* The ID in the Client-Id header must match the Client ID in the OAuth token." } }, "security": [ { "twitch_auth": [] } ] } }, "/chat/badges/global": { "get": { "summary": "Gets Twitch’s list of chat badges.", "description": "Gets Twitch’s list of chat badges, which users may use in any channel’s chat room. For information about chat badges, see [Twitch Chat Badges Guide](https://help.twitch.tv/s/article/twitch-chat-badges-guide).\n\n__Authorization:__\n\nRequires an [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens) or [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens).\n\n__Request Query Parameters:__\n\nNone", "tags": [ "Chat" ], "externalDocs": { "description": "Get Global Chat Badges", "url": "https://dev.twitch.tv/docs/api/reference#get-global-chat-badges" }, "operationId": "get-global-chat-badges", "responses": { "200": { "description": "Successfully retrieved the list of global chat badges.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetGlobalChatBadgesResponse" }, "examples": { "Example": { "description": "_Request:_\n\nGets the list of global chat badges.\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/chat/badges/global' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```", "value": { "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", "title": "VIP", "description": "VIP", "click_action": "visit_url", "click_url": "https://help.twitch.tv/customer/en/portal/articles/659115-twitch-chat-badges-guide" } ] } ] } } } } } }, "401": { "description": "* The Authorization header is required and must specify a valid app access token or user access token.\n* The OAuth token is not valid.\n* The ID in the Client-Id header must match the Client ID in the OAuth token." } }, "security": [ { "twitch_auth": [] } ] } }, "/chat/settings": { "get": { "summary": "Gets the broadcaster’s chat settings.", "description": "Gets the broadcaster’s chat settings.\n\nFor an overview of chat settings, see [Chat Commands for Broadcasters and Moderators](https://help.twitch.tv/s/article/chat-commands#AllMods) and [Moderator Preferences](https://help.twitch.tv/s/article/setting-up-moderation-for-your-twitch-channel#modpreferences).\n\n__Authorization:__\n\nRequires an [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens) or [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens).", "tags": [ "Chat" ], "externalDocs": { "description": "Get Chat Settings", "url": "https://dev.twitch.tv/docs/api/reference#get-chat-settings" }, "operationId": "get-chat-settings", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster whose chat settings you want to get.", "schema": { "type": "string" }, "required": true }, { "name": "moderator_id", "in": "query", "description": "The ID of the broadcaster or one of the broadcaster’s moderators. \n \nThis field is required only if you want to include the `non_moderator_chat_delay` and `non_moderator_chat_delay_duration` settings in the response. \n \nIf you specify this field, this ID must match the user ID in the user access token.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the broadcaster’s chat settings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetChatSettingsResponse" }, "examples": { "Example": { "description": "_Request:_\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/chat/settings?broadcaster_id=1234' \\\n-H 'Authorization: Bearer 4a4x78f5wqvkybms7mxfist3jmzul' \\\n-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh'\n```", "value": { "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 } ] } } } } } }, "400": { "description": "* The _broadcaster\\_id_ query parameter is required." }, "401": { "description": "* The Authorization header is required and must specify a valid app access token or user access token.\n* The OAuth token is not valid.\n* The ID in the Client-Id header must match the Client ID in the OAuth token." } }, "security": [ { "twitch_auth": [] } ] }, "patch": { "summary": "Updates the broadcaster’s chat settings.", "description": "Updates the broadcaster’s chat settings.\n\n__Authorization:__\n\nRequires one of the following:\n\n* A [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **moderator:manage:chat\\_settings** scope. The user ID associated with the token must match the `moderator_id` in the query parameter.\n* BETA An [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens) where the application, through a prior authorization, has the **moderator:manage:chat\\_settings** scope for the user represented by the `moderator_id` query parameter.\n\n__Request Body:__\n\nAll fields are optional. Specify only those fields that you want to update.\n\nTo 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).\n\nTo 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**.\n\nTo 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).", "tags": [ "Chat" ], "externalDocs": { "description": "Update Chat Settings", "url": "https://dev.twitch.tv/docs/api/reference#update-chat-settings" }, "operationId": "update-chat-settings", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster whose chat settings you want to update.", "schema": { "type": "string" }, "required": true }, { "name": "moderator_id", "in": "query", "description": "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.", "schema": { "type": "string" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateChatSettingsBody" }, "examples": { "Example 1": { "value": { "follower_mode": false }, "description": "This example disables `follower_mode` by setting it to false." }, "Example 2": { "value": { "slow_mode": true, "slow_mode_wait_time": 10 }, "description": "This example disables `follower_mode` by setting it to false.\n\nTo 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**." } } } } }, "responses": { "200": { "description": "Successfully updated the broadcaster’s chat settings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateChatSettingsResponse" }, "examples": { "Example": { "description": "_Request:_\n\nThis example disables `follower_mode` by setting it to false.\n\n```bash\ncurl -X PATCH 'https://api.twitch.tv/helix/chat/settings?broadcaster_id=1234&moderator_id=5678' \\\n-H 'Authorization: Bearer 4a4x78f5wqvkybms7mxfist3jmzul' \\\n-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh' \\\n-H 'Content-Type: application/json' \\\n-d '{\"follower_mode\": false}'\n```\n\nTo 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**.\n\n```bash\ncurl -X PATCH 'https://https://api.twitch.tv/helix/chat/settings?broadcaster_id=1234&moderator_id=5678' \\\n-H 'Authorization: Bearer 8j9yq1kpl92w96trqy7sintbsihdp' \\\n-H 'Client-Id: 0vql4f5yqu4spo6zrz1pkumcqwa9c' \\\n-H 'Content-Type: application/json' \\\n-d '{\"slow_mode\": true, \"slow_mode_wait_time\": 10}'\n```", "value": { "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 } ] } } } } } }, "400": { "description": "* The _broadcaster\\_id_ query parameter is required.\n* The _moderator\\_id_ query parameter is required.\n* If _slow\\_mode_ is **true**, the `slow_mode_wait_time` field must be set to a valid value.\n* If `follower_mode` is **true**, the `follower_mode_duration` field must be set to a valid value.\n* If `non_moderator_chat_delay` is **true**, the `non_moderator_chat_delay_duration` field must be set to a valid value." }, "401": { "description": "* The ID in the _moderator\\_id_ query parameter must match the user ID in the user access token.\n* The Authorization header is required and must contain a user access token.\n* The user access token must include the **moderator:manage:chat\\_settings** scope.\n* The access token is not valid.\n* The ID in the Client-Id header must match the client ID in the access token." }, "403": { "description": "* The user in the _moderator\\_id_ query parameter must have moderator privileges in the broadcaster's channel." } }, "security": [ { "twitch_auth": [ "moderator:manage:chat_settings" ] } ] } }, "/shared_chat/session": { "get": { "summary": "NEW Retrieves the active shared chat session for a channel.", "description": "NEW Retrieves the active shared chat session for a channel.\n\n__Authorization:__\n\nRequires an [app access token](https://dev.twitch.tv/docs/cli/token-command/#app-access-token) or [user access token](https://dev.twitch.tv/docs/authentication/#user-access-tokens).", "tags": [ "Chat" ], "externalDocs": { "description": "Get Shared Chat Session", "url": "https://dev.twitch.tv/docs/api/reference#get-shared-chat-session" }, "operationId": "get-shared-chat-session", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The User ID of the channel broadcaster.", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Successfully retrieved the shared chat session. Returns an empty array if the broadcaster\\_id in the request isn’t in a shared chat session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSharedChatSessionResponse" }, "examples": { "Example": { "description": "_Request:_\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/shared_chat/session?broadcaster_id=198704263' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```", "value": { "data": [ { "session_id": "359bce59-fa4e-41a5-bd6f-9bc0c8360485", "host_broadcaster_id": "198704263", "participants": [ { "broadcaster_id": "198704263" }, { "broadcaster_id": "487263401" } ], "created_at": "2024-09-29T19:45:37Z", "updated_at": "2024-09-29T19:45:37Z" } ] } } } } } }, "400": { "description": "The ID in the `broadcaster_id` query parameter is not valid." }, "401": { "description": "* The OAuth token is not valid.\n* The Authorization header is required and must contain a user access token." }, "500": { "description": "Internal Server Error." } }, "security": [ { "twitch_auth": [] } ] } }, "/chat/emotes/user": { "get": { "summary": "Retrieves emotes available to the user across all channels.", "description": "Retrieves emotes available to the user across all channels.\n\n__Authorization:__\n\n* Requires a user access token that includes the **user:read:emotes** scope.\n* Query parameter `user_id` must match the `user_id` in the user access token.", "tags": [ "Chat" ], "externalDocs": { "description": "Get User Emotes", "url": "https://dev.twitch.tv/docs/api/reference#get-user-emotes" }, "operationId": "get-user-emotes", "parameters": [ { "name": "user_id", "in": "query", "description": "The ID of the user. This ID must match the user ID in the user access token.", "schema": { "type": "string" }, "required": true }, { "name": "after", "in": "query", "description": "The cursor used to get the next page of results. The Pagination object in the response contains the cursor’s value.", "schema": { "type": "string" } }, { "name": "broadcaster_id", "in": "query", "description": "The User ID of a broadcaster you wish to get follower emotes of. Using this query parameter will guarantee inclusion of the broadcaster’s follower emotes in the response body. \n \n**Note:** If the user specified in `user_id` is subscribed to the broadcaster specified, their follower emotes will appear in the response body regardless if this query parameter is used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the emotes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetUserEmotesResponse" }, "examples": { "Example": { "description": "_Request:_\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/chat/emotes/user?user_id=123456' \\\n-H 'Authorization: Bearer kpvy3cjboyptmiacwr0c19hotn5s' \\\n-H 'Client-Id: hof5gwx0su6owfn0nyan9c87zr6t'\n```", "value": { "data": [ { "emote_set_id": "", "emote_type": "hypetrain", "format": [ "static" ], "id": "304420818", "name": "HypeLol", "owner_id": "477339272", "scale": [ "1.0", "2.0", "3.0" ], "theme_mode": [ "light", "dark" ] } ], "template": "https://static-cdn.jtvnw.net/emoticons/v2/{{id}}/{{format}}/{{theme_mode}}/{{scale}}", "pagination": { "cursor": "eyJiIjpudWxsLJxhIjoiIn0gf5" } } } } } } }, "400": { "description": "* The _user\\_id_ query parameter is required.\n* The ID in the _user\\_id_ query parameter is not valid." }, "401": { "description": "* The ID in _user\\_id_ must match the user ID in the user access token.\n* The Authorization header is required and must contain a user access token.\n* The user access token must include the **user:read:emotes** scope.\n* The access token is not valid.\n* The client ID specified in the Client-Id header does not match the client ID specified in the access token." } }, "security": [ { "twitch_auth": [ "user:read:emotes" ] } ] } }, "/chat/announcements": { "post": { "summary": "Sends an announcement to the broadcaster’s chat room.", "description": "Sends an announcement to the broadcaster’s chat room.\n\n**Rate Limits**: One announcement may be sent every 2 seconds.\n\n__Authorization:__\n\nRequires a [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **moderator:manage:announcements** scope.", "tags": [ "Chat" ], "externalDocs": { "description": "Send Chat Announcement", "url": "https://dev.twitch.tv/docs/api/reference#send-chat-announcement" }, "operationId": "send-chat-announcement", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster that owns the chat room to send the announcement to.", "schema": { "type": "string" }, "required": true }, { "name": "moderator_id", "in": "query", "description": "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.", "schema": { "type": "string" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendChatAnnouncementBody" }, "examples": { "Example": { "value": { "message": "Hello chat!", "color": "purple" }, "description": "Sends an announcement to the broadcaster’s chat room." } } } } }, "responses": { "204": { "description": "Successfully sent the announcement.\n\n__Examples__\n\n_Request:_\n\nSends an announcement to the broadcaster’s chat room.\n\n```bash\ncurl -X POST 'https://api.twitch.tv/helix/chat/announcements?broadcaster_id=11111&moderator_id=44444' \\\n-H 'Authorization: Bearer kpvy3cjboyptmdkiacwr0c19hotn5s' \\\n-H 'Client-Id: hof5gwx0su6owfnys0nyan9c87zr6t' \\\n-H 'Content-Type: application/json' \\\n-d '{\"message\":\"Hello chat!\",\"color\":\"purple\"}'\n```" }, "400": { "description": "* The `message` field in the request's body is required.\n* The `message` field may not contain an empty string.\n* The string in the `message` field failed review.\n* The specified color is not valid." }, "401": { "description": "* The Authorization header is required and must contain a user access token.\n* The user access token is missing the **moderator:manage:announcements** scope.\n* The OAuth token is not valid.\n* The client ID specified in the Client-Id header does not match the client ID specified in the OAuth token." }, "429": { "description": "The sender has exceeded the number of announcements they may send to this **broadcaster\\_id** within a given window." } }, "security": [ { "twitch_auth": [ "moderator:manage:announcements" ] } ] } }, "/chat/shoutouts": { "post": { "summary": "Sends a Shoutout to the specified broadcaster.", "description": "Sends a Shoutout to the specified broadcaster. Typically, you send Shoutouts when you or one of your moderators notice another broadcaster in your chat, the other broadcaster is coming up in conversation, or after they raid your broadcast.\n\nTwitch’s Shoutout feature is a great way for you to show support for other broadcasters and help them grow. Viewers who do not follow the other broadcaster will see a pop-up Follow button in your chat that they can click to follow the other broadcaster. [Learn More](https://help.twitch.tv/s/article/shoutouts)\n\n**Rate Limits**: The broadcaster may send a Shoutout once every 2 minutes. They may send the same broadcaster a Shoutout once every 60 minutes.\n\nTo receive notifications when a Shoutout is sent or received, subscribe to the [channel.shoutout.create](https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelshoutoutcreate) and [channel.shoutout.receive](https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelshoutoutreceive) subscription types. The **channel.shoutout.create** event includes cooldown periods that indicate when the broadcaster may send another Shoutout without exceeding the endpoint’s rate limit.\n\n__Authorization:__\n\nRequires one of the following:\n\n* A [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **moderator:manage:shoutouts** scope.\n* BETA An [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens) where the application, through prior authorizations, has: \n \n* The **channel:bot** scope for the user represented by the `broadcaster_id` query parameter, and \n* The **moderator:manage:shoutouts** and **user:bot** scopes for the user represented by the `moderator_id` in the query parameter.", "tags": [ "Chat" ], "externalDocs": { "description": "Send a Shoutout", "url": "https://dev.twitch.tv/docs/api/reference#send-a-shoutout" }, "operationId": "send-a-shoutout", "parameters": [ { "name": "from_broadcaster_id", "in": "query", "description": "The ID of the broadcaster that’s sending the Shoutout.", "schema": { "type": "string" }, "required": true }, { "name": "to_broadcaster_id", "in": "query", "description": "The ID of the broadcaster that’s receiving the Shoutout.", "schema": { "type": "string" }, "required": true }, { "name": "moderator_id", "in": "query", "description": "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.", "schema": { "type": "string" }, "required": true } ], "responses": { "204": { "description": "Successfully sent the specified broadcaster a Shoutout.\n\n__Examples__\n\n_Request:_\n\n```bash\ncurl -X POST 'https://api.twitch.tv/helix/chat/shoutouts?from_broadcaster_id=12345&to_broadcaster_id=626262&moderator_id=98765' \\\n-H 'Authorization: Bearer kpvy3cjboyptmdkiacwr0c19hotn5s' \\\n-H 'Client-Id: hof5gwx0su6owfnys0nyan9c87zr6t'\n```" }, "400": { "description": "* The _from\\_broadcaster\\_id_ query parameter is required.\n* The ID in the _from\\_broadcaster\\_id_ query parameter is not valid.\n* The _to\\_broadcaster\\_id_ query parameter is required.\n* The ID in the _to\\_broadcaster\\_id_ query parameter is not valid.\n* The broadcaster may not give themselves a Shoutout.\n* The broadcaster is not streaming live or does not have one or more viewers." }, "401": { "description": "* The ID in _moderator\\_id_ must match the user ID in the user access token.\n* The Authorization header is required and must contain a user access token.\n* The user access token must include the **moderator:manage:shoutouts** scope.\n* The access token is not valid.\n* The client ID specified in the Client-Id header does not match the client ID specified in the access token." }, "403": { "description": "* The user in _moderator\\_id_ is not one of the broadcaster's moderators.\n* The broadcaster may not send the specified broadcaster a Shoutout." }, "429": { "description": "* The broadcaster exceeded the number of Shoutouts they may send within a given window. See the endpoint's Rate Limits.\n* The broadcaster exceeded the number of Shoutouts they may send the same broadcaster within a given window. See the endpoint's Rate Limits." } }, "security": [ { "twitch_auth": [ "moderator:manage:shoutouts", "channel:bot", "user:bot" ] } ] } }, "/chat/messages": { "post": { "summary": "Sends a message to the broadcaster’s chat room.", "description": "Sends a message to the broadcaster’s chat room.\n\n**NOTE:** When sending messages to a Shared Chat session, behaviors differ depending on your authentication token type:\n\n* When using an _App Access Token_, messages will only be sent to the source channel (defined by the `broadcaster_id` parameter) by default starting on May 19, 2025\\. Messages can be sent to all channels by using the `for_source_only` parameter and setting it to `false`.\n* When using a _User Access Token_, messages will be sent to all channels in the shared chat session, including the source channel. This behavior cannot be changed with this token type.\n\n__Authorization:__\n\nRequires an [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens) or [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the `user:write:chat` scope. If app access token used, then additionally requires `user:bot` scope from chatting user, and either `channel:bot` scope from broadcaster or moderator status.", "tags": [ "Chat" ], "externalDocs": { "description": "Send Chat Message", "url": "https://dev.twitch.tv/docs/api/reference#send-chat-message" }, "operationId": "send-chat-message", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendChatMessageBody" }, "examples": { "Example": { "value": { "broadcaster_id": "12826", "sender_id": "141981764", "message": "Hello, world! twitchdevHype", "for_source_only": true } } } } } }, "responses": { "200": { "description": "Successfully sent the specified broadcaster a message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendChatMessageResponse" }, "examples": { "Example": { "description": "_Request:_\n\n```bash\ncurl -X POST 'https://api.twitch.tv/helix/chat/messages' \\\n-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \\\n-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz' \\\n-H 'Content-Type: application/json' \\\n-d '{\n \"broadcaster_id\": \"12826\",\n \"sender_id\": \"141981764\",\n \"message\": \"Hello, world! twitchdevHype\",\n \"for_source_only\": true\n}'\n```", "value": { "data": [ { "message_id": "abc-123-def", "is_sent": true } ] } } } } } }, "400": { "description": "* The _broadcaster\\_id_ query parameter is required.\n* The ID in the _broadcaster\\_id_ query parameter is not valid.\n* The _sender\\_id_ query parameter is required.\n* The ID in the _sender\\_id_ query parameter is not valid.\n* The _text_ query parameter is required.\n* The ID in the _reply\\_parent\\_message\\_id_ query parameter is not valid.\n* Cannot set \\*for\\_source\\_only\\* if User Access Token is used." }, "401": { "description": "* The ID in the user\\_id query parameter must match the user ID in the access token.\n* The Authorization header is required and must contain a user access token.\n* The user access token must include the user:write:chat scope.\n* The access token is not valid.\n* The client ID specified in the Client-Id header does not match the client ID specified in the access token." }, "403": { "description": "The sender is not permitted to send chat messages to the broadcaster’s chat room." }, "422": { "description": "The message is too large." } }, "security": [ { "twitch_auth": [ "user:write:chat", "user:bot", "channel:bot" ] } ] } }, "/chat/color": { "get": { "summary": "Gets the color used for the user’s name in chat.", "description": "Gets the color used for the user’s name in chat.\n\n__Authorization:__\n\nRequires an [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens) or [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens).", "tags": [ "Chat" ], "externalDocs": { "description": "Get User Chat Color", "url": "https://dev.twitch.tv/docs/api/reference#get-user-chat-color" }, "operationId": "get-user-chat-color", "parameters": [ { "name": "user_id", "in": "query", "description": "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. \n \nThe API ignores duplicate IDs and IDs that weren’t found.", "schema": { "type": "array", "items": { "type": "string" } }, "required": true, "explode": true } ], "responses": { "200": { "description": "Successfully retrieved the chat color used by the specified users.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetUserChatColorResponse" }, "examples": { "Example": { "description": "_Request:_\n\nGets the chat color code used by the specified users.\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/chat/color?user_id=11111&user_id=44444' \\\n-H 'Authorization: Bearer kpvy3cjboyptmdkiacwr0c19hotn5s' \\\n-H 'Client-Id: hof5gwx0su6owfnys0nyan9c87zr6t'\n```", "value": { "data": [ { "user_id": "11111", "user_name": "SpeedySpeedster1", "user_login": "speedyspeedster1", "color": "#9146FF" }, { "user_id": "44444", "user_name": "SpeedySpeedster2", "user_login": "speedyspeedster2", "color": "" } ] } } } } } }, "400": { "description": "* The ID in the _user\\_id_ query parameter is not valid." }, "401": { "description": "* The Authorization header is required and must contain an app access token or user access token.\n* The OAuth token is not valid.\n* The client ID specified in the Client-Id header does not match the client ID specified in the OAuth token." } }, "security": [ { "twitch_auth": [] } ] }, "put": { "summary": "Updates the color used for the user’s name in chat.", "description": "Updates the color used for the user’s name in chat.\n\n__Authorization:__\n\nRequires a [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **user:manage:chat\\_color** scope.", "tags": [ "Chat" ], "externalDocs": { "description": "Update User Chat Color", "url": "https://dev.twitch.tv/docs/api/reference#update-user-chat-color" }, "operationId": "update-user-chat-color", "parameters": [ { "name": "user_id", "in": "query", "description": "The ID of the user whose chat color you want to update. This ID must match the user ID in the access token.", "schema": { "type": "string" }, "required": true }, { "name": "color", "in": "query", "description": "The color to use for the user's name in chat. All users may specify one of the following named color values. \n \n* blue\n* blue\\_violet\n* cadet\\_blue\n* chocolate\n* coral\n* dodger\\_blue\n* firebrick\n* golden\\_rod\n* green\n* hot\\_pink\n* orange\\_red\n* red\n* sea\\_green\n* spring\\_green\n* yellow\\_green\n \nTurbo 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.", "schema": { "type": "string", "enum": [ "blue", "blue_violet", "cadet_blue", "chocolate", "coral", "dodger_blue", "firebrick", "golden_rod", "green", "hot_pink", "orange_red", "red", "sea_green", "spring_green", "yellow_green" ] }, "required": true } ], "responses": { "204": { "description": "Successfully updated the user's chat color.\n\n__Examples__\n\n_Request:_\n\nUses a named color to change the color that the user uses for their name in chat.\n\n```bash\ncurl -X PUT 'https://api.twitch.tv/helix/chat/color?user_id=123&color=blue' \\\n-H 'Authorization: Bearer kpvy3cjboyptmdkiacwr0c19hotn5s' \\\n-H 'Client-Id: hof5gwx0su6owfnys0nyan9c87zr6t'\n```\n\nUses a color Hex code to change the color that the user uses for their name in chat.\n\n```bash\ncurl -X PUT 'https://api.twitch.tv/helix/chat/color?user_id=123&color=%239146FF' \\\n-H 'Authorization: Bearer kpvy3cjboyptmdkiacwr0c19hotn5s' \\\n-H 'Client-Id: hof5gwx0su6owfnys0nyan9c87zr6t'\n```" }, "400": { "description": "* The ID in the _user\\_id_ query parameter is not valid.\n* The _color_ query parameter is required.\n* The named color in the _color_ query parameter is not valid.\n* To specify a Hex color code, the user must be a Turbo or Prime user." }, "401": { "description": "* The Authorization header is required and must contain a user access token.\n* The user access token must include the **user:manage:chat\\_color** scope.\n* The OAuth token is not valid.\n* The ID in the _user\\_id_ query parameter must match the user ID in the access token.\n* The client ID specified in the Client-Id header does not match the client ID specified in the OAuth token." } }, "security": [ { "twitch_auth": [ "user:manage:chat_color" ] } ] } }, "/clips": { "post": { "summary": "Creates a clip from the broadcaster’s stream.", "description": "Creates a clip from the broadcaster’s stream.\n\nThis 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 2: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.\n\nBy 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.\n\nCreating 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](https://dev.twitch.tv/docs/api/reference#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.\n\n__Authorization:__\n\nRequires a [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **clips:edit** scope.", "tags": [ "Clips" ], "externalDocs": { "description": "Create Clip", "url": "https://dev.twitch.tv/docs/api/reference#create-clip" }, "operationId": "create-clip", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster whose stream you want to create a clip from.", "schema": { "type": "string" }, "required": true }, { "name": "title", "in": "query", "description": "The title of the clip.", "schema": { "type": "string" } }, { "name": "duration", "in": "query", "description": "The length of the clip in seconds. Possible values range from 5 to 60 inclusively with a precision of 0.1\\. The default is 30.", "schema": { "type": "number", "format": "float" } } ], "responses": { "202": { "description": "Successfully started the clip process.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateClipResponse" }, "examples": { "Example": { "description": "_Request:_\n\n```bash\ncurl -X POST 'https://api.twitch.tv/helix/clips?broadcaster_id=141981764' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```", "value": { "data": [ { "id": "FiveWordsForClipSlug", "edit_url": "https://www.twitch.tv/twitchdev/clip/FiveWordsForClipSlug" } ] } } } } } }, "400": { "description": "* The _broadcaster\\_id_ query parameter is required.\n* The ID in the _broadcaster\\_id_ query parameter was not found.\n* The category is not clippable.\n* The title did not pass AutoMod checks." }, "401": { "description": "* The Authorization header is required and must specify user access token.\n* The user access token must include the **clips:edit** scope.\n* The OAuth token is not valid.\n* The ID in the Client-Id header must match the Client ID in the OAuth token." }, "403": { "description": "* The broadcaster has restricted the ability to capture clips to followers and/or subscribers only.\n* The specified broadcaster has not enabled clips on their channel.\n* The user is banned or timed out from the broadcaster’s channel." }, "404": { "description": "* The broadcaster in the _broadcaster\\_id_ query parameter must be broadcasting live." } }, "security": [ { "twitch_auth": [ "clips:edit" ] } ] }, "get": { "summary": "Gets one or more video clips.", "description": "Gets one or more video clips that were captured from streams. For information about clips, see [How to use clips](https://help.twitch.tv/s/article/how-to-use-clips).\n\nWhen using pagination for clips, note that the maximum number of results returned over multiple requests will be approximately 1,000\\. If additional results are necessary, paginate over different query parameters such as multiple `started_at` and `ended_at` timeframes to refine the search.\n\n__Authorization:__\n\nRequires an [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens) or [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens).\n\n__Request Query Parameters:__\n\nThe _id_, _game\\_id_, and _broadcaster\\_id_ query parameters are mutually exclusive.", "tags": [ "Clips" ], "externalDocs": { "description": "Get Clips", "url": "https://dev.twitch.tv/docs/api/reference#get-clips" }, "operationId": "get-clips", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "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.", "schema": { "type": "string" } }, { "name": "game_id", "in": "query", "description": "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.", "schema": { "type": "string" } }, { "name": "id", "in": "query", "description": "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.", "schema": { "type": "array", "items": { "type": "string" } }, "explode": true }, { "name": "started_at", "in": "query", "description": "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.", "schema": { "type": "string", "format": "date-time" } }, { "name": "ended_at", "in": "query", "description": "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.", "schema": { "type": "string", "format": "date-time" } }, { "name": "first", "in": "query", "description": "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.", "schema": { "type": "integer", "format": "int32" } }, { "name": "before", "in": "query", "description": "The cursor used to get the previous page of results. The **Pagination** object in the response contains the cursor’s value. [Read More](https://dev.twitch.tv/docs/api/guide#pagination)", "schema": { "type": "string" } }, { "name": "after", "in": "query", "description": "The cursor used to get the next page of results. The **Pagination** object in the response contains the cursor’s value. [Read More](https://dev.twitch.tv/docs/api/guide#pagination)", "schema": { "type": "string" } }, { "name": "is_featured", "in": "query", "description": "A Boolean value that determines whether the response includes featured clips. If **true**, returns only clips that are featured. If **false**, returns only clips that aren’t featured. All clips are returned if this parameter is not present.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Successfully retrieved the list of video clips.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetClipsResponse" }, "examples": { "Example 1": { "description": "_Request:_\n\nGets a clip by ID.\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/clips?id=AwkwardHelplessSalamanderSwiftRage' \\\n-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```", "value": { "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, "is_featured": false } ] } }, "Example 2": { "description": "_Request:_\n\nGets the broadcaster’s top 5 clips based on views.\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/clips?broadcaster_id=1234&first=5' \\\n-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```", "value": { "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, "is_featured": true } ], "pagination": { "cursor": "eyJiIjpudWxsLCJhIjoiIn0" } } } } } } }, "400": { "description": "* The _id_ or _game\\_id_ or _broadcaster\\_id_ query parameter is required.\n* The _id_, _game\\_id_, and _broadcaster\\_id_ query parameters are mutually exclusive; you may specify only one of them." }, "401": { "description": "* The Authorization header is required and must contain an app access token or user access token.\n* The OAuth token is not valid.\n* The client ID specified in the Client-Id header does not match the client ID specified in the OAuth token." }, "404": { "description": "* The ID in _game\\_id_ was not found." } }, "security": [ { "twitch_auth": [] } ] } }, "/videos/clips": { "post": { "summary": "NEW Creates a clip from the broadcaster’s VOD.", "description": "NEW Creates a clip from a broadcaster’s VOD on behalf of the broadcaster or an editor of the channel. Since a live stream is actively creating a VOD, this endpoint can also be used to create a clip from earlier in the current stream.\n\nThe duration of a clip can be from 5 seconds to 60 seconds in length, with a default of 30 seconds if not specified.\n\n`vod_offset` indicates where the clip will end. In other words, the clip will start at (`vod_offset` \\- `duration`) and end at `vod_offset`. This means that the value of `vod_offset` must greater than or equal to the value of `duration`.\n\nThe URL in the response’s `edit_url` field allows you to edit the clip’s title, feature the clip, create a portrait version of the clip, download the clip media, and share the clip directly to social platforms.\n\n__Authorization:__\n\nRequires an [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens) or [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **editor:manage:clips** or **channel:manage:clips** scope.", "tags": [ "Clips" ], "externalDocs": { "description": "Create Clip From VOD", "url": "https://dev.twitch.tv/docs/api/reference#create-clip-from-vod" }, "operationId": "create-clip-from-vod", "parameters": [ { "name": "editor_id", "in": "query", "description": "The user ID of the editor for the channel you want to create a clip for. If using the broadcaster’s auth token, this is the same as broadcaster\\_id. This must match the user\\_id in the user access token.", "schema": { "type": "string" }, "required": true }, { "name": "broadcaster_id", "in": "query", "description": "The user ID for the channel you want to create a clip for.", "schema": { "type": "string" }, "required": true }, { "name": "vod_id", "in": "query", "description": "ID of the VOD the user wants to clip.", "schema": { "type": "string" }, "required": true }, { "name": "vod_offset", "in": "query", "description": "Offset in the VOD to create the clip. See notes above.", "schema": { "type": "integer", "format": "int32" }, "required": true }, { "name": "duration", "in": "query", "description": "The length of the clip, in seconds. Precision is 0.1\\. Defaults to 30\\. Min: 5 seconds, Max: 60 seconds.", "schema": { "type": "number", "format": "float" } }, { "name": "title", "in": "query", "description": "The title of the clip.", "schema": { "type": "string" }, "required": true } ], "responses": { "202": { "description": "Successfully started the clip process.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateClipFromVODResponse" }, "examples": { "Example": { "description": "_Request:_\n\n```bash\ncurl -X POST 'https://api.twitch.tv/helix/videos/clips?broadcaster_id=141981764&editor_id=12826&vod_id=2277656159' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```", "value": { "data": [ { "id": "FiveWordsForClipSlug", "edit_url": "https://www.twitch.tv/twitchdev/clip/FiveWordsForClipSlug" } ] } } } } } }, "400": { "description": "* Validation errors: Invalid source type, missing required fields.\n* The broadcaster\\_id query parameter is required.\n* The ID in the broadcaster\\_id query parameter was not found.\n* The category is not clippable.\n* The title did not pass AutoMod checks.\n* Broadcaster is banned." }, "401": { "description": "* The Authorization header is required and must specify user access token.\n* The user access token must include the **editor:manage:clips** or **channel:manage:clips** scope.\n* The OAuth token is not valid.\n* The ID in the Client-Id header must match the Client ID in the OAuth token." }, "403": { "description": "* The broadcaster has restricted the ability to capture clips to followers and/or subscribers only.\n* The specified broadcaster has not enabled clips on their channel.\n* The user defined by the _editor\\_id_ is not authorized to create Clips.\n* The user is banned or timed out from the broadcaster's channel." }, "404": { "description": "* The broadcaster in the _broadcaster\\_id_ query parameter must be broadcasting live.\n* The VOD is not found..\n* The _broadcaster\\_id_ or the _editor\\_id_ does not exist." } }, "security": [ { "twitch_auth": [ "editor:manage:clips", "channel:manage:clips" ] } ] } }, "/clips/downloads": { "get": { "summary": "NEW Provides URLs to download the video file(s) for the specified clips.", "description": "NEW Provides URLs to download the video file(s) for the specified clips. For information about clips, see [How to use clips](https://help.twitch.tv/s/article/how-to-use-clips).\n\n**Rate Limits**: Limited to 100 requests per minute.\n\n__Authorization:__\n\nRequires an [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens) or [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the `editor:manage:clips` or `channel:manage:clips` scope.", "tags": [ "Clips" ], "externalDocs": { "description": "Get Clips Download", "url": "https://dev.twitch.tv/docs/api/reference#get-clips-download" }, "operationId": "get-clips-download", "parameters": [ { "name": "editor_id", "in": "query", "description": "The User ID of the editor for the channel you want to download a clip for. If using the broadcaster’s auth token, this is the same as `broadcaster_id`. This must match the `user_id` in the user access token.", "schema": { "type": "string" }, "required": true }, { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster you want to download clips for.", "schema": { "type": "string" }, "required": true }, { "name": "clip_id", "in": "query", "description": "The ID that identifies the clip you want to download. Include this parameter for each clip you want to download, up to a maximum of 10 clips. For example, `clip_id=SleepyGiftedPeppermintNerfRedBlaster-KbkBXYt3lOk3jy8-&clip_id=WimpyAltruisticKleeKeyboardCat-EiY5yMrEwZ4i4gwC`.", "schema": { "type": "array", "items": { "type": "string" } }, "required": true, "explode": true } ], "responses": { "200": { "description": "Successfully retrieved the clip download URL(s).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetClipsDownloadResponse" }, "examples": { "Example": { "description": "_Request:_\n\nGets clip download URLs for two clips from the TwitchDev channel.\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/clips/downloads?broadcaster_id=141981764&editor_id=141981764&clip_id=InexpensiveDistinctFoxChefFrank&clip_id=SpinelessCloudyLeopardMcaT' \\\n-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```", "value": { "data": [ { "clip_id": "InexpensiveDistinctFoxChefFrank", "landscape_download_url": "https://production.assets.clips.twitchcdn.net/yFZG...", "portrait_download_url": null }, { "clip_id": "SpinelessCloudyLeopardMcaT", "landscape_download_url": "https://production.assets.clips.twitchcdn.net/542j...", "portrait_download_url": null } ] } } } } } }, "400": { "description": "The ID in the broadcaster\\_id, editor\\_id, or clip\\_id query parameter is not valid." }, "401": { "description": "* The OAuth token is not valid.\n* The Authorization header is required and must contain a user access token or app access token.\n* The access token must include the editor:manage:clips or channel:manage:clips scope\n* The access token is not valid\n* The client ID specified in the Client-Id header does not match the client ID specified in the access token." }, "403": { "description": "The user is not an editor for the specified broadcaster." }, "500": { "description": "Internal Server Error." } }, "security": [ { "twitch_auth": [ "editor:manage:clips", "channel:manage:clips" ] } ] } }, "/eventsub/conduits": { "get": { "summary": "Gets the conduits for a client ID.", "description": "Gets the [conduits](https://dev.twitch.tv/docs/eventsub/handling-conduit-events/) for a client ID.\n\n__Authorization:__\n\nRequires an [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens).", "tags": [ "Conduits" ], "externalDocs": { "description": "Get Conduits", "url": "https://dev.twitch.tv/docs/api/reference#get-conduits" }, "operationId": "get-conduits", "responses": { "200": { "description": "Successfully retrieved conduits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetConduitsResponse" }, "examples": { "Example": { "description": "_Request:_\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/eventsub/conduits' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```", "value": { "data": [ { "id": "26b1c993-bfcf-44d9-b876-379dacafe75a", "shard_count": 15 }, { "id": "bfcfc993-26b1-b876-44d9-afe75a379dac", "shard_count": 5 } ] } } } } } }, "401": { "description": "Authorization header required with an app access token." } }, "security": [ { "twitch_auth": [] } ] }, "post": { "summary": "Creates a new conduit.", "description": "Creates a new [conduit](https://dev.twitch.tv/docs/eventsub/handling-conduit-events/).\n\n__Authorization:__\n\nRequires an [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens).", "tags": [ "Conduits" ], "externalDocs": { "description": "Create Conduits", "url": "https://dev.twitch.tv/docs/api/reference#create-conduits" }, "operationId": "create-conduits", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateConduitsBody" }, "examples": { "Example": { "value": { "shard_count": 5 } } } } } }, "responses": { "200": { "description": "Conduit created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateConduitsResponse" }, "examples": { "Example": { "description": "_Request:_\n\n```bash\ncurl -X POST 'https://api.twitch.tv/helix/eventsub/conduits' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \\\n-H 'Content-Type: application/json' \\\n-d '{\"shard_count\": 5}'\n```", "value": { "data": [ { "id": "bfcfc993-26b1-b876-44d9-afe75a379dac", "shard_count": 5 } ] } } } } } }, "400": { "description": "Invalid shard count." }, "401": { "description": "Authorization header required with an app access token." }, "429": { "description": "Conduit limit reached." } }, "security": [ { "twitch_auth": [] } ] }, "patch": { "summary": "Updates a conduit’s shard count.", "description": "Updates a [conduit’s](https://dev.twitch.tv/docs/eventsub/handling-conduit-events/) shard count. To delete shards, update the count to a lower number, and the shards above the count will be deleted. For example, if the existing shard count is 100, by resetting shard count to 50, shards 50-99 are disabled.\n\n__Authorization:__\n\nRequires an [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens).", "tags": [ "Conduits" ], "externalDocs": { "description": "Update Conduits", "url": "https://dev.twitch.tv/docs/api/reference#update-conduits" }, "operationId": "update-conduits", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateConduitsBody" }, "examples": { "Example": { "value": { "id": "bfcfc993-26b1-b876-44d9-afe75a379dac", "shard_count": 5 } } } } } }, "responses": { "200": { "description": "Conduit updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateConduitsResponse" }, "examples": { "Example": { "description": "_Request:_\n\n```bash\ncurl -X PATCH 'https://api.twitch.tv/helix/eventsub/conduits' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \\\n-H 'Content-Type: application/json' \\\n-d '{\n \"id\":\"bfcfc993-26b1-b876-44d9-afe75a379dac\",\n \"shard_count\":5\n}'\n```", "value": { "data": [ { "id": "bfcfc993-26b1-b876-44d9-afe75a379dac", "shard_count": 5 } ] } } } } } }, "400": { "description": "* Invalid shard count\n* The id query parameter is required." }, "401": { "description": "Authorization header required with an app access token." }, "404": { "description": "* Conduit not found.\n* Conduit’s owner must match the client ID in the access token." } }, "security": [ { "twitch_auth": [] } ] }, "delete": { "summary": "Deletes a specified conduit.", "description": "Deletes a specified [conduit](https://dev.twitch.tv/docs/eventsub/handling-conduit-events/). Note that it may take some time for Eventsub subscriptions on a deleted [conduit](https://dev.twitch.tv/docs/eventsub/handling-conduit-events/) to show as disabled when calling [Get Eventsub Subscriptions](https://dev.twitch.tv/docs/api/reference/#get-eventsub-subscriptions).\n\n__Authorization:__\n\nRequires an [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens).", "tags": [ "Conduits" ], "externalDocs": { "description": "Delete Conduit", "url": "https://dev.twitch.tv/docs/api/reference#delete-conduit" }, "operationId": "delete-conduit", "parameters": [ { "name": "id", "in": "query", "description": "Conduit ID.", "schema": { "type": "string" }, "required": true } ], "responses": { "204": { "description": "Successfully deleted the conduit.\n\n__Examples__\n\n_Request:_\n\n```bash\ncurl -X DELETE 'https://api.twitch.tv/helix/eventsub/conduits?id=bfcfc993-26b1-b876-44d9-afe75a379dac' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```" }, "400": { "description": "The id query parameter is required." }, "401": { "description": "Authorization header required with an app access token." }, "404": { "description": "* Conduit not found.\n* Conduit’s owner must match the client ID in the access token." } }, "security": [ { "twitch_auth": [] } ] } }, "/eventsub/conduits/shards": { "get": { "summary": "Gets a lists of all shards for a conduit.", "description": "Gets a lists of all shards for a [conduit](https://dev.twitch.tv/docs/eventsub/handling-conduit-events/).\n\n__Authorization:__\n\nRequires an [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens).", "tags": [ "Conduits" ], "externalDocs": { "description": "Get Conduit Shards", "url": "https://dev.twitch.tv/docs/api/reference#get-conduit-shards" }, "operationId": "get-conduit-shards", "parameters": [ { "name": "conduit_id", "in": "query", "description": "Conduit ID.", "schema": { "type": "string" }, "required": true }, { "name": "status", "in": "query", "description": "Status to filter by.", "schema": { "type": "string" } }, { "name": "after", "in": "query", "description": "The cursor used to get the next page of results. The pagination object in the response contains the cursor’s value.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved shards.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetConduitShardsResponse" }, "examples": { "Example": { "description": "_Request:_\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/eventsub/conduits/shards?conduit_id=bfcfc993-26b1-b876-44d9-afe75a379dac' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```", "value": { "data": [ { "id": "0", "status": "enabled", "transport": { "method": "webhook", "callback": "https://this-is-a-callback.com" } }, { "id": "1", "status": "webhook_callback_verification_pending", "transport": { "method": "webhook", "callback": "https://this-is-a-callback-2.com" } }, { "id": "2", "status": "enabled", "transport": { "method": "websocket", "session_id": "9fd5164a-a958-4c60-b7f4-6a7202506ca0", "connected_at": "2020-11-10T14:32:18.730260295Z" } }, { "id": "3", "status": "enabled", "transport": { "method": "websocket", "session_id": "238b4b08-13f1-4b8f-8d31-56665a7a9d9f", "connected_at": "2020-11-10T14:32:18.730260295Z" } }, { "id": "4", "status": "websocket_disconnected", "transport": { "method": "websocket", "session_id": "ad1c9fc3-0d99-4eb7-8a04-8608e8ff9ec9", "connected_at": "2020-11-10T14:32:18.730260295Z", "disconnected_at": "2020-11-11T14:32:18.730260295Z" } } ], "pagination": {} } } } } } }, "400": { "description": "The id query parameter is required." }, "401": { "description": "Authorization header required with an app access token." }, "404": { "description": "* Conduit not found.\n* Conduit’s owner must match the client ID in the access token." } }, "security": [ { "twitch_auth": [] } ] }, "patch": { "summary": "Updates shard(s) for a conduit.", "description": "Updates shard(s) for a [conduit](https://dev.twitch.tv/docs/eventsub/handling-conduit-events/).\n\n**NOTE:** Shard IDs are indexed starting at 0, so a conduit with a `shard_count` of 5 will have shards with IDs 0 through 4.\n\n__Authorization:__\n\nRequires an [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens).", "tags": [ "Conduits" ], "externalDocs": { "description": "Update Conduit Shards", "url": "https://dev.twitch.tv/docs/api/reference#update-conduit-shards" }, "operationId": "update-conduit-shards", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateConduitShardsBody" }, "examples": { "Example": { "value": { "conduit_id": "bfcfc993-26b1-b876-44d9-afe75a379dac", "shards": [ { "id": "0", "transport": { "method": "webhook", "callback": "https://this-is-a-callback.com", "secret": "s3cre7" } }, { "id": "1", "transport": { "method": "webhook", "callback": "https://this-is-a-callback-2.com", "secret": "s3cre7" } }, { "id": "3", "transport": { "method": "webhook", "callback": "https://this-is-a-callback-3.com", "secret": "s3cre7" } } ] } } } } } }, "responses": { "202": { "description": "Successfully retrieved shards.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateConduitShardsResponse" }, "examples": { "Example": { "description": "_Request:_\n\n```bash\ncurl -X PATCH 'https://api.twitch.tv/helix/eventsub/conduits/shards' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \\\n-H 'Content-Type: application/json' \\\n-d '{\n \"conduit_id\":\"bfcfc993-26b1-b876-44d9-afe75a379dac\",\n \"shards\": [{\n \"id\": \"0\",\n \"transport\": {\n \"method\": \"webhook\",\n \"callback\": \"https://this-is-a-callback.com\",\n \"secret\": \"s3cre7\"\n }\n },\n {\n \"id\": \"1\",\n \"transport\": {\n \"method\": \"webhook\",\n \"callback\": \"https://this-is-a-callback-2.com\",\n \"secret\": \"s3cre7\"\n }\n },\n {\n \"id\": \"3\",\n \"transport\":{\n \"method\": \"webhook\",\n \"callback\": \"https://this-is-a-callback-3.com\",\n \"secret\": \"s3cre7\"\n }\n }]\n}'\n```", "value": { "data": [ { "id": "0", "status": "enabled", "transport": { "method": "webhook", "callback": "https://this-is-a-callback.com" } }, { "id": "1", "status": "webhook_callback_verification_pending", "transport": { "method": "webhook", "callback": "https://this-is-a-callback-2.com" } } ], "errors": [ { "id": "3", "message": "The shard id is outside the conduit's range", "code": "invalid_parameter" } ] } } } } } }, "400": { "description": "The id query parameter is required." }, "401": { "description": "Authorization header required with an app access token." }, "404": { "description": "* Conduit not found.\n* Conduit’s owner must match the client ID in the access token." } }, "security": [ { "twitch_auth": [] } ] } }, "/content_classification_labels": { "get": { "summary": "Gets information about Twitch content classification labels.", "description": "Gets information about Twitch content classification labels.\n\n__Authorization:__\n\nRequires an [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens) or [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens).", "tags": [ "CCLs" ], "externalDocs": { "description": "Get Content Classification Labels", "url": "https://dev.twitch.tv/docs/api/reference#get-content-classification-labels" }, "operationId": "get-content-classification-labels", "parameters": [ { "name": "locale", "in": "query", "description": "Locale for the Content Classification Labels. You may specify a maximum of 1 locale. Default: `“en-US”` \nSupported locales: `\"bg-BG\", \"cs-CZ\", \"da-DK\", \"da-DK\", \"de-DE\", \"el-GR\", \"en-GB\", \"en-US\", \"es-ES\", \"es-MX\", \"fi-FI\", \"fr-FR\", \"hu-HU\", \"it-IT\", \"ja-JP\", \"ko-KR\", \"nl-NL\", \"no-NO\", \"pl-PL\", \"pt-BT\", \"pt-PT\", \"ro-RO\", \"ru-RU\", \"sk-SK\", \"sv-SE\", \"th-TH\", \"tr-TR\", \"vi-VN\", \"zh-CN\", \"zh-TW\"`", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the list of CCLs available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetContentClassificationLabelsResponse" }, "examples": { "Example": { "description": "_Request:_\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/content_classification_labels' \\\n-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \\\n-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'\n```", "value": { "data": [ { "id": "DebatedSocialIssuesAndPolitics", "description": "Discussions or debates about politics or sensitive social issues such as elections, civic integrity, military conflict, and civil rights in a polarizing manner.", "name": "Politics and Sensitive Social Issues" }, { "id": "DrugsIntoxication", "description": "Excessive tobacco glorification or promotion, any marijuana consumption/use, legal drug and alcohol induced intoxication, discussions of illegal drugs.", "name": "Drugs, Intoxication, or Excessive Tobacco Use" }, { "id": "Gambling", "description": "Participating in online or in-person gambling, poker or fantasy sports, that involve the exchange of real money.", "name": "Gambling" }, { "id": "MatureGame", "description": "Games that are rated Mature or less suitable for a younger audience.", "name": "Mature-rated game" }, { "id": "ProfanityVulgarity", "description": "Prolonged, and repeated use of obscenities, profanities, and vulgarities, especially as a regular part of speech.", "name": "Significant Profanity or Vulgarity" }, { "id": "SexualThemes", "description": "Content that focuses on sexualized physical attributes and activities, sexual topics, or experiences.", "name": "Sexual Themes" }, { "id": "ViolentGraphic", "description": "Simulations and/or depictions of realistic violence, gore, extreme injury, or death.", "name": "Violent and Graphic Depictions" } ] } } } } } }, "400": { "description": "" }, "401": { "description": "" }, "500": { "description": "" } }, "security": [ { "twitch_auth": [] } ] } }, "/entitlements/drops": { "get": { "summary": "Gets an organization’s list of entitlements that have been granted to a game, a user, or both.", "description": "Gets an organization’s list of entitlements that have been granted to a game, a user, or both.\n\n**NOTE:** Entitlements returned in the response body data are not guaranteed to be sorted by any field returned by the API. To retrieve **CLAIMED** or **FULFILLED** entitlements, use the `fulfillment_status` query parameter to filter results. To retrieve entitlements for a specific game, use the `game_id` query parameter to filter results.\n\nThe following table identifies the request parameters that you may specify based on the type of access token used.\n\n| Access token type | Parameter | Description |\n| - | - | - |\n| App | None | If you don’t specify request parameters, the request returns all entitlements that your organization owns. |\n| App | user_id | The request returns all entitlements for any game that the organization granted to the specified user. |\n| App | user_id, game_id | The request returns all entitlements that the specified game granted to the specified user. |\n| App | game_id | The request returns all entitlements that the specified game granted to all entitled users. |\n| 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. |\n| User | user_id | Invalid. |\n| User | user_id, game_id | Invalid. |\n| User | game_id | The request returns all entitlements that the specified game granted to the user identified in the access token. |\n\n\n__Authorization:__\n\nRequires an [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens) or [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens). The Client ID associated with the access token must be owned by a user who is a member of the [organization](https://dev.twitch.tv/docs/docs/companies/) that holds ownership of the game.", "tags": [ "Entitlements" ], "externalDocs": { "description": "Get Drops Entitlements", "url": "https://dev.twitch.tv/docs/api/reference#get-drops-entitlements" }, "operationId": "get-drops-entitlements", "parameters": [ { "name": "id", "in": "query", "description": "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.", "schema": { "type": "array", "items": { "type": "string" } }, "explode": true }, { "name": "user_id", "in": "query", "description": "An ID that identifies a user that was granted entitlements.", "schema": { "type": "string" } }, { "name": "game_id", "in": "query", "description": "An ID that identifies a game that offered entitlements.", "schema": { "type": "string" } }, { "name": "fulfillment_status", "in": "query", "description": "The entitlement’s fulfillment status. Used to filter the list to only those with the specified status. Possible values are: \n \n* CLAIMED\n* FULFILLED", "schema": { "type": "string", "enum": [ "CLAIMED", "FULFILLED" ] } }, { "name": "after", "in": "query", "description": "The cursor used to get the next page of results. The **Pagination** object in the response contains the cursor’s value. [Read More](https://dev.twitch.tv/docs/api/guide#pagination)", "schema": { "type": "string" } }, { "name": "first", "in": "query", "description": "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.", "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "Successfully retrieved the entitlements.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetDropsEntitlementsResponse" }, "examples": { "Example": { "description": "_Request:_\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/entitlements/drops?user_id=25009227&game_id=33214' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```", "value": { "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", "last_updated": "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", "last_updated": "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", "last_updated": "2019-01-28T04:17:53.325Z" } ], "pagination": { "cursor": "eyJiIjpudW..." } } } } } } }, "400": { "description": "* The value in the _fulfillment\\_status_ query parameter is not valid.\n* The ID in the _user\\_id_ query parameter must match the user ID in the user access token.\n* The client in the access token is not associated with a known organization.\n* The owner of the client in the access token is not a member of the organization." }, "401": { "description": "* The ID in the Client-Id header must match the Client ID in the access token.\n* The Authorization header is required and must specify an app access token or user access token.\n* The access token is not valid." }, "403": { "description": "* The organization associated with the client in the access token must own the game specified in the _game\\_id_ query parameter.\n* The organization associated with the client in the access token must own the entitlements specified in the _id_ query parameter." }, "500": { "description": "" } }, "security": [ { "twitch_auth": [] } ] }, "patch": { "summary": "Updates the Drop entitlement’s fulfillment status.", "description": "Updates the Drop entitlement’s fulfillment status.\n\nThe following table identifies which entitlements are updated based on the type of access token used.\n\n| Access token type | Data that’s updated |\n| - | - |\n| App | Updates all entitlements with benefits owned by the organization in the access token. |\n| 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. |\n\n\n__Authorization:__\n\nRequires an [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens) or [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens). The Client ID associated with the access token must be owned by a user who is a member of the [organization](https://dev.twitch.tv/docs/docs/companies/) that holds ownership of the game.", "tags": [ "Entitlements" ], "externalDocs": { "description": "Update Drops Entitlements", "url": "https://dev.twitch.tv/docs/api/reference#update-drops-entitlements" }, "operationId": "update-drops-entitlements", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDropsEntitlementsBody" }, "examples": { "Example": { "value": { "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" ] } } } } } }, "responses": { "200": { "description": "Successfully requested the updates. Check the response to determine which updates succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDropsEntitlementsResponse" }, "examples": { "Example": { "description": "_Request:_\n\n```bash\ncurl -X PATCH 'https://api.twitch.tv/helix/entitlements/drops' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \\\n-H 'Content-Type: application/json' \\\n-d '{\n \"fulfillment_status\": \"FULFILLED\",\n \"entitlement_ids\": [\n \"fb78259e-fb81-4d1b-8333-34a06ffc24c0\",\n \"862750a5-265e-4ab6-9f0a-c64df3d54dd0\",\n \"d8879baa-3966-4d10-8856-15fdd62cce02\",\n \"9a290126-7e3b-4f66-a9ae-551537893b65\"\n ]\n}'\n```", "value": { "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" ] } ] } } } } } }, "400": { "description": "* The value in the `fulfillment_status` field is not valid.\n* The client in the access token is not associated with a known organization.\n* The owner of the client in the access token is not a member of the organization." }, "401": { "description": "* The Authorization header is required and must specify an app access token or user access token.\n* The access token is not valid.\n* The ID in the Client-Id header must match the Client ID in the access token." }, "500": { "description": "" } }, "security": [ { "twitch_auth": [] } ] } }, "/extensions/configurations": { "get": { "summary": "Gets the specified configuration segment from the specified extension.", "description": "Gets the specified configuration segment from the specified extension.\n\n**Rate Limits**: You may retrieve each segment a maximum of 20 times per minute.\n\n__Authorization:__\n\nRequires a signed JSON Web Token (JWT) created by an Extension Backend Service (EBS). For signing requirements, see [Signing the JWT](https://dev.twitch.tv/docs/extensions/building/#signing-the-jwt). The signed JWT must include the `role`, `user_id`, and `exp` fields (see [JWT Schema](https://dev.twitch.tv/docs/extensions/reference/#jwt-schema)). The `role` field must be set to _external_.", "tags": [ "Extensions" ], "externalDocs": { "description": "Get Extension Configuration Segment", "url": "https://dev.twitch.tv/docs/api/reference#get-extension-configuration-segment" }, "operationId": "get-extension-configuration-segment", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "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.", "schema": { "type": "string" } }, { "name": "extension_id", "in": "query", "description": "The ID of the extension that contains the configuration segment you want to get.", "schema": { "type": "string" }, "required": true }, { "name": "segment", "in": "query", "description": "The type of configuration segment to get. Possible case-sensitive values are: \n \n* broadcaster\n* developer\n* global\n \nYou 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.", "schema": { "type": "string", "enum": [ "broadcaster", "developer", "global" ] }, "required": true } ], "responses": { "200": { "description": "Successfully retrieved the configurations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetExtensionConfigurationSegmentResponse" }, "examples": { "Example 1": { "description": "The following example shows a global segment that contains a plain-text string in the `content` field.\n\n_Request:_\n\nGets the global configuration segment from the specified extension. Because the request gets the global segment, it must not include the _broadcaster\\_id_ query parameter.\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/extensions/configurations?extension_id=&segment=global' \\\n-H 'Authorization: Bearer ' \\\n-H 'Client-Id: '\n```", "value": { "data": [ { "segment": "global", "content": "hello config!", "version": "0.0.1" } ] } }, "Example 2": { "description": "The following example shows a global segment that contains a string-encoded JSON object in the `content` field.\n\n_Request:_\n\nGets the global configuration segment from the specified extension. Because the request gets the global segment, it must not include the _broadcaster\\_id_ query parameter.\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/extensions/configurations?extension_id=&segment=global' \\\n-H 'Authorization: Bearer ' \\\n-H 'Client-Id: '\n```", "value": { "data": [ { "segment": "global", "content": "{\"foo\":\"bar\"}", "version": "0.0.1" } ] } } } } } }, "400": { "description": "* The _extension\\_id_ query parameter is required.\n* The value in the _segment_ query parameter is not valid.\n* The _broadcaster\\_id_ query parameter is required if the _segment_ query parameter is set to broadcaster or developer." }, "401": { "description": "* The Authorization header is required and must specify a JWT token.\n* The JWT token is not valid.\n* The Client-Id header is required." }, "429": { "description": "* The app exceeded the number of requests that it may make per minute. See Rate Limits above." } }, "security": [ { "twitch_auth": [] } ] }, "put": { "summary": "Updates a configuration segment.", "description": "Updates a configuration segment. The segment is limited to 5 KB. Extensions that are active on a channel do not receive the updated configuration.\n\n**Rate Limits**: You may update the configuration a maximum of 20 times per minute.\n\n__Authorization:__\n\nRequires a signed JSON Web Token (JWT) created by an Extension Backend Service (EBS). For signing requirements, see [Signing the JWT](https://dev.twitch.tv/docs/extensions/building/#signing-the-jwt). The signed JWT must include the `role`, `user_id`, and `exp` fields (see [JWT Schema](https://dev.twitch.tv/docs/extensions/reference/#jwt-schema)). The `role` field must be set to _external_.", "tags": [ "Extensions" ], "externalDocs": { "description": "Set Extension Configuration Segment", "url": "https://dev.twitch.tv/docs/api/reference#set-extension-configuration-segment" }, "operationId": "set-extension-configuration-segment", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetExtensionConfigurationSegmentBody" }, "examples": { "Example": { "value": { "extension_id": "uo6dggojyb8d6soh92zknwmi5ej1q2", "segment": "global", "version": "0.0.1", "content": "hello config!" } } } } } }, "responses": { "204": { "description": "Successfully updated the configuration.\n\n__Examples__\n\n_Request:_\n\n```bash\ncurl -X PUT 'https://api.twitch.tv/helix/extensions/configurations' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \\\n-H 'Content-Type: application/json' \\\n-d '{\n \"extension_id\": \"uo6dggojyb8d6soh92zknwmi5ej1q2\",\n \"segment\": \"global\",\n \"version\": \"0.0.1\",\n \"content\": \"hello config!\"\n}'\n```" }, "400": { "description": "* The `broadcaster_id` field is required if `segment` is set to developer or broadcaster." }, "401": { "description": "* The Authorization header is required and must specify a JWT token.\n* The JWT token is not valid.\n* The Client-Id header is required." } }, "security": [ { "twitch_auth": [] } ] } }, "/extensions/required_configuration": { "put": { "summary": "Updates the extension’s required_configuration string.", "description": "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](https://dev.twitch.tv/docs/extensions/life-cycle/#capabilities)). For more information, see [Required Configurations](https://dev.twitch.tv/docs/extensions/building#required-configurations) and [Setting Required Configuration](https://dev.twitch.tv/docs/extensions/building#setting-required-configuration-with-the-configuration-service-optional).\n\n__Authorization:__\n\nRequires a signed JSON Web Token (JWT) created by an EBS. For signing requirements, see [Signing the JWT](https://dev.twitch.tv/docs/extensions/building/#signing-the-jwt). The signed JWT must include the `role`, `user_id`, and `exp` fields (see [JWT Schema](https://dev.twitch.tv/docs/extensions/reference/#jwt-schema)). Set the `role` field to _external_ and the `user_id` field to the ID of the user that owns the extension.", "tags": [ "Extensions" ], "externalDocs": { "description": "Set Extension Required Configuration", "url": "https://dev.twitch.tv/docs/api/reference#set-extension-required-configuration" }, "operationId": "set-extension-required-configuration", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster that installed the extension on their channel.", "schema": { "type": "string" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetExtensionRequiredConfigurationBody" }, "examples": { "Example": { "value": { "required_configuration": "RCS", "extension_id": "uo6dggojyb8d6soh92zknwmi5ej1q2", "extension_version": "0.0.1" } } } } } }, "responses": { "204": { "description": "Successfully updated the extension’s required\\_configuration string.\n\n__Examples__\n\n_Request:_\n\n```bash\ncurl -X PUT 'https://api.twitch.tv/helix/extensions/required_configuration?broadcaster_id=274637212' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \\\n-H 'Content-Type: application/json' \\\n-d '{\n \"required_configuration\": \"RCS\",\n \"extension_id\": \"uo6dggojyb8d6soh92zknwmi5ej1q2\",\n \"extension_version\": \"0.0.1\"\n}'\n```" }, "400": { "description": "* The _broadcaster\\_id_ query parameter is required.\n* The `extension_id` field is required.\n* The `extension_version` field is required.\n* The `required_configuration` field is required." }, "401": { "description": "* The Authorization header is required and must specify a JWT token.\n* The JWT token is not valid.\n* The Client-Id header is required." } }, "security": [ { "twitch_auth": [] } ] } }, "/extensions/pubsub": { "post": { "summary": "Sends a message to one or more viewers.", "description": "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](https://dev.twitch.tv/docs/extensions/reference#send) JavaScript helper function used to send messages.\n\n**Rate Limits**: You may send a maximum of 100 messages per minute per combination of extension client ID and broadcaster ID.\n\n__Authorization:__\n\nRequires a signed JSON Web Token (JWT) created by an Extension Backend Service (EBS). For signing requirements, see [Signing the JWT](https://dev.twitch.tv/docs/extensions/building/#signing-the-jwt). The signed JWT must include the `role`, `user_id`, and `exp` fields (see [JWT Schema](https://dev.twitch.tv/docs/extensions/reference/#jwt-schema)) along with the `channel_id` and `pubsub_perms` fields. The `role` field must be set to _external_.\n\nTo 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_.\n\n```\n{\n \"exp\": 1503343947,\n \"user_id\": \"27419011\",\n \"role\": \"external\",\n \"channel_id\": \"27419011\",\n \"pubsub_perms\": {\n \"send\":[\n \"broadcast\"\n ]\n }\n}\n\n```\n\nTo 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_.\n\n```\n{\n \"exp\": 1503343947,\n \"user_id\": \"27419011\",\n \"role\": \"external\",\n \"channel_id\": \"all\",\n \"pubsub_perms\": {\n \"send\":[\n \"global\"\n ]\n }\n}\n\n```", "tags": [ "Extensions" ], "externalDocs": { "description": "Send Extension PubSub Message", "url": "https://dev.twitch.tv/docs/api/reference#send-extension-pubsub-message" }, "operationId": "send-extension-pubsub-message", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendExtensionPubSubMessageBody" }, "examples": { "Example": { "value": { "message": "hello world!", "broadcaster_id": "141981764", "target": [ "broadcast" ] } } } } } }, "responses": { "204": { "description": "Successfully sent the message.\n\n__Examples__\n\n_Request:_\n\n```bash\ncurl -X POST 'https://api.twitch.tv/helix/extensions/pubsub' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \\\n-H 'Content-Type: application/json' \\\n-d '{\n \"message\": \"hello world!\",\n \"broadcaster_id\": \"141981764\",\n \"target\": [\"broadcast\"]\n}'\n```" }, "400": { "description": "* The `broadcaster_id` field in the request's body may only be set if the `is_global_broadcast` field is set to **false**." }, "401": { "description": "* The Authorization header is required and must specify a JWT token.\n* The JWT token is not valid.\n* The Client-Id header is required." }, "422": { "description": "* The message is too large." } }, "security": [ { "twitch_auth": [] } ] } }, "/extensions/live": { "get": { "summary": "Gets a list of broadcasters that are streaming live and have installed or activated the extension.", "description": "Gets a list of broadcasters that are streaming live and have installed or activated the extension.\n\nIt may take a few minutes for the list to include or remove broadcasters that have recently gone live or stopped broadcasting.\n\n__Authorization:__\n\nRequires an [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens) or [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens).", "tags": [ "Extensions" ], "externalDocs": { "description": "Get Extension Live Channels", "url": "https://dev.twitch.tv/docs/api/reference#get-extension-live-channels" }, "operationId": "get-extension-live-channels", "parameters": [ { "name": "extension_id", "in": "query", "description": "The ID of the extension to get. Returns the list of broadcasters that are live and that have installed or activated this extension.", "schema": { "type": "string" }, "required": true }, { "name": "first", "in": "query", "description": "The specific maximum number of items per page in the response. The actual number returned may be less than this limit. [Read More](https://dev.twitch.tv/docs/api/guide#pagination)", "schema": { "type": "integer", "format": "int32" } }, { "name": "after", "in": "query", "description": "The cursor used to get the next page of results. The `pagination` field in the response contains the cursor’s value. [Read More](https://dev.twitch.tv/docs/api/guide#pagination)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the list of broadcasters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetExtensionLiveChannelsResponse" }, "examples": { "Example": { "description": "_Request:_\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/extensions/live?extension_id=uo6dggojyb8d6soh92zknwmi5ej1q2' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```", "value": { "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" } } } } } }, "400": { "description": "* The _extension\\_id_ query parameter is required.\n* The pagination cursor is not valid." }, "401": { "description": "* The Authorization header is required and must specify an app access token or user access token.\n* The access token is not valid.\n* The ID in the Client-Id header must match the client ID in the access token." }, "404": { "description": "* The extension specified in the _extension\\_id_ query parameter was not found or it's not being used in a live stream." } }, "security": [ { "twitch_auth": [] } ] } }, "/extensions/jwt/secrets": { "get": { "summary": "Gets an extension’s list of shared secrets.", "description": "Gets an extension’s list of shared secrets.\n\n__Authorization:__\n\nRequires a signed JSON Web Token (JWT) created by an Extension Backend Service (EBS). For signing requirements, see [Signing the JWT](https://dev.twitch.tv/docs/extensions/building/#signing-the-jwt). The signed JWT must include the `role`, `user_id`, and `exp` fields (see [JWT Schema](https://dev.twitch.tv/docs/extensions/reference/#jwt-schema)). The `role` field must be set to _external_.", "tags": [ "Extensions" ], "externalDocs": { "description": "Get Extension Secrets", "url": "https://dev.twitch.tv/docs/api/reference#get-extension-secrets" }, "operationId": "get-extension-secrets", "responses": { "200": { "description": "Successfully retrieved the list of secrets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetExtensionSecretsResponse" }, "examples": { "Example": { "description": "_Request:_\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/extensions/jwt/secrets?extension_id=uo6dggojyb8d6soh92zknwmi5ej1q2' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```", "value": { "data": [ { "format_version": 1, "secrets": [ { "content": "secret", "active_at": "2021-03-29T06:58:40.858343036Z", "expires_at": "2121-03-05T06:58:40.858343036Z" } ] } ] } } } } } }, "400": { "description": "* The _extension\\_id_ query parameter is required." }, "401": { "description": "* The Authorization header is required and must specify a JWT token.\n* The JWT token is not valid.\n* The Client-Id header is required." } }, "security": [ { "twitch_auth": [] } ] }, "post": { "summary": "Creates a shared secret used to sign and verify JWT tokens.", "description": "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.\n\n__Authorization:__\n\nRequires a signed JSON Web Token (JWT) created by an Extension Backend Service (EBS). For signing requirements, see [Signing the JWT](https://dev.twitch.tv/docs/extensions/building/#signing-the-jwt). The signed JWT must include the `role`, `user_id`, and `exp` fields (see [JWT Schema](https://dev.twitch.tv/docs/extensions/reference/#jwt-schema)). The `role` field must be set to _external_.", "tags": [ "Extensions" ], "externalDocs": { "description": "Create Extension Secret", "url": "https://dev.twitch.tv/docs/api/reference#create-extension-secret" }, "operationId": "create-extension-secret", "parameters": [ { "name": "extension_id", "in": "query", "description": "The ID of the extension to apply the shared secret to.", "schema": { "type": "string" }, "required": true }, { "name": "delay", "in": "query", "description": "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.", "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "Successfully created the new secret.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateExtensionSecretResponse" }, "examples": { "Example": { "description": "_Request:_\n\n```bash\ncurl -X POST 'https://api.twitch.tv/helix/extensions/jwt/secrets?extension_id=uo6dggojyb8d6soh92zknwmi5ej1q2&delay=600' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```", "value": { "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" } ] } ] } } } } } }, "400": { "description": "* The _extension\\_id_ query parameter is required.\n* The delay specified in the _delay_ query parameter is too short." }, "401": { "description": "* The Authorization header is required and must specify a JWT token.\n* The JWT token is not valid.\n* The Client-Id header is required." } }, "security": [ { "twitch_auth": [] } ] } }, "/extensions/chat": { "post": { "summary": "Sends a message to the specified broadcaster’s chat room.", "description": "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).\n\n**Rate Limits**: You may send a maximum of 12 messages per minute per channel.\n\n__Authorization:__\n\nRequires a signed JSON Web Token (JWT) created by an Extension Backend Service (EBS). For signing requirements, see [Signing the JWT](https://dev.twitch.tv/docs/extensions/building/#signing-the-jwt). The signed JWT must include the `role` and `user_id` fields (see [JWT Schema](https://dev.twitch.tv/docs/extensions/reference/#jwt-schema)). The `role` field must be set to _external_.", "tags": [ "Extensions" ], "externalDocs": { "description": "Send Extension Chat Message", "url": "https://dev.twitch.tv/docs/api/reference#send-extension-chat-message" }, "operationId": "send-extension-chat-message", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster that has activated the extension.", "schema": { "type": "string" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendExtensionChatMessageBody" } } } }, "responses": { "204": { "description": "Successfully sent the chat message.\n\n__Examples__\n\n_Request:_\n\n```bash\ncurl -X POST 'https://api.twitch.tv/helix/extensions/chat?broadcaster_id=237757755' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \\\n-H 'Content-Type: application/json' \\\n-d '{\n \"text\": \"Hello\",\n \"extension_id\": \"uo6dggojyb8d6soh92zknwmi5ej1q2\",\n \"extension_version\": \"0.0.9\"\n}\n```" }, "400": { "description": "* The _broadcaster\\_id_ query parameter is required.\n* The `extension_id` field in the request's body is required.\n* The `extension_version` field in the request's body is required.\n* The `text` field in the request's body is required.\n* The message is too long." }, "401": { "description": "* The Authorization header is required and must specify a JWT token.\n* The ID in the _broadcaster\\_id_ query parameter must match the `channel_id` claim in the JWT.\n* The JWT token is not valid.\n* The Client-Id header is required." } }, "security": [ { "twitch_auth": [] } ] } }, "/extensions": { "get": { "summary": "Gets information about an extension.", "description": "Gets information about an extension.\n\n__Authorization:__\n\nRequires a signed JSON Web Token (JWT) created by an Extension Backend Service (EBS). For signing requirements, see [Signing the JWT](https://dev.twitch.tv/docs/extensions/building/#signing-the-jwt). The signed JWT must include the `role` field (see [JWT Schema](https://dev.twitch.tv/docs/extensions/reference/#jwt-schema)), and the `role` field must be set to _external_.", "tags": [ "Extensions" ], "externalDocs": { "description": "Get Extensions", "url": "https://dev.twitch.tv/docs/api/reference#get-extensions" }, "operationId": "get-extensions", "parameters": [ { "name": "extension_id", "in": "query", "description": "The ID of the extension to get.", "schema": { "type": "string" }, "required": true }, { "name": "extension_version", "in": "query", "description": "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.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the list of extensions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetExtensionsResponse" }, "examples": { "Example": { "description": "_Request:_\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/extensions?extension_id=uo6dggojyb8d6soh92zknwmi5ej1q2&extension_version=0.0.9' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```", "value": { "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": [] } ] } } } } } }, "400": { "description": "* The _extension\\_id_ query parameter is required." }, "401": { "description": "* The request must specify the Authorization header.\n* The Authorization header is required and must specify a JWT token.\n* The JWT token is not valid.\n* The request must specify the Client-Id header." }, "404": { "description": "* The extension in the _extension\\_id_ query parameter was not found." } }, "security": [ { "twitch_auth": [] } ] } }, "/extensions/released": { "get": { "summary": "Gets information about a released extension.", "description": "Gets information about a released extension. Returns the extension if its `state` is Released.\n\n__Authorization:__\n\nRequires an [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens) or [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens).", "tags": [ "Extensions" ], "externalDocs": { "description": "Get Released Extensions", "url": "https://dev.twitch.tv/docs/api/reference#get-released-extensions" }, "operationId": "get-released-extensions", "parameters": [ { "name": "extension_id", "in": "query", "description": "The ID of the extension to get.", "schema": { "type": "string" }, "required": true }, { "name": "extension_version", "in": "query", "description": "The version of the extension to get. If not specified, it returns the latest version.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the extension.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetReleasedExtensionsResponse" }, "examples": { "Example": { "description": "_Request:_\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/extensions/released?extension_version=0.0.9&extension_id=uo6dggojyb8d6soh92zknwmi5ej1q2' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```", "value": { "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": [] } ] } } } } } }, "400": { "description": "* The _extension\\_id_ query parameter is required." }, "401": { "description": "* The Authorization header must specify an app access token or user access token.\n* The access token is not valid.\n* The ID in the Client-Id header must match the client ID in the access token." }, "404": { "description": "* The extension specified in the _extension\\_id_ query parameter was not found or is not released." } }, "security": [ { "twitch_auth": [] } ] } }, "/bits/extensions": { "get": { "summary": "Gets the list of Bits products that belongs to the extension.", "description": "Gets the list of Bits products that belongs to the extension. The client ID in the app access token identifies the extension.\n\n__Authorization:__\n\nRequires an [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens). The client ID in the app access token must be the extension’s client ID.", "tags": [ "Extensions" ], "externalDocs": { "description": "Get Extension Bits Products", "url": "https://dev.twitch.tv/docs/api/reference#get-extension-bits-products" }, "operationId": "get-extension-bits-products", "parameters": [ { "name": "should_include_all", "in": "query", "description": "A Boolean value that determines whether to include disabled or expired Bits products in the response. The default is **false**.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Successfully retrieved the list of products.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetExtensionBitsProductsResponse" }, "examples": { "Example": { "description": "_Request:_\n\nGets the extension’s products including its disabled and expired products.\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/bits/extensions?should_include_all=true' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```", "value": { "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 } ] } } } } } }, "400": { "description": "* The ID in the Client-Id header must belong to an extension." }, "401": { "description": "* The Authorization header is required and must specify an app access token; you may not specify a user access token.\n* The OAuth token is not valid.\n* The ID in the Client-Id header must match the Client ID in the OAuth token." } }, "security": [ { "twitch_auth": [] } ] }, "put": { "summary": "Adds or updates a Bits product that the extension created.", "description": "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.\n\n__Authorization:__\n\nRequires an [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens). The client ID in the app access token must match the extension’s client ID.", "tags": [ "Extensions" ], "externalDocs": { "description": "Update Extension Bits Product", "url": "https://dev.twitch.tv/docs/api/reference#update-extension-bits-product" }, "operationId": "update-extension-bits-product", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateExtensionBitsProductBody" } } } }, "responses": { "200": { "description": "Successfully created the product.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateExtensionBitsProductResponse" }, "examples": { "Example": { "description": "_Request:_\n\n```bash\ncurl -X PUT 'https://api.twitch.tv/helix/bits/extensions' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \\\n-H 'Content-Type: application/json' \\\n-d {\n \"sku\": \"1010\",\n \"cost\": {\n \"amount\": 990,\n \"type\": \"bits\"\n },\n \"in_development\": true,\n \"display_name\": \"Rusty Crate 2\",\n \"is_broadcast\": true,\n \"expiration\": \"2021-05-18T09:10:13.397Z\"\n}\n```", "value": { "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 } ] } } } } } }, "400": { "description": "* The `sku` field is required.\n* The value in the `sku` field is not valid. The SKU may contain only alphanumeric characters, dashes (-), underscores (\\_), and periods (.).\n* The `cost` object's `amount` field is required.\n* The value in the `cost` object's `amount` field is not valid.\n* The `cost` object's `type` field is required.\n* The value in the `cost` object's `type` field is not valid.\n* The `display_name` field is required.\n* The ID in the Client-Id header must belong to the extension." }, "401": { "description": "* The Authorization header is required and must specify an app access token; you may not specify a user access token.\n* The OAuth token is not valid.\n* The ID in the Client-Id header must match the Client ID in the OAuth token." } }, "security": [ { "twitch_auth": [] } ] } }, "/eventsub/subscriptions": { "post": { "summary": "Creates an EventSub subscription.", "description": "Creates an EventSub subscription.\n\n__Authorization:__\n\nIf you use [webhooks to receive events](https://dev.twitch.tv/docs/eventsub/handling-webhook-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](https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types/#channelsubscribe) 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.\n\nIf you use [WebSockets to receive events](https://dev.twitch.tv/docs/eventsub/handling-websocket-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.\n\nIf you use [Conduits](https://dev.twitch.tv/docs/eventsub/handling-conduit-events/) to receive events, the request must specify an app access token. The request will fail if you use a user access token.", "tags": [ "EventSub" ], "externalDocs": { "description": "Create EventSub Subscription", "url": "https://dev.twitch.tv/docs/api/reference#create-eventsub-subscription" }, "operationId": "create-eventsub-subscription", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEventSubSubscriptionBody" }, "examples": { "Example 1": { "value": { "type": "user.update", "version": "1", "condition": { "user_id": "1234" }, "transport": { "method": "webhook", "callback": "https://this-is-a-callback.com", "secret": "s3cre7" } }, "description": "For a **webhook** `method` type. Adds a user.update subscription." }, "Example 2": { "value": { "type": "user.update", "version": "1", "condition": { "user_id": "1234" }, "transport": { "method": "websocket", "session_id": "AQoQexAWVYKSTIu4ec_2VAxyuhAB" } }, "description": "For a **websocket** `method` type." } } } } }, "responses": { "202": { "description": "Successfully accepted the subscription request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEventSubSubscriptionResponse" }, "examples": { "Example 1": { "description": "_Request:_\n\nFor a **webhook** `method` type. Adds a user.update subscription.\n\n```bash\ncurl -X POST 'https://api.twitch.tv/helix/eventsub/subscriptions' \\\n-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \\\n-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz' \\\n-H 'Content-Type: application/json' \\\n-d '{\n \"type\": \"user.update\",\n \"version\": \"1\",\n \"condition\": {\n \"user_id\": \"1234\"\n },\n \"transport\": {\n \"method\": \"webhook\",\n \"callback\": \"https://this-is-a-callback.com\",\n \"secret\":\"s3cre7\"\n }\n}'\n```\n\n```bash\n# Twitch CLI example that adds a user.update subscription.\n\ntwitch 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 - Webhook\n```", "value": { "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 } }, "Example 2": { "description": "_Request:_\n\nFor a **websocket** `method` type.\n\n```bash\ncurl -X POST 'https://api.twitch.tv/helix/eventsub/subscriptions' \\\n-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \\\n-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz' \\\n-H 'Content-Type: application/json' \\\n-d '{\n \"type\": \"user.update\",\n \"version\": \"1\",\n \"condition\": {\n \"user_id\": \"1234\"\n },\n \"transport\": {\n \"method\": \"websocket\",\n \"session_id\": \"AQoQexAWVYKSTIu4ec_2VAxyuhAB\"\n }\n}'\n```", "value": { "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 } }, "Example 3": { "description": "_Request:_\n\nFor a **conduit** `method` type.\n\n```text\nExample RequestExample Requestcurl -X POST 'https://api.twitch.tv/helix/eventsub/subscriptions' \\\n-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \\\n-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz' \\\n-H 'Content-Type: application/json' \\\n-d '{\n \"type\":\"user.update\",\n \"version\":\"1\",\n \"condition\":{\n \"user_id\":\"1234\"\n },\n \"transport\":{\n \"method\":\"conduit\",\n \"conduit_id\":\"bfcfc993-26b1-b876-44d9-afe75a379dac\"\n }\n}'\n```", "value": { "data": [ { "id": "26b1c993-bfcf-44d9-b876-379dacafe75a", "status": "enabled", "type": "user.update", "version": "1", "condition": { "user_id": "1234" }, "created_at": "2020-11-10T14:32:18.730260295Z", "transport": { "method": "conduit", "conduit_id": "bfcfc993-26b1-b876-44d9-afe75a379dac" }, "cost": 1 } ], "total": 1, "total_cost": 1, "max_total_cost": 10000 } } } } } }, "400": { "description": "* The `condition` field is required.\n* The user specified in the `condition` object does not exist.\n* The `condition` object is missing one or more required fields.\n* The combination of values in the `version` and `type` fields is not valid.\n* The length of the string in the `secret` field is not valid.\n* The URL in the transport's `callback` field is not valid. The URL must use the HTTPS protocol and the 443 port number.\n* The value specified in the `method` field is not valid.\n* The `callback` field is required if you specify the webhook transport method.\n* The `session_id` field is required if you specify the WebSocket transport method.\n* The combination of subscription type and version is not valid.\n* The `conduit_id` field is required if you specify the Conduit transport method." }, "401": { "description": "* The Authorization header is required and must specify an app access token if the transport method is webhook.\n* The Authorization header is required and must specify a user access token if the transport method is WebSocket.\n* The access token is not valid.\n* The ID in the Client-Id header must match the client ID in the access token." }, "403": { "description": "The access token is missing the required scopes." }, "409": { "description": "A subscription already exists for the specified event type and `condition` combination." }, "429": { "description": "The request exceeds the number of subscriptions that you may create with the same combination of `type` and `condition` values." } }, "security": [ { "twitch_auth": [ "channel:read:subscriptions" ] } ] }, "delete": { "summary": "Deletes an EventSub subscription.", "description": "Deletes an EventSub subscription.\n\n__Authorization:__\n\nIf you use [webhooks to receive events](https://dev.twitch.tv/docs/eventsub/handling-webhook-events), the request must specify an app access token. The request will fail if you use a user access token.\n\nIf you use [WebSockets to receive events](https://dev.twitch.tv/docs/eventsub/handling-websocket-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.", "tags": [ "EventSub" ], "externalDocs": { "description": "Delete EventSub Subscription", "url": "https://dev.twitch.tv/docs/api/reference#delete-eventsub-subscription" }, "operationId": "delete-eventsub-subscription", "parameters": [ { "name": "id", "in": "query", "description": "The ID of the subscription to delete.", "schema": { "type": "string" }, "required": true } ], "responses": { "204": { "description": "Successfully deleted the subscription.\n\n__Examples__\n\n_Request:_\n\nDeletes the specified EventSub subscription.\n\n```bash\ncurl -X DELETE\n'https://api.twitch.tv/helix/eventsub/subscriptions?id=26b1c993-bfcf-44d9-b876-379dacafe75a' \\\n-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \\\n-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'\n```\n\n```bash\n# Twitch CLI example that deletes the specified subscription.\n\ntwitch api delete /eventsub/subscriptions -q id=c839a466-034a-4d77-8d4d-c9a751516e7\n```" }, "400": { "description": "* The _id_ query parameter is required." }, "401": { "description": "* The Authorization header is required and must specify an app access token.\n* The access token is not valid.\n* The ID in the Client-Id header must match the client ID in the access token." }, "404": { "description": "* The subscription was not found." } }, "security": [ { "twitch_auth": [] } ] }, "get": { "summary": "Gets a list of EventSub subscriptions that the client in the access token created.", "description": "Gets a list of EventSub subscriptions that the client in the access token created.\n\n__Authorization:__\n\nIf you use [Webhooks](https://dev.twitch.tv/docs/eventsub/handling-webhook-events) or [Conduits](https://dev.twitch.tv/docs/eventsub/handling-conduit-events/) to receive events, the request must specify an app access token. The request will fail if you use a user access token.\n\nIf you use [WebSockets to receive events](https://dev.twitch.tv/docs/eventsub/handling-websocket-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.\n\n__Request Query Parameters:__\n\nUse the _status_, _type_, _user\\_id_, and _subscription\\_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.", "tags": [ "EventSub" ], "externalDocs": { "description": "Get EventSub Subscriptions", "url": "https://dev.twitch.tv/docs/api/reference#get-eventsub-subscriptions" }, "operationId": "get-eventsub-subscriptions", "parameters": [ { "name": "status", "in": "query", "description": "Filter subscriptions by its status. Possible values are: \n \n* enabled — The subscription is enabled.\n* webhook\\_callback\\_verification\\_pending — The subscription is pending verification of the specified callback URL.\n* webhook\\_callback\\_verification\\_failed — The specified callback URL failed verification.\n* notification\\_failures\\_exceeded — The notification delivery failure rate was too high.\n* authorization\\_revoked — The authorization was revoked for one or more users specified in the **Condition** object.\n* moderator\\_removed — The moderator that authorized the subscription is no longer one of the broadcaster's moderators.\n* user\\_removed — One of the users specified in the **Condition** object was removed.\n* chat\\_user\\_banned - The user specified in the **Condition** object was banned from the broadcaster's chat.\n* version\\_removed — The subscription to subscription type and version is no longer supported.\n* beta\\_maintenance — The subscription to the beta subscription type was removed due to maintenance.\n* websocket\\_disconnected — The client closed the connection.\n* websocket\\_failed\\_ping\\_pong — The client failed to respond to a ping message.\n* websocket\\_received\\_inbound\\_traffic — The client sent a non-pong message. Clients may only send pong messages (and only in response to a ping message).\n* websocket\\_connection\\_unused — The client failed to subscribe to events within the required time.\n* websocket\\_internal\\_error — The Twitch WebSocket server experienced an unexpected error.\n* websocket\\_network\\_timeout — The Twitch WebSocket server timed out writing the message to the client.\n* websocket\\_network\\_error — The Twitch WebSocket server experienced a network error writing the message to the client.\n* websocket\\_failed\\_to\\_reconnect - The client failed to reconnect to the Twitch WebSocket server within the required time after a Reconnect Message.", "schema": { "type": "string", "enum": [ "enabled", "webhook_callback_verification_pending", "webhook_callback_verification_failed", "notification_failures_exceeded", "authorization_revoked", "moderator_removed", "user_removed", "chat_user_banned", "version_removed", "beta_maintenance", "websocket_disconnected", "websocket_failed_ping_pong", "websocket_received_inbound_traffic", "websocket_connection_unused", "websocket_internal_error", "websocket_network_timeout", "websocket_network_error", "websocket_failed_to_reconnect" ] } }, { "name": "type", "in": "query", "description": "Filter subscriptions by subscription type. For a list of subscription types, see [Subscription Types](https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#subscription-types).", "schema": { "type": "string", "enum": [ "automod.message.hold", "automod.message.update", "automod.settings.update", "automod.terms.update", "channel.bits.use", "channel.update", "channel.follow", "channel.ad_break.begin", "channel.chat.clear", "channel.chat.clear_user_messages", "channel.chat.message", "channel.chat.message_delete", "channel.chat.notification", "channel.chat_settings.update", "channel.chat.user_message_hold", "channel.chat.user_message_update", "channel.shared_chat.begin", "channel.shared_chat.update", "channel.shared_chat.end", "channel.subscribe", "channel.subscription.end", "channel.subscription.gift", "channel.subscription.message", "channel.cheer", "channel.raid", "channel.ban", "channel.unban", "channel.unban_request.create", "channel.unban_request.resolve", "channel.moderate", "channel.moderator.add", "channel.moderator.remove", "channel.guest_star_session.begin", "channel.guest_star_session.end", "channel.guest_star_guest.update", "channel.guest_star_settings.update", "channel.channel_points_automatic_reward_redemption.add", "channel.channel_points_custom_reward.add", "channel.channel_points_custom_reward.update", "channel.channel_points_custom_reward.remove", "channel.channel_points_custom_reward_redemption.add", "channel.channel_points_custom_reward_redemption.update", "channel.poll.begin", "channel.poll.progress", "channel.poll.end", "channel.prediction.begin", "channel.prediction.progress", "channel.prediction.lock", "channel.prediction.end", "channel.suspicious_user.message", "channel.suspicious_user.update", "channel.vip.add", "channel.vip.remove", "channel.warning.acknowledge", "channel.warning.send", "channel.charity_campaign.donate", "channel.charity_campaign.start", "channel.charity_campaign.progress", "channel.charity_campaign.stop", "conduit.shard.disabled", "drop.entitlement.grant", "extension.bits_transaction.create", "channel.goal.begin", "channel.goal.progress", "channel.goal.end", "channel.hype_train.begin", "channel.hype_train.progress", "channel.hype_train.end", "channel.shield_mode.begin", "channel.shield_mode.end", "channel.shoutout.create", "channel.shoutout.receive", "stream.online", "stream.offline", "user.authorization.grant", "user.authorization.revoke", "user.update", "user.whisper.message" ] } }, { "name": "user_id", "in": "query", "description": "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](https://dev.twitch.tv/docs/api/reference#create-eventsub-subscription).", "schema": { "type": "string" } }, { "name": "subscription_id", "in": "query", "description": "Returns an array with the subscription matching the ID (as long as it is owned by the client making the request), or an empty array if there is no matching subscription.", "schema": { "type": "string" } }, { "name": "after", "in": "query", "description": "The cursor used to get the next page of results. The `pagination` object in the response contains the cursor's value.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the subscriptions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetEventSubSubscriptionsResponse" }, "examples": { "Example": { "description": "_Request:_\n\nGets a list of EventSub subscriptions that you created. The list is ordered by the oldest subscription first.\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/eventsub/subscriptions' \\\n-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \\\n-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'\n```\n\n```bash\n# Twitch CLI example that gets a list of EventSub subscriptions that you created.\n\ntwitch api get /eventsub/subscriptions\n```", "value": { "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": {} } } } } } }, "400": { "description": "* The request may specify only one filter query parameter. For example, either _type_ or _status_ or _user\\_id_.\n* The value in the _type_ query parameter is not valid.\n* The value in the _status_ query parameter is not valid.\n* The cursor specified in the _after_ query parameter is not valid." }, "401": { "description": "* The Authorization header is required and must specify an app access token.\n* The access token is not valid.\n* The ID in the Client-Id header must match the client ID in the access token." } }, "security": [ { "twitch_auth": [] } ] } }, "/games/top": { "get": { "summary": "Gets information about all broadcasts on Twitch.", "description": "Gets information about all broadcasts on Twitch.\n\n__Authorization:__\n\nRequires an [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens) or [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens).", "tags": [ "Games" ], "externalDocs": { "description": "Get Top Games", "url": "https://dev.twitch.tv/docs/api/reference#get-top-games" }, "operationId": "get-top-games", "parameters": [ { "name": "first", "in": "query", "description": "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.", "schema": { "type": "integer", "format": "int32" } }, { "name": "after", "in": "query", "description": "The cursor used to get the next page of results. The **Pagination** object in the response contains the cursor’s value. [Read More](https://dev.twitch.tv/docs/api/guide#pagination)", "schema": { "type": "string" } }, { "name": "before", "in": "query", "description": "The cursor used to get the previous page of results. The **Pagination** object in the response contains the cursor’s value. [Read More](https://dev.twitch.tv/docs/api/guide#pagination)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the list of broadcasts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetTopGamesResponse" }, "examples": { "Example": { "description": "_Request:_\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/games/top' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```", "value": { "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==" } } } } } } }, "400": { "description": "* The value in the _first_ query parameter is not valid.\n* The cursor in the _after_ or _before_ query parameter is not valid." }, "401": { "description": "* The Authorization header is required and must specify an app access token or user access token.\n* The access token is not valid.\n* The ID in the Client-Id header must match the client ID in the access token." } }, "security": [ { "twitch_auth": [] } ] } }, "/games": { "get": { "summary": "Gets information about specified games.", "description": "Gets information about specified categories or games.\n\nYou 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.\n\n__Authorization:__\n\nRequires an [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens) or [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens).", "tags": [ "Games" ], "externalDocs": { "description": "Get Games", "url": "https://dev.twitch.tv/docs/api/reference#get-games" }, "operationId": "get-games", "parameters": [ { "name": "id", "in": "query", "description": "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.", "schema": { "type": "array", "items": { "type": "string" } }, "explode": true }, { "name": "name", "in": "query", "description": "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.", "schema": { "type": "array", "items": { "type": "string" } }, "explode": true }, { "name": "igdb_id", "in": "query", "description": "The [IGDB](https://www.igdb.com/) 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.", "schema": { "type": "array", "items": { "type": "string" } }, "explode": true } ], "responses": { "200": { "description": "Successfully retrieved the specified games.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetGamesResponse" }, "examples": { "Example": { "description": "_Request:_\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/games?id=33214' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```", "value": { "data": [ { "id": "33214", "name": "Fortnite", "box_art_url": "https://static-cdn.jtvnw.net/ttv-boxart/33214-{width}x{height}.jpg", "igdb_id": "1905" } ] } } } } } }, "400": { "description": "* The request must specify the _id_ or _name_ or _igdb\\_id_ query parameter.\n* The combined number of game IDs (_id_ and _igdb\\_id_) and game names that you specify in the request must not exceed 100." }, "401": { "description": "* The Authorization header is required and must specify an app access token or user access token.\n* The access token is not valid.\n* The ID in the Client-Id header must match the client ID in the access token." } }, "security": [ { "twitch_auth": [] } ] } }, "/goals": { "get": { "summary": "Gets the broadcaster’s list of active goals.", "description": "Gets the broadcaster’s list of active goals. Use this endpoint to get the current progress of each goal.\n\nInstead of polling for the progress of a goal, consider [subscribing](https://dev.twitch.tv/docs/eventsub/manage-subscriptions) to receive notifications when a goal makes progress using the [channel.goal.progress](https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelgoalprogress) subscription type. [Read More](https://dev.twitch.tv/docs/api/goals#requesting-event-notifications)\n\n__Authorization:__\n\nRequires a [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **channel:read:goals** scope.", "tags": [ "Goals" ], "externalDocs": { "description": "Get Creator Goals", "url": "https://dev.twitch.tv/docs/api/reference#get-creator-goals" }, "operationId": "get-creator-goals", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster that created the goals. This ID must match the user ID in the user access token.", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Successfully retrieved the broadcaster’s goals.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetCreatorGoalsResponse" }, "examples": { "Example": { "description": "_Request:_\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/goals?broadcaster_id=141981764' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```\n\n```bash\n# Twitch CLI example that gets the broadcaster's goals.\n\ntwitch api get /goals -q broadcaster_id=141981764\n```", "value": { "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" } ] } } } } } }, "400": { "description": "* The _broadcaster\\_id_ query parameter is required." }, "401": { "description": "* The Authorization header is required and must contain a user access token.\n* The user access token must include the **channel:read:goals** scope.\n* The ID in _broadcaster\\_id_ must match the user ID in the user access token.\n* The access token is not valid.\n* The client ID specified in the Client-Id header does not match the client ID specified in the access token." } }, "security": [ { "twitch_auth": [ "channel:read:goals" ] } ] } }, "/guest_star/channel_settings": { "get": { "summary": "BETA Gets the channel settings for configuration of the Guest Star feature for a particular host.", "description": "BETA Gets the channel settings for configuration of the Guest Star feature for a particular host.\n\n__Authorization:__\n\n* Query parameter `moderator_id` must match the `user_id` in the [User-Access token](https://dev.twitch.tv/docs/authentication#user-access-tokens)\n* Requires OAuth Scope: `channel:read:guest_star`, `channel:manage:guest_star`, `moderator:read:guest_star` or `moderator:manage:guest_star`", "tags": [ "Guest Star" ], "externalDocs": { "description": "Get Channel Guest Star Settings", "url": "https://dev.twitch.tv/docs/api/reference#get-channel-guest-star-settings" }, "operationId": "get-channel-guest-star-settings", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster you want to get guest star settings for.", "schema": { "type": "string" }, "required": true }, { "name": "moderator_id", "in": "query", "description": "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.", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetChannelGuestStarSettingsResponse" }, "examples": { "Example": { "description": "_Request:_\n\n```bash\ncurl -x GET `https://api.twitch.tv/helix/guest_star/channel_settings?broadcaster_id=9321049&moderator_id=9321049` \\\n\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```", "value": { "data": [ { "is_moderator_send_live_enabled": true, "slot_count": 4, "is_browser_source_audio_enabled": true, "layout": "TILED_LAYOUT", "browser_source_token": "eihq8rew7q3hgierufhi3q" } ] } } } } } }, "400": { "description": "* Missing _broadcaster\\_id_\n* Missing _moderator\\_id_" }, "403": { "description": "Insufficient authorization for viewing channel’s Guest Star settings" } } }, "put": { "summary": "BETA Mutates the channel settings for configuration of the Guest Star feature for a particular host.", "description": "BETA Mutates the channel settings for configuration of the Guest Star feature for a particular host.\n\n__Authorization:__\n\n* Query parameter `broadcaster_id` must match the `user_id` in the [User-Access token](https://dev.twitch.tv/docs/authentication#user-access-tokens)\n* Requires OAuth Scope: `channel:manage:guest_star`", "tags": [ "Guest Star" ], "externalDocs": { "description": "Update Channel Guest Star Settings", "url": "https://dev.twitch.tv/docs/api/reference#update-channel-guest-star-settings" }, "operationId": "update-channel-guest-star-settings", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster you want to update Guest Star settings for.", "schema": { "type": "string" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateChannelGuestStarSettingsBody" } } } }, "responses": { "204": { "description": "Successfully updated channel settings\n\n__Examples__\n\n_Request:_\n\nUpdate browser source layout settings\n\n```bash\ncurl -x PUT `https://api.twitch.tv/helix/guest_star/channel_settings?broadcaster_id=9321049&group_layout=TILED_LAYOUT` \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```\n\n_Request:_\n\nDisable moderator control of slot live setting\n\n```bash\ncurl -x PUT `https://api.twitch.tv/helix/guest_star/channel_settings?broadcaster_id=9321049&is_moderator_send_live_enabled=false` \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```\n\n_Request:_\n\nUpdate max slot count\n\n```bash\ncurl -x PUT `https://api.twitch.tv/helix/guest_star/channel_settings?broadcaster_id=9321049&slot_count=6` \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```\n\n_Request:_\n\nRegenerate browser sources\n\n```bash\ncurl -x PUT `https://api.twitch.tv/helix/guest_star/channel_settings?broadcaster_id=9321049®enerate_browser_sources=true` \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```" }, "400": { "description": "* Missing _broadcaster\\_id_\n* Invalid _slot\\_count_\n* Invalid _group\\_layout_" } } } }, "/guest_star/session": { "get": { "summary": "BETA Gets information about an ongoing Guest Star session for a particular channel.", "description": "BETA Gets information about an ongoing Guest Star session for a particular channel.\n\n__Authorization:__\n\n* Requires OAuth Scope: `channel:read:guest_star`, `channel:manage:guest_star`, `moderator:read:guest_star` or `moderator:manage:guest_star`\n* Guests must be either invited or assigned a slot within the session", "tags": [ "Guest Star" ], "externalDocs": { "description": "Get Guest Star Session", "url": "https://dev.twitch.tv/docs/api/reference#get-guest-star-session" }, "operationId": "get-guest-star-session", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "ID for the user hosting the Guest Star session.", "schema": { "type": "string" }, "required": true }, { "name": "moderator_id", "in": "query", "description": "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.", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetGuestStarSessionResponse" }, "examples": { "Example": { "description": "_Request:_\n\nGet session for host channel\n\n```bash\ncurl -x GET `https://api.twitch.tv/helix/guest_star/session?broadcaster_id=9321049&moderator_id=9321049` \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```", "value": { "data": [ { "id": "2KFRQbFtpmfyD3IevNRnCzOPRJI", "guests": [ { "slot_id": "0", "user_id": "9321049", "user_display_name": "Cool_User", "user_login": "cool_user", "is_live": true, "volume": 100, "assigned_at": "2023-01-02T04:16:53.325Z", "audio_settings": { "is_available": true, "is_host_enabled": true, "is_guest_enabled": true }, "video_settings": { "is_available": true, "is_host_enabled": true, "is_guest_enabled": true } }, { "slot_id": "1", "user_id": "144601104", "user_display_name": "Cool_Guest", "user_login": "cool_guest", "is_live": true, "volume": 100, "assigned_at": "2023-01-02T04:20:59.325Z", "audio_settings": { "is_available": true, "is_host_enabled": true, "is_guest_enabled": true }, "video_settings": { "is_available": true, "is_host_enabled": true, "is_guest_enabled": true } } ] } ] } } } } } }, "400": { "description": "* Missing _broadcaster\\_id_\n* Missing _moderator\\_id_" }, "401": { "description": "_moderator\\_id_ and user token do not match" } } }, "post": { "summary": "BETA Programmatically creates a Guest Star session on behalf of the broadcaster.", "description": "BETA Programmatically creates a Guest Star session on behalf of the broadcaster. Requires the broadcaster to be present in the call interface, or the call will be ended automatically.\n\n__Authorization:__\n\n* Query parameter `broadcaster_id` must match the `user_id` in the [User-Access token](https://dev.twitch.tv/docs/authentication#user-access-tokens)\n* Requires OAuth Scope: `channel:manage:guest_star`", "tags": [ "Guest Star" ], "externalDocs": { "description": "Create Guest Star Session", "url": "https://dev.twitch.tv/docs/api/reference#create-guest-star-session" }, "operationId": "create-guest-star-session", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster you want to create a Guest Star session for. Provided `broadcaster_id` must match the `user_id` in the auth token.", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateGuestStarSessionResponse" }, "examples": { "Example": { "description": "_Request:_\n\nStart Guest Star session\n\n```bash\ncurl -x POST `https://api.twitch.tv/helix/guest_star/session?broadcaster_id=9321049` \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```", "value": { "data": [ { "id": "2KFRQbFtpmfyD3IevNRnCzOPRJI", "guests": [ { "id": "0", "user_id": "9321049", "user_display_name": "Cool_User", "user_login": "cool_user", "is_live": true, "volume": 100, "assigned_at": "2023-01-02T04:16:53.325Z", "audio_settings": { "is_available": true, "is_host_enabled": true, "is_guest_enabled": true }, "video_settings": { "is_available": true, "is_host_enabled": true, "is_guest_enabled": true } } ] } ] } } } } } }, "400": { "description": "* Missing _broadcaster\\_id_\n* Session limit reached (1 active call)" }, "401": { "description": "Phone verification missing" }, "403": { "description": "Insufficient authorization for creating session" } } }, "delete": { "summary": "BETA Programmatically ends a Guest Star session on behalf of the broadcaster.", "description": "BETA Programmatically ends a Guest Star session on behalf of the broadcaster. Performs the same action as if the host clicked the “End Call” button in the Guest Star UI.\n\n__Authorization:__\n\n* Query parameter `broadcaster_id` must match the `user_id` in the [User-Access token](https://dev.twitch.tv/docs/authentication#user-access-tokens)\n* Requires OAuth Scope: `channel:manage:guest_star`", "tags": [ "Guest Star" ], "externalDocs": { "description": "End Guest Star Session", "url": "https://dev.twitch.tv/docs/api/reference#end-guest-star-session" }, "operationId": "end-guest-star-session", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster you want to end a Guest Star session for. Provided `broadcaster_id` must match the `user_id` in the auth token.", "schema": { "type": "string" }, "required": true }, { "name": "session_id", "in": "query", "description": "ID for the session to end on behalf of the broadcaster.", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndGuestStarSessionResponse" }, "examples": { "Example": { "description": "_Request:_\n\nEnd Guest Star session\n\n```bash\ncurl -x DELETE `https://api.twitch.tv/helix/guest_star/session?broadcaster_id=9321049&session_id=2KFRQbFtpmfyD3IevNRnCzOPRJI` \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```", "value": { "data": [ { "id": "2KFRQbFtpmfyD3IevNRnCzOPRJI", "guests": [ { "id": "0", "user_id": "9321049", "user_display_name": "Cool_User", "user_login": "cool_user", "is_live": true, "volume": 100, "assigned_at": "2023-01-02T04:16:53.325Z", "audio_settings": { "is_available": true, "is_host_enabled": true, "is_guest_enabled": true }, "video_settings": { "is_available": true, "is_host_enabled": true, "is_guest_enabled": true } } ] } ] } } } } } }, "400": { "description": "* Missing or invalid _broadcaster\\_id_\n* Missing or invalid _session\\_id_\n* Session has already been ended" }, "403": { "description": "Insufficient authorization for ending session" } } } }, "/guest_star/invites": { "get": { "summary": "BETA Provides the caller with a list of pending invites to a Guest Star session.", "description": "BETA Provides the caller with a list of pending invites to a Guest Star session, including the invitee’s ready status while joining the waiting room.\n\n__Authorization:__\n\n* Query parameter `broadcaster_id` must match the `user_id` in the [User-Access token](https://dev.twitch.tv/docs/authentication#user-access-tokens)\n* Requires OAuth Scope: `channel:read:guest_star`, `channel:manage:guest_star`, `moderator:read:guest_star` or `moderator:manage:guest_star`", "tags": [ "Guest Star" ], "externalDocs": { "description": "Get Guest Star Invites", "url": "https://dev.twitch.tv/docs/api/reference#get-guest-star-invites" }, "operationId": "get-guest-star-invites", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster running the Guest Star session.", "schema": { "type": "string" }, "required": true }, { "name": "moderator_id", "in": "query", "description": "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.", "schema": { "type": "string" }, "required": true }, { "name": "session_id", "in": "query", "description": "The session ID to query for invite status.", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetGuestStarInvitesResponse" }, "examples": { "Example 1": { "description": "_Request:_\n\nGet session invites\n\n```bash\ncurl -x GET `https://api.twitch.tv/helix/guest_star/invites?broadcaster_id=9321049&moderator_id=9321049&session_id=2KFRQbFtpmfyD3IevNRnCzOPRJI` \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```" }, "Example 2": { "description": "_Request:_\n\nGet session for host channel\n\n```bash\ncurl -x GET `https://api.twitch.tv/helix/guest_star/session?broadcaster_id=9321049` \\ -H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\ -H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```", "value": { "data": [ { "user_id": "144601104", "invited_at": "2023-01-02T04:16:53.325Z", "status": "INVITED", "is_audio_enabled": false, "is_video_enabled": true, "is_audio_available": true, "is_video_available": true } ] } } } } } }, "400": { "description": "* Missing _broadcaster\\_id_\n* Missing _session\\_id_" } } }, "post": { "summary": "BETA Sends an invite to a specified guest on behalf of the broadcaster for a Guest Star session in progress.", "description": "BETA Sends an invite to a specified guest on behalf of the broadcaster for a Guest Star session in progress.\n\n__Authorization:__\n\n* Query parameter `moderator_id` must match the `user_id` in the [User-Access token](https://dev.twitch.tv/docs/authentication#user-access-tokens)\n* Requires OAuth Scope: `channel:manage:guest_star` or `moderator:manage:guest_star`", "tags": [ "Guest Star" ], "externalDocs": { "description": "Send Guest Star Invite", "url": "https://dev.twitch.tv/docs/api/reference#send-guest-star-invite" }, "operationId": "send-guest-star-invite", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster running the Guest Star session.", "schema": { "type": "string" }, "required": true }, { "name": "moderator_id", "in": "query", "description": "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.", "schema": { "type": "string" }, "required": true }, { "name": "session_id", "in": "query", "description": "The session ID for the invite to be sent on behalf of the broadcaster.", "schema": { "type": "string" }, "required": true }, { "name": "guest_id", "in": "query", "description": "Twitch User ID for the guest to invite to the Guest Star session.", "schema": { "type": "string" }, "required": true } ], "responses": { "204": { "description": "\n\n__Examples__\n\n_Request:_\n\nInvite user to Guest Star session\n\n```bash\ncurl -x POST `https://api.twitch.tv/helix/guest_star/invites?broadcaster_id=9321049&moderator_id=9321049&session_id=2KFRQbFtpmfyD3IevNRnCzOPRJI&guest_id=144601104` \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```" }, "400": { "description": "* Missing _broadcaster\\_id_\n* Missing _moderator\\_id_\n* Missing _session\\_id_\n* Missing _guest\\_id_\n* Invalid _session\\_id_" }, "403": { "description": "* Unauthorized guest invited\n* Guest already invited" } } }, "delete": { "summary": "BETA Revokes a previously sent invite for a Guest Star session.", "description": "BETA Revokes a previously sent invite for a Guest Star session.\n\n__Authorization:__\n\n* Query parameter `moderator_id` must match the `user_id` in the [User-Access token](https://dev.twitch.tv/docs/authentication#user-access-tokens)\n* Requires OAuth Scope: `channel:manage:guest_star` or `moderator:manage:guest_star`", "tags": [ "Guest Star" ], "externalDocs": { "description": "Delete Guest Star Invite", "url": "https://dev.twitch.tv/docs/api/reference#delete-guest-star-invite" }, "operationId": "delete-guest-star-invite", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster running the Guest Star session.", "schema": { "type": "string" }, "required": true }, { "name": "moderator_id", "in": "query", "description": "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.", "schema": { "type": "string" }, "required": true }, { "name": "session_id", "in": "query", "description": "The ID of the session for the invite to be revoked on behalf of the broadcaster.", "schema": { "type": "string" }, "required": true }, { "name": "guest_id", "in": "query", "description": "Twitch User ID for the guest to revoke the Guest Star session invite from.", "schema": { "type": "string" }, "required": true } ], "responses": { "204": { "description": "\n\n__Examples__\n\n_Request:_\n\nRemove invite to session\n\n```bash\ncurl -x DELETE `https://api.twitch.tv/helix/guest_star/invites?broadcaster_id=9321049&moderator_id=9321049&session_id=2KFRQbFtpmfyD3IevNRnCzOPRJI&guest_id=144601104` \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```" }, "400": { "description": "* Missing _broadcaster\\_id_\n* Missing _session\\_id_\n* Missing _guest\\_id_\n* Invalid _session\\_id_" }, "404": { "description": "No invite exists for specified _guest\\_id_" } } } }, "/guest_star/slot": { "post": { "summary": "BETA Allows a previously invited user to be assigned a slot within the active Guest Star session.", "description": "BETA Allows a previously invited user to be assigned a slot within the active Guest Star session, once that guest has indicated they are ready to join.\n\n__Authorization:__\n\n* Query parameter `moderator_id` must match the `user_id` in the [User-Access token](https://dev.twitch.tv/docs/authentication#user-access-tokens)\n* Requires OAuth Scope: `channel:manage:guest_star` or `moderator:manage:guest_star`", "tags": [ "Guest Star" ], "externalDocs": { "description": "Assign Guest Star Slot", "url": "https://dev.twitch.tv/docs/api/reference#assign-guest-star-slot" }, "operationId": "assign-guest-star-slot", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster running the Guest Star session.", "schema": { "type": "string" }, "required": true }, { "name": "moderator_id", "in": "query", "description": "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.", "schema": { "type": "string" }, "required": true }, { "name": "session_id", "in": "query", "description": "The ID of the Guest Star session in which to assign the slot.", "schema": { "type": "string" }, "required": true }, { "name": "guest_id", "in": "query", "description": "The Twitch User ID corresponding to the guest to assign a slot in the session. This user must already have an invite to this session, and have indicated that they are ready to join.", "schema": { "type": "string" }, "required": true }, { "name": "slot_id", "in": "query", "description": "The slot assignment to give to the user. Must be a numeric identifier between “1” and “N” where N is the max number of slots for the session. Max number of slots allowed for the session is reported by [Get Channel Guest Star Settings](https://dev.twitch.tv/docs/api/reference#get-channel-guest-star-settings).", "schema": { "type": "string" }, "required": true } ], "responses": { "204": { "description": "Successfuly assigned guest to slot\n\n__Examples__\n\n_Request:_\n\nAssign invited user to slot\n\n```bash\ncurl -x POST `https://api.twitch.tv/helix/guest_star/slot?broadcaster_id=9321049&moderator_id=9321049&session_id=2KFRQbFtpmfyD3IevNRnCzOPRJI&guest_id=144601104&slot_id=1` \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```" }, "400": { "description": "* Missing _broadcaster\\_id_\n* Missing _moderator\\_id_\n* Missing _guest\\_id_\n* Missing or invalid _session\\_id_\n* Missing or invalid _slot\\_id_" }, "401": { "description": "_moderator\\_id_ is not a guest star moderator" }, "403": { "description": "* Cannot assign host slot\n* Guest not invited to session\n* Guest already assigned to slot\n* Guest is not ready to join" } } }, "patch": { "summary": "BETA Allows a user to update the assigned slot for a particular user within the active Guest Star session.", "description": "BETA Allows a user to update the assigned slot for a particular user within the active Guest Star session.\n\n__Authorization:__\n\n* Query parameter `moderator_id` must match the `user_id` in the [User-Access token](https://dev.twitch.tv/docs/authentication#user-access-tokens)\n* Requires OAuth Scope: `channel:manage:guest_star` or `moderator:manage:guest_star`", "tags": [ "Guest Star" ], "externalDocs": { "description": "Update Guest Star Slot", "url": "https://dev.twitch.tv/docs/api/reference#update-guest-star-slot" }, "operationId": "update-guest-star-slot", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster running the Guest Star session.", "schema": { "type": "string" }, "required": true }, { "name": "moderator_id", "in": "query", "description": "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.", "schema": { "type": "string" }, "required": true }, { "name": "session_id", "in": "query", "description": "The ID of the Guest Star session in which to update slot settings.", "schema": { "type": "string" }, "required": true }, { "name": "source_slot_id", "in": "query", "description": "The slot assignment previously assigned to a user.", "schema": { "type": "string" }, "required": true }, { "name": "destination_slot_id", "in": "query", "description": "The slot to move this user assignment to. If the destination slot is occupied, the user assigned will be swapped into `source_slot_id`.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Successfuly updated slot(s)\n\n__Examples__\n\n_Request:_\n\nMove slot assignment to a new slot ID\n\n```bash\ncurl -x PATCH `https://api.twitch.tv/helix/guest_star/slot?broadcaster_id=9321049&moderator_id=9321049&session_id=2KFRQbFtpmfyD3IevNRnCzOPRJI&source_slot_id=1&destination_slot_id=2` \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```" }, "400": { "description": "* Missing _broadcaster\\_id_\n* Missing or invalid _session\\_id_\n* Missing or invalid _slot\\_id_" } } }, "delete": { "summary": "BETA Allows a caller to remove a slot assignment from a user participating in an active Guest Star session.", "description": "BETA Allows a caller to remove a slot assignment from a user participating in an active Guest Star session. This revokes their access to the session immediately and disables their access to publish or subscribe to media within the session.\n\n__Authorization:__\n\n* Query parameter `moderator_id` must match the `user_id` in the [User-Access token](https://dev.twitch.tv/docs/authentication#user-access-tokens)\n* Requires OAuth Scope: `channel:manage:guest_star` or `moderator:manage:guest_star`", "tags": [ "Guest Star" ], "externalDocs": { "description": "Delete Guest Star Slot", "url": "https://dev.twitch.tv/docs/api/reference#delete-guest-star-slot" }, "operationId": "delete-guest-star-slot", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster running the Guest Star session.", "schema": { "type": "string" }, "required": true }, { "name": "moderator_id", "in": "query", "description": "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.", "schema": { "type": "string" }, "required": true }, { "name": "session_id", "in": "query", "description": "The ID of the Guest Star session in which to remove the slot assignment.", "schema": { "type": "string" }, "required": true }, { "name": "guest_id", "in": "query", "description": "The Twitch User ID corresponding to the guest to remove from the session.", "schema": { "type": "string" }, "required": true }, { "name": "slot_id", "in": "query", "description": "The slot ID representing the slot assignment to remove from the session.", "schema": { "type": "string" }, "required": true }, { "name": "should_reinvite_guest", "in": "query", "description": "Flag signaling that the guest should be reinvited to the session, sending them back to the invite queue.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Successfuly removed user from slot\n\n__Examples__\n\n_Request:_\n\nRemove user from slot\n\n```bash\ncurl -x DELETE `https://api.twitch.tv/helix/guest_star/slot?broadcaster_id=9321049&moderator_id=9321049&session_id=2KFRQbFtpmfyD3IevNRnCzOPRJI&session_id=2KFRQbFtpmfyD3IevNRnCzOPRJI&guest_id=144601104&slot_id=1` \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```" }, "400": { "description": "* Missing _broadcaster\\_id_\n* Missing _moderator\\_id_\n* Missing or invalid _session\\_id_\n* Missing or invalid _slot\\_id_" }, "403": { "description": "* _moderator\\_id_ is not a Guest Star moderator\n* The request is attempting to modify a restricted slot" }, "404": { "description": "_guest\\_id_ or _slot\\_id_ not found" } } } }, "/guest_star/slot_settings": { "patch": { "summary": "BETA Allows a user to update slot settings for a particular guest within a Guest Star session.", "description": "BETA Allows a user to update slot settings for a particular guest within a Guest Star session, such as allowing the user to share audio or video within the call as a host. These settings will be broadcasted to all subscribers which control their view of the guest in that slot. One or more of the optional parameters to this API can be specified at any time.\n\n__Authorization:__\n\n* Query parameter `moderator_id` must match the `user_id` in the [User-Access token](https://dev.twitch.tv/docs/authentication#user-access-tokens)\n* Requires OAuth Scope: `channel:manage:guest_star` or `moderator:manage:guest_star`", "tags": [ "Guest Star" ], "externalDocs": { "description": "Update Guest Star Slot Settings", "url": "https://dev.twitch.tv/docs/api/reference#update-guest-star-slot-settings" }, "operationId": "update-guest-star-slot-settings", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster running the Guest Star session.", "schema": { "type": "string" }, "required": true }, { "name": "moderator_id", "in": "query", "description": "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.", "schema": { "type": "string" }, "required": true }, { "name": "session_id", "in": "query", "description": "The ID of the Guest Star session in which to update a slot’s settings.", "schema": { "type": "string" }, "required": true }, { "name": "slot_id", "in": "query", "description": "The slot assignment that has previously been assigned to a user.", "schema": { "type": "string" }, "required": true }, { "name": "is_audio_enabled", "in": "query", "description": "Flag indicating whether the slot is allowed to share their audio with the rest of the session. If false, the slot will be muted in any views containing the slot.", "schema": { "type": "boolean" } }, { "name": "is_video_enabled", "in": "query", "description": "Flag indicating whether the slot is allowed to share their video with the rest of the session. If false, the slot will have no video shared in any views containing the slot.", "schema": { "type": "boolean" } }, { "name": "is_live", "in": "query", "description": "Flag indicating whether the user assigned to this slot is visible/can be heard from any public subscriptions. Generally, this determines whether or not the slot is enabled in any broadcasting software integrations.", "schema": { "type": "boolean" } }, { "name": "volume", "in": "query", "description": "Value from 0-100 that controls the audio volume for shared views containing the slot.", "schema": { "type": "integer", "format": "int32" } } ], "responses": { "204": { "description": "Successfuly updated slot settings\n\n__Examples__\n\n_Request:_\n\nUpdate slot settings to enable slot in broadcasting software\n\n```bash\ncurl -x PATCH `https://api.twitch.tv/helix/guest_star/slot_settings?broadcaster_id=9321049&moderator_id=9321049&session_id=2KFRQbFtpmfyD3IevNRnCzOPRJI&slot_id=1&is_audio_enabled=false` \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```\n\n_Request:_\n\nMute a slot’s audio for a guest\n\n```bash\ncurl -x PATCH `https://api.twitch.tv/helix/guest_star/slot_settings?broadcaster_id=9321049&moderator_id=9321049&session_id=2KFRQbFtpmfyD3IevNRnCzOPRJI&slot_id=1&is_live=true` \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```\n\n_Request:_\n\nAllow slot audio to be unmuted by a guest. **NOTE**: This operation does not immediately unmute the guest. The guest will be notified they can unmute themselves when ready.\n\n```bash\ncurl -x PATCH `https://api.twitch.tv/helix/guest_star/slot_settings?broadcaster_id=9321049&moderator_id=9321049&session_id=2KFRQbFtpmfyD3IevNRnCzOPRJI&slot_id=1&is_audio_enabled=true` \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```" }, "400": { "description": "* Missing _broadcaster\\_id_\n* Missing _moderator\\_id_\n* Missing or invalid _session\\_id_\n* Missing or invalid _slot\\_id_" }, "403": { "description": "* _moderator\\_id_ is not a Guest Star moderator\n* The request is attempting to modify a restricted slot" } } } }, "/hypetrain/status": { "get": { "summary": "NEW Gets the status of a Hype Train for the specified broadcaster.", "description": "NEW Get the status of a Hype Train for the specified broadcaster.\n\n__Authorization:__\n\n* Requires an [user access token](https://dev.twitch.tv/docs/authentication/#user-access-tokens).\n* Requires OAuth Scope: `channel:read:hype_train`.\n* Requires that `broadcaster_id` and `user_id` match in the User-Access token.", "tags": [ "Hype Train" ], "externalDocs": { "description": "Get Hype Train Status", "url": "https://dev.twitch.tv/docs/api/reference#get-hype-train-status" }, "operationId": "get-hype-train-status", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The User ID of the channel broadcaster.", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Successfully retrieved the status object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetHypeTrainStatusResponse" }, "examples": { "Example": { "description": "_Request:_\n\n```bash\ncurl -X GET\n'https://api.twitch.tv/helix/hypetrain/status?broadcaster_id=123' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```", "value": { "data": [ { "current": { "id": "1b0AsbInCHZW2SQFQkCzqN07Ib2", "broadcaster_user_id": "1337", "broadcaster_user_login": "cool_user", "broadcaster_user_name": "Cool_User", "level": 2, "total": 700, "progress": 200, "goal": 1000, "top_contributions": [ { "user_id": "123", "user_login": "pogchamp", "user_name": "PogChamp", "type": "bits", "total": 50 }, { "user_id": "456", "user_login": "kappa", "user_name": "Kappa", "type": "subscription", "total": 45 } ], "shared_train_participants": [ { "broadcaster_user_id": "456", "broadcaster_user_login": "pogchamp", "broadcaster_user_name": "PogChamp" }, { "broadcaster_user_id": "321", "broadcaster_user_login": "pogchamp", "broadcaster_user_name": "PogChamp" } ], "started_at": "2020-07-15T17:16:03.17106713Z", "expires_at": "2020-07-15T17:16:11.17106713Z", "type": "golden_kappa" }, "all_time_high": { "level": 6, "total": 2850, "achieved_at": "2020-04-24T20:12:21.003802269Z" }, "shared_all_time_high": { "level": 16, "total": 23850, "achieved_at": "2020-04-27T20:12:21.003802269Z" } } ] } } } } } }, "400": { "description": "The ID in the `broadcaster_id` query parameter is not valid." }, "401": { "description": "* The OAuth token is not valid.\n* The Authorization header is required and must contain a user access token." }, "500": { "description": "Internal Server Error." } }, "security": [ { "twitch_auth": [ "channel:read:hype_train" ] } ] } }, "/moderation/enforcements/status": { "post": { "summary": "Checks whether AutoMod would flag the specified message for review.", "description": "Checks whether AutoMod would flag the specified message for review.\n\nAutoMod 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](https://help.twitch.tv/s/article/how-to-use-automod).\n\n**Rate Limits**: Rates are limited per channel based on the account type rather than per access token.\n\n| Account type | Limit per minute | Limit per hour |\n| - | - | - |\n| Normal | 5 | 50 |\n| Affiliate | 10 | 100 |\n| Partner | 30 | 300 |\n\n\nThe above limits are in addition to the standard [Twitch API rate limits](https://dev.twitch.tv/docs/api/guide#twitch-rate-limits). The rate limit headers in the response represent the Twitch rate limits and not the above limits.\n\n__Authorization:__\n\nRequires one of the following:\n\n* A [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **moderation:read** scope.\n* BETA An [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens) where the application, through a prior authorization, has the **moderation:read** scope for the user represented by the `broadcaster_id` query parameter.", "tags": [ "Moderation" ], "externalDocs": { "description": "Check AutoMod Status", "url": "https://dev.twitch.tv/docs/api/reference#check-automod-status" }, "operationId": "check-automod-status", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "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.", "schema": { "type": "string" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckAutoModStatusBody" }, "examples": { "Example": { "value": { "data": [ { "msg_id": "123", "msg_text": "Hello World!" }, { "msg_id": "393", "msg_text": "Boooooo!" } ] } } } } } }, "responses": { "200": { "description": "Successfully checked the messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckAutoModStatusResponse" }, "examples": { "Example": { "description": "_Request:_\n\n```bash\ncurl -X POST 'https://api.twitch.tv/helix/moderation/enforcements/status?broadcaster_id=12345' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \\\n-H 'Content-Type: application/json' \\\n-d '{\n \"data\": [\n {\n \"msg_id\": \"123\",\n \"msg_text\": \"Hello World!\"\n },\n {\n \"msg_id\": \"393\",\n \"msg_text\": \"Boooooo!\"\n }\n ]\n}'\n```", "value": { "data": [ { "msg_id": "123", "is_permitted": true }, { "msg_id": "393", "is_permitted": false } ] } } } } } }, "400": { "description": "* The _broadcaster\\_id_ query parameter is required.\n* The `data` field is required and the list must contain one or more messages to check.\n* The `msg_id` field is required.\n* The `msg_text` field is required." }, "401": { "description": "* The Authorization header is required and must contain a user access token.\n* The user access token must include the **moderation:read** scope.\n* The access token is not valid.\n* The client ID specified in the Client-Id header does not match the client ID specified in the access token." }, "403": { "description": "* The ID in _broadcaster\\_id_ must match the user ID in the user access token." }, "429": { "description": "* The broadcaster exceeded the number of chat message checks that they may make. See the endpoint's rate limits." } }, "security": [ { "twitch_auth": [ "moderation:read" ] } ] } }, "/moderation/automod/message": { "post": { "summary": "Allow or deny the message that AutoMod flagged for review.", "description": "Allow or deny the message that AutoMod flagged for review. For information about AutoMod, see [How to Use AutoMod](https://help.twitch.tv/s/article/how-to-use-automod).\n\nTo get messages that AutoMod is holding for review, subscribe to the **automod-queue..** [topic](https://dev.twitch.tv/docs/pubsub#topics) using [PubSub](https://dev.twitch.tv/docs/pubsub). PubSub sends a notification to your app when AutoMod holds a message for review.\n\n__Authorization:__\n\nRequires one of the following:\n\n* A [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **moderator:manage:automod** scope.\n* BETA An [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens) where the application, through a prior authorization, has the **moderator:manage:automod** scope for the user represented by the `user_id` query parameter.", "tags": [ "Moderation" ], "externalDocs": { "description": "Manage Held AutoMod Messages", "url": "https://dev.twitch.tv/docs/api/reference#manage-held-automod-messages" }, "operationId": "manage-held-automod-messages", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManageHeldAutoModMessagesBody" }, "examples": { "Example": { "value": { "user_id": "9327994", "msg_id": "836013710", "action": "ALLOW" } } } } } }, "responses": { "204": { "description": "Successfully approved or denied the message.\n\n__Examples__\n\n_Request:_\n\n```bash\ncurl -X POST 'https://api.twitch.tv/helix/moderation/automod/message' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \\\n-H 'Content-Type: application/json' \\\n-d '{\n \"user_id\": \"9327994\",\n \"msg_id\": \"836013710\",\n \"action\": \"ALLOW\"\n}'\n```" }, "400": { "description": "* The value in the `action` field is not valid.\n* The `user_id` field is required.\n* The `msg_id` field is required.\n* The `action` field is required." }, "401": { "description": "* The ID in `user_id` must match the user ID in the user access token.\n* The Authorization header is required and must contain a user access token.\n* The user access token must include the **moderator:manage:automod** scope.\n* The access token is not valid.\n* The client ID specified in the Client-Id header does not match the client ID specified in the access token." }, "403": { "description": "* The user in _user\\_id_ is not one of the broadcaster's moderators." }, "404": { "description": "* The message specified in the `msg_id` field was not found." } }, "security": [ { "twitch_auth": [ "moderator:manage:automod" ] } ] } }, "/moderation/automod/settings": { "get": { "summary": "Gets the broadcaster’s AutoMod settings.", "description": "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.\n\n__Authorization:__\n\nRequires one of the following:\n\n* A [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **moderator:read:automod\\_settings** or **moderator:manage:automod\\_settings** scope.\n* BETA An [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens) where the application, through a prior authorization, has the **moderator:read:automod\\_settings** or **moderator:manage:automod\\_settings** scope for the user represented by the `moderator_id` query parameter.", "tags": [ "Moderation" ], "externalDocs": { "description": "Get AutoMod Settings", "url": "https://dev.twitch.tv/docs/api/reference#get-automod-settings" }, "operationId": "get-automod-settings", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster whose AutoMod settings you want to get.", "schema": { "type": "string" }, "required": true }, { "name": "moderator_id", "in": "query", "description": "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.", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Successfully retrieved the broadcaster’s AutoMod settings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAutoModSettingsResponse" }, "examples": { "Example": { "description": "Shows what the response looks like if the broadcaster hasn’t enabled AutoMod (none of the settings are set).\n\n_Request:_\n\nGets the broadcaster’s AutoMod settings.\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/moderation/automod/settings?broadcaster_id=1234&moderator_id=5678' \\\n-H 'Authorization: Bearer 4a4x78f5wqvkybms7mxfist3jmzul' \\\n-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh'\n```", "value": { "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 } ] } } } } } }, "400": { "description": "* The _broadcaster\\_id_ query parameter is required.\n* The _moderator\\_id_ query parameter is required." }, "401": { "description": "* The ID in _moderator\\_id_ must match the user ID in the user access token.\n* The Authorization header is required and must contain a user access token.\n* The user access token must include the **moderator:read:automod\\_settings** scope.\n* The access token is not valid.\n* The client ID specified in the Client-Id header does not match the client ID specified in the access token." }, "403": { "description": "* The user in _moderator\\_id_ is not one of the broadcaster's moderators." } }, "security": [ { "twitch_auth": [ "moderator:read:automod_settings", "moderator:manage:automod_settings" ] } ] }, "put": { "summary": "Updates the broadcaster’s AutoMod settings.", "description": "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.\n\n__Authorization:__\n\nRequires one of the following:\n\n* A [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **moderator:manage:automod\\_settings** scope.\n* BETA An [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens) where the application, through a prior authorization, has the **moderator:manage:automod\\_settings** scope for the user represented by the `moderator_id` query parameter.\n\n__Request Body:__\n\nBecause 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.\n\nYou may set either `overall_level` or the individual settings like `aggression`, but not both.\n\nSetting `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).\n\nIf `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.\n\nNote 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.\n\nValid 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).", "tags": [ "Moderation" ], "externalDocs": { "description": "Update AutoMod Settings", "url": "https://dev.twitch.tv/docs/api/reference#update-automod-settings" }, "operationId": "update-automod-settings", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster whose AutoMod settings you want to update.", "schema": { "type": "string" }, "required": true }, { "name": "moderator_id", "in": "query", "description": "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.", "schema": { "type": "string" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAutoModSettingsBody" }, "examples": { "Example 1": { "value": { "overall_level": 3 }, "description": "This example updates the `overall_level` setting to 3." }, "Example 2": { "value": { "overall_level": 3 }, "description": "This example updates the `overall_level` setting to 3." } } } } }, "responses": { "200": { "description": "Successfully updated the broadcaster’s AutoMod settings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAutoModSettingsResponse" }, "examples": { "Example 1": { "description": "Notice in the response that not all settings are set to level 3.\n\n_Request:_\n\nThis example updates the `overall_level` setting to 3.\n\n```bash\ncurl -X PUT 'https://api.twitch.tv/helix/moderation/automod/settings?broadcaster_id=1234&moderator_id=5678' \\\n-H 'Authorization: Bearer 4a4x78f5wqvkybms7mxfist3jmzul' \\\n-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh'\n​​-H 'Content-Type: application/json' \\\n-d '{\"overall_level\":3}'\n```", "value": { "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 } ] } }, "Example 2": { "description": "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.\n\n_Request:_\n\nThis example updates the `overall_level` setting to 3.\n\n```bash\ncurl -X PUT 'https://api.twitch.tv/helix/moderation/automod/settings?broadcaster_id=1234&moderator_id=5678' \\\n-H 'Authorization: Bearer 4a4x78f5wqvkybms7mxfist3jmzul' \\\n-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh'\n​​-H 'Content-Type: application/json' \\\n-d '{\"overall_level\":3}'\n```", "value": { "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 } ] } } } } } }, "400": { "description": "* The _broadcaster\\_id_ is required.\n* The _moderator\\_id_ is required.\n* 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.\n* The value of one or more AutoMod settings is not valid." }, "401": { "description": "* The ID in _moderator\\_id_ must match the user ID in the user access token.\n* The Authorization header is required and must contain a user access token.\n* The user access token must include the **moderator:manage:automod\\_settings** scope.\n* The access token is not valid.\n* The client ID specified in the Client-Id header does not match the client ID specified in the access token." }, "403": { "description": "* The user in _moderator\\_id_ is not one of the broadcaster's moderators." } }, "security": [ { "twitch_auth": [ "moderator:manage:automod_settings" ] } ] } }, "/moderation/banned": { "get": { "summary": "Gets all users that the broadcaster banned or put in a timeout.", "description": "Gets all users that the broadcaster banned or put in a timeout.\n\n__Authorization:__\n\nRequires one of the following:\n\n* A [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **moderation:read** or **moderator:manage:banned\\_users** scope.\n* BETA An [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens) where the application, through a prior authorization, has the **moderation:read** or **moderator:manage:banned\\_users** scope for the user represented by the `broadcaster_id` query parameter.", "tags": [ "Moderation" ], "externalDocs": { "description": "Get Banned Users", "url": "https://dev.twitch.tv/docs/api/reference#get-banned-users" }, "operationId": "get-banned-users", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "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.", "schema": { "type": "string" }, "required": true }, { "name": "user_id", "in": "query", "description": "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. \n \nThe 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.", "schema": { "type": "array", "items": { "type": "string" } }, "explode": true }, { "name": "first", "in": "query", "description": "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.", "schema": { "type": "integer", "format": "int32" } }, { "name": "after", "in": "query", "description": "The cursor used to get the next page of results. The **Pagination** object in the response contains the cursor’s value. [Read More](https://dev.twitch.tv/docs/api/guide#pagination)", "schema": { "type": "string" } }, { "name": "before", "in": "query", "description": "The cursor used to get the previous page of results. The **Pagination** object in the response contains the cursor’s value. [Read More](https://dev.twitch.tv/docs/api/guide#pagination)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the list of banned users.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetBannedUsersResponse" }, "examples": { "Example": { "description": "_Request:_\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/moderation/banned?broadcaster_id=198704263' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```", "value": { "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" } } } } } } }, "400": { "description": "* The _broadcaster\\_id_ query parameter is required." }, "401": { "description": "* The ID in _broadcaster\\_id_ must match the user ID in the user access token.\n* The Authorization header is required and must contain a user access token.\n* The user access token must include the **moderation:read** scope.\n* The access token is not valid.\n* The client ID specified in the Client-Id header does not match the client ID specified in the access token." } }, "security": [ { "twitch_auth": [ "moderation:read", "moderator:manage:banned_users" ] } ] } }, "/moderation/bans": { "post": { "summary": "Bans a user from participating in a broadcaster’s chat room or puts them in a timeout.", "description": "Bans a user from participating in the specified broadcaster’s chat room or puts them in a timeout.\n\nFor information about banning or putting users in a timeout, see [Ban a User](https://help.twitch.tv/s/article/how-to-manage-harassment-in-chat#TheBanFeature) and [Timeout a User](https://help.twitch.tv/s/article/how-to-manage-harassment-in-chat#TheTimeoutFeature).\n\nIf 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.\n\nTo remove a ban or end a timeout, see [Unban user](https://dev.twitch.tv/docs/api/reference#unban-user).\n\n__Authorization:__\n\nRequires one of the following:\n\n* A [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **moderator:manage:banned\\_users** scope.\n* BETA An [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens) where the application, through a prior authorization, has the **moderator:manage:banned\\_users** and **user:bot** scopes for the user represented by the `moderator_id` query parameter.", "tags": [ "Moderation" ], "externalDocs": { "description": "Ban User", "url": "https://dev.twitch.tv/docs/api/reference#ban-user" }, "operationId": "ban-user", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster whose chat room the user is being banned from.", "schema": { "type": "string" }, "required": true }, { "name": "moderator_id", "in": "query", "description": "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.", "schema": { "type": "string" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BanUserBody" }, "examples": { "Example 1": { "value": { "data": { "user_id": "9876", "reason": "no reason" } }, "description": "Bans a user (it doesn’t include the `duration` field)." }, "Example 2": { "value": { "data": { "user_id": "9876", "duration": 300, "reason": "no reason" } }, "description": "Puts a user in a 5-minute timeout." }, "Example 3": { "value": { "data": { "user_id": "9876", "duration": 300, "reason": "no reason" } }, "description": "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.\n\nYou’ll get the same response if you try to ban a user who is already banned." } } } } }, "responses": { "200": { "description": "Successfully banned the user or placed them in a timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BanUserResponse" }, "examples": { "Example 1": { "description": "_Request:_\n\nBans a user (it doesn’t include the `duration` field).\n\n```bash\ncurl -X POST 'https://api.twitch.tv/helix/moderation/bans?broadcaster_id=1234&moderator_id=5678' \\\n-H 'Authorization: Bearer 4a4x78f5wqvkybms7mxfist3jmzul' \\\n-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh' \\\n-H 'Content-Type: application/json' \\\n-d '{\"data\": {\"user_id\":\"9876\",\"reason\":\"no reason\"}}'\n```", "value": { "data": [ { "broadcaster_id": "1234", "moderator_id": "5678", "user_id": "9876", "created_at": "2021-09-28T18:22:31Z", "end_time": null } ] } }, "Example 2": { "description": "_Request:_\n\nPuts a user in a 5-minute timeout.\n\n```bash\ncurl -X POST 'https://api.twitch.tv/helix/moderation/bans?broadcaster_id=1234&moderator_id=5678' \\\n-H 'Authorization: Bearer 4a4x78f5wqvkybms7mxfist3jmzul' \\\n-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh' \\\n-H 'Content-Type: application/json' \\\n-d '{\"data\": {\"user_id\":\"9876\",\"duration\":300,\"reason\":\"no reason\"}}'\n```", "value": { "data": [ { "broadcaster_id": "1234", "moderator_id": "5678", "user_id": "9876", "created_at": "2021-09-28T19:27:31Z", "end_time": "2021-09-28T19:22:31Z" } ] } } } } } }, "400": { "description": "* The _broadcaster\\_id_ query parameter is required.\n* The _moderator\\_id_ query parameter is required.\n* The `user_id` field is required.\n* The text in the `reason` field is too long.\n* The value in the `duration` field is not valid.\n* The user specified in the `user_id` field may not be banned.\n* The user specified in the `user_id` field may not be put in a timeout.\n* The user specified in the `user_id` field is already banned.", "content": { "application/json": { "examples": { "Example": { "description": "_Request:_\n\nShows 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.\n\nYou’ll get the same response if you try to ban a user who is already banned.\n\n```bash\ncurl -X POST 'https://api.twitch.tv/helix/moderation/bans?broadcaster_id=1234&moderator_id=5678' \\\n-H 'Authorization: Bearer 4a4x78f5wqvkybms7mxfist3jmzul' \\\n-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh' \\\n-H 'Content-Type: application/json' \\\n-d '{\"data\": {\"user_id\":\"9876\",\"duration\":300,\"reason\":\"no reason\"}}'\n```", "value": { "error": "Bad Request", "status": 400, "message": "user is already banned" } } } } } }, "401": { "description": "* The ID in _moderator\\_id_ must match the user ID in the access token.\n* The Authorization header is required and must contain a user access token.\n* The user access token must include the **moderator:manage:banned\\_users** scope.\n* The access token is not valid.\n* The client ID specified in the Client-Id header does not match the client ID specified in the access token." }, "403": { "description": "* The user in _moderator\\_id_ is not one of the broadcaster's moderators." }, "409": { "description": "* 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": { "description": "* The app has exceeded the number of requests it may make per minute for this broadcaster." } }, "security": [ { "twitch_auth": [ "moderator:manage:banned_users", "user:bot" ] } ] }, "delete": { "summary": "Removes the ban or timeout that was placed on the specified user.", "description": "Removes the ban or timeout that was placed on the specified user.\n\nTo ban a user, see [Ban user](https://dev.twitch.tv/docs/api/reference#ban-user).\n\n__Authorization:__\n\nRequires one of the following:\n\n* A [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **moderator:manage:banned\\_users** scope.\n* BETA An [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens) where the application, through a prior authorization, has the **moderator:manage:banned\\_users** and **user:bot** scopes for the user represented by the `moderator_id` query parameter.", "tags": [ "Moderation" ], "externalDocs": { "description": "Unban User", "url": "https://dev.twitch.tv/docs/api/reference#unban-user" }, "operationId": "unban-user", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster whose chat room the user is banned from chatting in.", "schema": { "type": "string" }, "required": true }, { "name": "moderator_id", "in": "query", "description": "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.", "schema": { "type": "string" }, "required": true }, { "name": "user_id", "in": "query", "description": "The ID of the user to remove the ban or timeout from.", "schema": { "type": "string" }, "required": true } ], "responses": { "204": { "description": "Successfully removed the ban or timeout.\n\n__Examples__\n\n_Request:_\n\nRemoves a ban or timeout from a user.\n\n```bash\ncurl -X DELETE 'https://api.twitch.tv/helix/moderation/bans?broadcaster_id=1234&moderator_id=5678&user_id=5432' \\\n-H 'Authorization: Bearer 4a4x78f5wqvkybms7mxfist3jmzul' \\\n-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh'\n```" }, "400": { "description": "* The _broadcaster\\_id_ query parameter is required.\n* The _moderator\\_id_ query parameter is required.\n* The _user\\_id_ query parameter is required.\n* The user specified in the _user\\_id_ query parameter is not banned.", "content": { "application/json": { "examples": { "Example": { "description": "_Request:_\n\nTries to remove a ban or timeout from a user that is not currently banned or in a timeout.\n\n```bash\ncurl -X DELETE 'https://api.twitch.tv/helix/moderation/bans?broadcaster_id=1234&moderator_id=5678&user_id=5432' \\\n-H 'Authorization: Bearer 4a4x78f5wqvkybms7mxfist3jmzul' \\\n-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh'\n```", "value": { "error": "Bad Request", "status": 400, "message": "user is not banned" } } } } } }, "401": { "description": "* The ID in _moderator\\_id_ must match the user ID in the access token.\n* The Authorization header is required and must contain a user access token.\n* The user access token must include the **moderator:manage:banned\\_users** scope.\n* The access token is not valid.\n* The client ID specified in the Client-Id header does not match the client ID specified in the access token." }, "403": { "description": "* The user in _moderator\\_id_ is not one of the broadcaster's moderators." }, "409": { "description": "* 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": { "description": "* The app has exceeded the number of requests it may make per minute for this broadcaster." } }, "security": [ { "twitch_auth": [ "moderator:manage:banned_users", "user:bot" ] } ] } }, "/moderation/unban_requests": { "get": { "summary": "Gets a list of unban requests for a broadcaster’s channel.", "description": "Gets a list of unban requests for a broadcaster’s channel.\n\n__Authorization:__\n\n* Requires a user access token that includes the **moderator:read:unban\\_requests** or **moderator:manage:unban\\_requests** scope.\n* Query parameter `moderator_id` must match the `user_id` in the [user access token](https://dev.twitch.tv/docs/authentication/#user-access-tokens).", "tags": [ "Moderation" ], "externalDocs": { "description": "Get Unban Requests", "url": "https://dev.twitch.tv/docs/api/reference#get-unban-requests" }, "operationId": "get-unban-requests", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster whose channel is receiving unban requests.", "schema": { "type": "string" }, "required": true }, { "name": "moderator_id", "in": "query", "description": "The ID of the broadcaster or a user that has permission to moderate the broadcaster’s unban requests. This ID must match the user ID in the user access token.", "schema": { "type": "string" }, "required": true }, { "name": "status", "in": "query", "description": "Filter by a status. \n \n* pending\n* approved\n* denied\n* acknowledged\n* canceled", "schema": { "type": "string" }, "required": true }, { "name": "user_id", "in": "query", "description": "The ID used to filter what unban requests are returned.", "schema": { "type": "string" } }, { "name": "after", "in": "query", "description": "Cursor used to get next page of results. Pagination object in response contains cursor value.", "schema": { "type": "string" } }, { "name": "first", "in": "query", "description": "The maximum number of items to return per page in response", "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "Successfully retrieved the list of unban requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetUnbanRequestsResponse" }, "examples": { "Example": { "description": "_Request:_\n\nGets information about the specified broadcaster.\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/moderation/unban_requests?broadcaster_id=274637212&moderator_id=274637212&status=pending' \\\n​​​​​-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```", "value": { "data": [ { "id": "92af127c-7326-4483-a52b-b0da0be61c01", "broadcaster_name": "torpedo09", "broadcaster_login": "torpedo09", "broadcaster_id": "274637212", "moderator_id": "141981764", "moderator_login": "twitchdev", "moderator_name": "TwitchDev", "user_id": "424596340", "user_login": "quotrok", "user_name": "quotrok", "text": "Please unban me from the channel?", "status": "pending", "created_at": "2022-08-07T02:07:55Z", "resolved_at": null, "resolution_text": null } ], "pagination": { "cursor": "eyJiIjpudWxsLCJhIjp7IkN1cnNvciI6IjEwMDQ3MzA2NDo4NjQwNjU3MToxSVZCVDFKMnY5M1BTOXh3d1E0dUdXMkJOMFcifX0" } } } } } } }, "400": { "description": "* The _broadcaster\\_id_ query parameter is required.\n* The ID in the _broadcaster\\_id_ query parameter is not valid.\n* The _moderator\\_id_ query parameter is required.\n* The ID in the _moderator\\_id_ query parameter is not valid.\n* The pagination cursor is not valid." }, "401": { "description": "* The ID in _moderator\\_id_ must match the user ID in the user access token.\n* The Authorization header is required and must contain a user access token.\n* The user access token must include the **moderator:read:unban\\_requests** or **moderator:manage:unban\\_requests** scope.\n* The access token is not valid.\n* The client ID specified in the Client-Id header does not match the client ID specified in the access token." } }, "security": [ { "twitch_auth": [ "moderator:read:unban_requests", "moderator:manage:unban_requests" ] } ] }, "patch": { "summary": "Resolves an unban request by approving or denying it.", "description": "Resolves an unban request by approving or denying it.\n\n__Authorization:__\n\n* Requires a user access token that includes the **moderator:manage:unban\\_requests** scope.\n* Query parameter `moderator_id` must match the `user_id` in the[user access token](https://dev.twitch.tv/docs/authentication/#user-access-tokens).", "tags": [ "Moderation" ], "externalDocs": { "description": "Resolve Unban Requests", "url": "https://dev.twitch.tv/docs/api/reference#resolve-unban-requests" }, "operationId": "resolve-unban-requests", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster whose channel is approving or denying the unban request.", "schema": { "type": "string" }, "required": true }, { "name": "moderator_id", "in": "query", "description": "The ID of the broadcaster or a user that has permission to moderate the broadcaster’s unban requests. This ID must match the user ID in the user access token.", "schema": { "type": "string" }, "required": true }, { "name": "unban_request_id", "in": "query", "description": "The ID of the broadcaster or a user that has permission to moderate the broadcaster’s unban requests. This ID must match the user ID in the user access token.", "schema": { "type": "string" }, "required": true }, { "name": "status", "in": "query", "description": "Resolution status. \n \n* approved\n* denied", "schema": { "type": "string" }, "required": true }, { "name": "resolution_text", "in": "query", "description": "Message supplied by the unban request resolver. The message is limited to a maximum of 500 characters.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully resolved the unban request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveUnbanRequestsResponse" }, "examples": { "Example": { "description": "_Request:_\n\nApproving an unban request.\n\n```bash\ncurl -X PATCH 'https://api.twitch.tv/helix/moderation/unban_requests?broadcaster_id=274637212&moderator_id=274637212&unban_request_id=92af127c-7326-4483-a52b-b0daa0be61c01&status=approved' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'`\n```", "value": { "data": [ { "id": "92af127c-7326-4483-a52b-b0da0be61c01", "broadcaster_name": "torpedo09", "broadcaster_login": "torpedo09", "broadcaster_id": "274637212", "moderator_id": "141981764", "moderator_login": "twitchdev", "moderator_name": "TwitchDev", "user_id": "424596340", "user_login": "quotrok", "user_name": "quotrok", "text": "Please unban me from the channel?", "status": "approved", "created_at": "2022-08-07T02:07:55Z", "resolved_at": "2022-08-09T02:07:55Z", "resolution_text": null } ] } } } } } }, "400": { "description": "* The _broadcaster\\_id_ query parameter is required.\n* The ID in the _broadcaster\\_id_ query parameter is not valid.\n* The _moderator\\_id_ query parameter is required.\n* The ID in the _moderator\\_id_ query parameter is not valid.\n* The pagination cursor is not valid.\n* The broadcaster is not receiving unban requests\n* Invalid requested update" }, "401": { "description": "* The ID in _moderator\\_id_ must match the user ID in the user access token.\n* The Authorization header is required and must contain a user access token.\n* The user access token must include the **moderator:manage:unban\\_requests** scope.\n* The access token is not valid.\n* The client ID specified in the Client-Id header does not match the client ID specified in the access token." }, "404": { "description": "The unban request ID was not found." } }, "security": [ { "twitch_auth": [ "moderator:manage:unban_requests" ] } ] } }, "/moderation/blocked_terms": { "get": { "summary": "Gets the broadcaster’s list of non-private, blocked words or phrases.", "description": "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.\n\n__Authorization:__\n\nRequires one of the following:\n\n* A [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **moderator:read:blocked\\_terms** or **moderator:manage:blocked\\_terms** scope.\n* BETA An [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens) where the application, through a prior authorization, has the **moderator:read:blocked\\_terms** or **moderator:manage:blocked\\_terms** scope for the user represented by the `moderator_id` query parameter.", "tags": [ "Moderation" ], "externalDocs": { "description": "Get Blocked Terms", "url": "https://dev.twitch.tv/docs/api/reference#get-blocked-terms" }, "operationId": "get-blocked-terms", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster whose blocked terms you’re getting.", "schema": { "type": "string" }, "required": true }, { "name": "moderator_id", "in": "query", "description": "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.", "schema": { "type": "string" }, "required": true }, { "name": "first", "in": "query", "description": "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.", "schema": { "type": "integer", "format": "int32" } }, { "name": "after", "in": "query", "description": "The cursor used to get the next page of results. The **Pagination** object in the response contains the cursor’s value.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the list of blocked terms.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetBlockedTermsResponse" }, "examples": { "Example": { "description": "_Request:_\n\nGets the last 10 blocked terms (see the _first_ query parameter) that were added.\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/moderation/blocked_terms?broadcaster_id=1234&moderator_id=5678&first=10' \\\n-H 'Authorization: Bearer f4otqljtpbpg24v41v9gechs4yvwy' \\\n-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh'\n```", "value": { "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..." } } } } } } }, "400": { "description": "* The _broadcaster\\_id_ query parameter is required.\n* The _moderator\\_id_ query parameter is required." }, "401": { "description": "* The ID in _moderator\\_id_ must match the user ID in the user access token.\n* The Authorization header must contain a user access token.\n* The user access token must include the **moderator:read:blocked\\_terms** scope.\n* The access token is not valid.\n* The client ID specified in the Client-Id header does not match the client ID specified in the access token." }, "403": { "description": "* The user in _moderator\\_id_ is not one of the broadcaster's moderators." } }, "security": [ { "twitch_auth": [ "moderator:read:blocked_terms", "moderator:manage:blocked_terms" ] } ] }, "post": { "summary": "Adds a word or phrase to the broadcaster’s list of blocked terms.", "description": "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.\n\n__Authorization:__\n\nRequires one of the following:\n\n* A [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **moderator:manage:blocked\\_terms** scope.\n* BETA An [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens) where the application, through a prior authorization, has the **moderator:manage:blocked\\_terms** scope for the user represented by the `moderator_id` query parameter.", "tags": [ "Moderation" ], "externalDocs": { "description": "Add Blocked Term", "url": "https://dev.twitch.tv/docs/api/reference#add-blocked-term" }, "operationId": "add-blocked-term", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster that owns the list of blocked terms.", "schema": { "type": "string" }, "required": true }, { "name": "moderator_id", "in": "query", "description": "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.", "schema": { "type": "string" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddBlockedTermBody" }, "examples": { "Example 1": { "value": { "text": "A phrase I’m not fond of" }, "description": "Adds a blocked term. Adding the same term again will return the previously added term." }, "Example 2": { "value": { "text": "crac*" }, "description": "Adds a term that uses the wildcard character (\\*)." } } } } }, "responses": { "200": { "description": "Successfully retrieved the list of blocked terms.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddBlockedTermResponse" }, "examples": { "Example 1": { "description": "_Request:_\n\nAdds a blocked term. Adding the same term again will return the previously added term.\n\n```bash\ncurl -X POST 'https://api.twitch.tv/helix/moderation/blocked_terms?broadcaster_id=1234&moderator_id=5678' \\\n-H 'Authorization: Bearer 789nj68b49pwqs9nh2y2jrlgzju3f' \\\n-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh' \\\n-H 'Content-Type: application/json' \\\n-d '{\"text\":\"A phrase I’m not fond of\"}'\n```", "value": { "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 2": { "description": "_Request:_\n\nAdds a term that uses the wildcard character (\\*).\n\n```bash\ncurl -X POST 'https://api.twitch.tv/helix/moderation/blocked_terms?broadcaster_id=1234&moderator_id=5678' \\\n-H 'Authorization: Bearer 789nj68b49pwqs9nh2y2jrlgzju3f' \\\n-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh' \\\n-H 'Content-Type: application/json' \\\n-d '{\"text\":\"crac*\"}'\n```", "value": { "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 } ] } } } } } }, "400": { "description": "* The _broadcaster\\_id_ query parameter is required.\n* The _moderator\\_id_ query parameter is required.\n* The `text` field is required.\n* The length of the term in the `text` field is either too short or too long." }, "401": { "description": "* The ID in _moderator\\_id_ must match the user ID in the user access token.\n* The Authorization header is required and must contain a user access token.\n* The user access token must include the **moderator:manage:blocked\\_terms** scope.\n* The access token is not valid.\n* The client ID specified in the Client-Id header does not match the client ID specified in the access token." }, "403": { "description": "* The user in _moderator\\_id_ is not one of the broadcaster's moderators." } }, "security": [ { "twitch_auth": [ "moderator:manage:blocked_terms" ] } ] }, "delete": { "summary": "Removes the word or phrase from the broadcaster’s list of blocked terms.", "description": "Removes the word or phrase from the broadcaster’s list of blocked terms.\n\n__Authorization:__\n\nRequires one of the following:\n\n* A [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **moderator:manage:blocked\\_terms** scope.\n* BETA An [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens) where the application, through a prior authorization, has the **moderator:manage:blocked\\_terms** scope for the user represented by the `moderator_id` query parameter.", "tags": [ "Moderation" ], "externalDocs": { "description": "Remove Blocked Term", "url": "https://dev.twitch.tv/docs/api/reference#remove-blocked-term" }, "operationId": "remove-blocked-term", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster that owns the list of blocked terms.", "schema": { "type": "string" }, "required": true }, { "name": "moderator_id", "in": "query", "description": "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.", "schema": { "type": "string" }, "required": true }, { "name": "id", "in": "query", "description": "The ID of the blocked term to remove from the broadcaster’s list of blocked terms.", "schema": { "type": "string" }, "required": true } ], "responses": { "204": { "description": "Successfully removed the blocked term. Also returned if the ID is not found.\n\n__Examples__\n\n_Request:_\n\nDeletes the specified blocked term.\n\n```bash\ncurl -X DELETE 'https://api.twitch.tv/helix/moderation/blocked_terms?broadcaster_id=1234&moderator_id=5678&id=c9fc79b8-0f63-4ef7-9d38-efd811e74ac2' \\ \n-H 'Authorization: Bearer f4otqljtpbpg24v41v9gechs4yvwy' \\\n-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh'\n```" }, "400": { "description": "* The _broadcaster\\_id_ query parameter is required.\n* The _moderator\\_id_ query parameter is required.\n* The _id_ query parameter is required." }, "401": { "description": "* The ID in _moderator\\_id_ must match the user ID in the user access token.\n* The Authorization header is required and must contain a user access token.\n* The user access token must include the **moderator:manage:blocked\\_terms** scope.\n* The access token is not valid.\n* The client ID specified in the Client-Id header does not match the client ID specified in the access token." }, "403": { "description": "* The user in _moderator\\_id_ is not one of the broadcaster's moderators." } }, "security": [ { "twitch_auth": [ "moderator:manage:blocked_terms" ] } ] } }, "/moderation/chat": { "delete": { "summary": "Removes a single chat message or all chat messages from the broadcaster’s chat room.", "description": "Removes a single chat message or all chat messages from the broadcaster’s chat room.\n\n__Authorization:__\n\nRequires one of the following:\n\n* A [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **moderator:manage:chat\\_messages** scope.\n* BETA An [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens) where the application, through a prior authorization, has the **moderator:manage:chat\\_messages** scope for the user represented by the `moderator_id` query parameter.", "tags": [ "Moderation" ], "externalDocs": { "description": "Delete Chat Messages", "url": "https://dev.twitch.tv/docs/api/reference#delete-chat-messages" }, "operationId": "delete-chat-messages", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster that owns the chat room to remove messages from.", "schema": { "type": "string" }, "required": true }, { "name": "moderator_id", "in": "query", "description": "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.", "schema": { "type": "string" }, "required": true }, { "name": "message_id", "in": "query", "description": "The ID of the message to remove. The `id` tag in the [PRIVMSG](https://dev.twitch.tv/docs/irc/tags#privmsg-tags) tag contains the message’s ID. Restrictions: \n \n* The message must have been created within the last 6 hours.\n* The message must not belong to the broadcaster.\n* The message must not belong to another moderator.\n \nIf not specified, the request removes all messages in the broadcaster’s chat room.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Successfully removed the specified messages.\n\n__Examples__\n\n_Request:_\n\nRemoves all messages from the broadcaster’s chat room (doesn’t include the _message\\_id_ query parameter).\n\n```bash\ncurl -X DELETE 'https://api.twitch.tv/helix/moderation/chat?broadcaster_id=11111&moderator_id=44444' \\\n-H 'Authorization: Bearer f4otqljtpbpg24v41v9gechs4yvwy' \\\n-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh'\n```\n\nRemoves the specified message from the broadcaster’s chat room.\n\n```bash\ncurl -X DELETE 'https://api.twitch.tv/helix/moderation/chat?broadcaster_id=11111&moderator_id=44444&message_id=abc-123-def' \\ \n-H 'Authorization: Bearer f4otqljtpbpg24v41v9gechs4yvwy' \\\n-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh'\n```" }, "400": { "description": "* You may not delete another moderator's messages.\n* You may not delete the broadcaster's messages." }, "401": { "description": "* The Authorization header is required and must contain a user access token.\n* The user access token is missing the **moderator:manage:chat\\_messages** scope.\n* The OAuth token is not valid.\n* The client ID specified in the Client-Id header does not match the client ID specified in the OAuth token." }, "403": { "description": "* The user in _moderator\\_id_ is not one of the broadcaster's moderators." }, "404": { "description": "* The ID in _message\\_id_ was not found.\n* The specified message was created more than 6 hours ago." } }, "security": [ { "twitch_auth": [ "moderator:manage:chat_messages" ] } ] } }, "/moderation/channels": { "get": { "summary": "Gets a list of channels that the specified user has moderator privileges in.", "description": "Gets a list of channels that the specified user has moderator privileges in.\n\n__Authorization:__\n\nRequires one of the following:\n\n* A [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **user:read:moderated\\_channels**. The user ID associated with the token must match the `user_id` in the query parameter.\n* BETA An [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens) where the application, through a prior authorization, has the **user:read:moderated\\_channels** scope for the user represented by the `user_id` query parameter.", "tags": [ "Moderation" ], "externalDocs": { "description": "Get Moderated Channels", "url": "https://dev.twitch.tv/docs/api/reference#get-moderated-channels" }, "operationId": "get-moderated-channels", "parameters": [ { "name": "user_id", "in": "query", "description": "A user’s ID. Returns the list of channels that this user has moderator privileges in. This ID must match the user ID in the user OAuth token", "schema": { "type": "string" }, "required": true }, { "name": "after", "in": "query", "description": "The cursor used to get the next page of results. The Pagination object in the response contains the cursor’s value.", "schema": { "type": "string" } }, { "name": "first", "in": "query", "description": "The maximum number of items to return per page in the response. \n \nMinimum page size is 1 item per page and the maximum is 100\\. The default is 20.", "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "Successfully retrieved the list of moderated channels.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetModeratedChannelsResponse" }, "examples": { "Example": { "description": "_Request:_\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/moderation/channels?user_id=931931' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```", "value": { "data": [ { "broadcaster_id": "12345", "broadcaster_login": "grateful_broadcaster", "broadcaster_name": "Grateful_Broadcaster" }, { "broadcaster_id": "98765", "broadcaster_login": "bashfulgamer", "broadcaster_name": "BashfulGamer" } ], "pagination": { "cursor": "eyJiIjpudWxsLCJhIjp7IkN1cnNvciI6IjEwMDQ3MzA2NDo4NjQwNjU3MToxSVZCVDFKMnY5M1BTOXh3d1E0dUdXMkJOMFcifX0" } } } } } } }, "400": { "description": "" }, "401": { "description": "" }, "500": { "description": "" } }, "security": [ { "twitch_auth": [ "user:read:moderated_channels" ] } ] } }, "/moderation/moderators": { "get": { "summary": "Gets all users allowed to moderate the broadcaster’s chat room.", "description": "Gets all users allowed to moderate the broadcaster’s chat room.\n\n__Authorization:__\n\nRequires a [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **moderation:read** scope. If your app also adds and removes moderators, you can use the **channel:manage:moderators** scope instead.", "tags": [ "Moderation" ], "externalDocs": { "description": "Get Moderators", "url": "https://dev.twitch.tv/docs/api/reference#get-moderators" }, "operationId": "get-moderators", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster whose list of moderators you want to get. This ID must match the user ID in the access token.", "schema": { "type": "string" }, "required": true }, { "name": "user_id", "in": "query", "description": "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. \n \nThe 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.", "schema": { "type": "array", "items": { "type": "string" } }, "explode": true }, { "name": "first", "in": "query", "description": "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.", "schema": { "type": "string" } }, { "name": "after", "in": "query", "description": "The cursor used to get the next page of results. The **Pagination** object in the response contains the cursor’s value. [Read More](https://dev.twitch.tv/docs/api/guide#pagination)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the list of moderators.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetModeratorsResponse" }, "examples": { "Example": { "description": "_Request:_\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/moderation/moderators?broadcaster_id=198704263' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```", "value": { "data": [ { "user_id": "424596340", "user_login": "quotrok", "user_name": "quotrok" } ], "pagination": { "cursor": "eyJiIjpudWxsLCJhIjp7IkN1cnNvciI6IjEwMDQ3MzA2NDo4NjQwNjU3MToxSVZCVDFKMnY5M1BTOXh3d1E0dUdXMkJOMFcifX0" } } } } } } }, "400": { "description": "* The _broadcaster\\_id_ query parameter is required." }, "401": { "description": "* The ID in _broadcaster\\_id_ must match the user ID found in the access token.\n* The Authorization header is required and must contain a user access token.\n* The user access token must include the **moderation:read** scope.\n* The access token is not valid.\n* The client ID specified in the Client-Id header does not match the client ID specified in the access token." } }, "security": [ { "twitch_auth": [ "moderation:read", "channel:manage:moderators" ] } ] }, "post": { "summary": "Adds a moderator to the broadcaster’s chat room.", "description": "Adds a moderator to the broadcaster’s chat room.\n\n**Rate Limits**: The broadcaster may add a maximum of 10 moderators within a 10-second window.\n\n__Authorization:__\n\nRequires a [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **channel:manage:moderators** scope.", "tags": [ "Moderation" ], "externalDocs": { "description": "Add Channel Moderator", "url": "https://dev.twitch.tv/docs/api/reference#add-channel-moderator" }, "operationId": "add-channel-moderator", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster that owns the chat room. This ID must match the user ID in the access token.", "schema": { "type": "string" }, "required": true }, { "name": "user_id", "in": "query", "description": "The ID of the user to add as a moderator in the broadcaster’s chat room.", "schema": { "type": "string" }, "required": true } ], "responses": { "204": { "description": "Successfully added the moderator.\n\n__Examples__\n\n_Request:_\n\n```bash\ncurl -X POST 'https://api.twitch.tv/helix/moderation/moderators?broadcaster_id=11111&user_id=44444' \\\n-H 'Authorization: Bearer kpvy3cjboyptmdkiacwr0c19hotn5s' \\\n-H 'Client-Id: hof5gwx0su6owfnys0nyan9c87zr6t'\n```" }, "400": { "description": "* The ID in _broadcaster\\_id_ was not found.\n* The ID in _user\\_id_ was not found.\n* The user in _user\\_id_ is already a moderator in the broadcaster's chat room.\n* The user in _user\\_id_ cannot become a moderator because they're banned from the channel." }, "401": { "description": "* The Authorization header is required and must contain a user access token.\n* The user access token must include the **channel:manage:moderators** scope.\n* The access token is not valid.\n* The ID in the _broadcaster\\_id_ query parameter must match the user ID in the access token.\n* The client ID specified in the Client-Id header does not match the client ID specified in the access token." }, "422": { "description": "* 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](https://dev.twitch.tv/docs/api/reference#remove-channel-vip))." }, "429": { "description": "* The broadcaster has exceeded the number of requests allowed within a 10-second window. See this endpoint's rate limits." } }, "security": [ { "twitch_auth": [ "channel:manage:moderators" ] } ] }, "delete": { "summary": "Removes a moderator from the broadcaster’s chat room.", "description": "Removes a moderator from the broadcaster’s chat room.\n\n**Rate Limits**: The broadcaster may remove a maximum of 10 moderators within a 10-second window.\n\n__Authorization:__\n\nRequires a [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **channel:manage:moderators** scope.", "tags": [ "Moderation" ], "externalDocs": { "description": "Remove Channel Moderator", "url": "https://dev.twitch.tv/docs/api/reference#remove-channel-moderator" }, "operationId": "remove-channel-moderator", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster that owns the chat room. This ID must match the user ID in the access token.", "schema": { "type": "string" }, "required": true }, { "name": "user_id", "in": "query", "description": "The ID of the user to remove as a moderator from the broadcaster’s chat room.", "schema": { "type": "string" }, "required": true } ], "responses": { "204": { "description": "Successfully removed the moderator.\n\n__Examples__\n\n_Request:_\n\n```bash\ncurl -X DELETE 'https://api.twitch.tv/helix/moderation/moderators?broadcaster_id=11111&user_id=44444' \\\n-H 'Authorization: Bearer kpvy3cjboyptmdkiacwr0c19hotn5s' \\\n-H 'Client-Id: hof5gwx0su6owfnys0nyan9c87zr6t'\n```" }, "400": { "description": "* The ID in _broadcaster\\_id_ was not found.\n* The ID in _user\\_id_ was not found.\n* The user in _user\\_id_ is not a moderator in the broadcaster's chat room." }, "401": { "description": "* The Authorization header is required and must contain a user access token.\n* The user access token must include the **channel:manage:moderators** scope.\n* The access token is not valid.\n* The ID in the _broadcaster\\_id_ query parameter must match the user ID in the access token.\n* The client ID specified in the Client-Id header does not match the client ID specified in the access token." }, "429": { "description": "* The broadcaster has exceeded the number of requests allowed within a 10-second window. See this endpoint's rate limits." } }, "security": [ { "twitch_auth": [ "channel:manage:moderators" ] } ] } }, "/channels/vips": { "get": { "summary": "Gets a list of the broadcaster’s VIPs.", "description": "Gets a list of the broadcaster’s VIPs.\n\n__Authorization:__\n\nRequires a [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) 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.", "tags": [ "Moderation" ], "externalDocs": { "description": "Get VIPs", "url": "https://dev.twitch.tv/docs/api/reference#get-vips" }, "operationId": "get-vips", "parameters": [ { "name": "user_id", "in": "query", "description": "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.", "schema": { "type": "array", "items": { "type": "string" } }, "explode": true }, { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster whose list of VIPs you want to get. This ID must match the user ID in the access token.", "schema": { "type": "string" }, "required": true }, { "name": "first", "in": "query", "description": "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.", "schema": { "type": "integer", "format": "int32" } }, { "name": "after", "in": "query", "description": "The cursor used to get the next page of results. The **Pagination** object in the response contains the cursor’s value. [Read More](https://dev.twitch.tv/docs/api/guide#pagination)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the broadcaster’s list of VIPs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetVIPsResponse" }, "examples": { "Example": { "description": "_Request:_\n\nGets a list of the broadcaster’s VIPs\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/channels/vips?broadcaster_id=123' \\\n-H 'Authorization: Bearer kpvy3cjboyptmdkiacwr0c19hotn5s' \\\n-H 'Client-Id: hof5gwx0su6owfnys0nyan9c87zr6t'\n```\n\nGets a filtered list of the broadcaster’s VIPs. The list in the response contains only those users that are VIPs.\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/channels/vips?broadcaster_id=123&user_id=456&user_id=678' \\\n-H 'Authorization: Bearer kpvy3cjboyptmdkiacwr0c19hotn5s' \\\n-H 'Client-Id: hof5gwx0su6owfnys0nyan9c87zr6t'\n```", "value": { "data": [ { "user_id": "11111", "user_name": "UserDisplayName", "user_login": "userloginname" } ], "pagination": { "cursor": "eyJiIjpudWxsLCJhIjp7Ik9mZnNldCI6NX19" } } } } } } }, "400": { "description": "* The _broadcaster\\_id_ query parameter is required.\n* The ID in the _user\\_id_ query parameter is not valid.\n* The number of _user\\_id_ query parameters exceeds the maximum allowed." }, "401": { "description": "* The Authorization header is required and must contain a user access token.\n* The user access token must include the **channel:read:vips** or **channel:manage:vips** scope.\n* The OAuth token is not valid.\n* The ID in the _broadcaster\\_id_ query parameter must match the user ID in the access token.\n* The client ID specified in the Client-Id header does not match the client ID specified in the OAuth token." } }, "security": [ { "twitch_auth": [ "channel:read:vips", "channel:manage:vips" ] } ] }, "post": { "summary": "Adds the specified user as a VIP in the broadcaster’s channel.", "description": "Adds the specified user as a VIP in the broadcaster’s channel.\n\n**Rate Limits**: The broadcaster may add a maximum of 10 VIPs within a 10-second window.\n\n__Authorization:__\n\nRequires a [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **channel:manage:vips** scope.", "tags": [ "Moderation" ], "externalDocs": { "description": "Add Channel VIP", "url": "https://dev.twitch.tv/docs/api/reference#add-channel-vip" }, "operationId": "add-channel-vip", "parameters": [ { "name": "user_id", "in": "query", "description": "The ID of the user to give VIP status to.", "schema": { "type": "string" }, "required": true }, { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster that’s adding the user as a VIP. This ID must match the user ID in the access token.", "schema": { "type": "string" }, "required": true } ], "responses": { "204": { "description": "Successfully added the VIP.\n\n__Examples__\n\n_Request:_\n\nAdds a VIP to the broadcaster’s chat room.\n\n```bash\ncurl -X POST 'https://api.twitch.tv/helix/channels/vips?broadcaster_id=123&user_id=456' \\\n-H 'Authorization: Bearer kpvy3cjboyptmdkiacwr0c19hotn5s' \\\n-H 'Client-Id: hof5gwx0su6owfnys0nyan9c87zr6t'\n```" }, "400": { "description": "* The user in the _user\\_id_ query parameter is blocked from the broadcaster's channel.\n* The ID in the _broadcaster\\_id_ query parameter is not valid.\n* The ID in the _user\\_id_ query parameter is not valid." }, "401": { "description": "* The Authorization header is required and must contain a user access token.\n* The user access token must include the **channel:manage:vips** scope.\n* The OAuth token is not valid.\n* The ID in the _broadcaster\\_id_ query parameter must match the user ID in the access token.\n* The client ID specified in the Client-Id header does not match the client ID specified in the OAuth token." }, "403": { "description": "* The ID in the _broadcaster\\_id_ query parameter must match the user ID in the access token." }, "404": { "description": "* The ID in _broadcaster\\_id_ was not found.\n* The ID in _user\\_id_ was not found." }, "409": { "description": "The broadcaster doesn’t have available VIP slots. [Read More](https://help.twitch.tv/s/article/Managing-Roles-for-your-Channel?language=en%5FUS#types)" }, "422": { "description": "* 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](https://dev.twitch.tv/docs/api/reference#remove-channel-moderator)).\n* The user in the _user\\_id_ query parameter is already a VIP." }, "425": { "description": "The broadcaster must complete the Build a Community requirement before they may assign VIPs." }, "429": { "description": "The broadcaster exceeded the number of VIP that they may add within a 10-second window. See Rate Limits for this endpoint above." } }, "security": [ { "twitch_auth": [ "channel:manage:vips" ] } ] }, "delete": { "summary": "Removes the specified user as a VIP in the broadcaster’s channel.", "description": "Removes the specified user as a VIP in the broadcaster’s channel.\n\nIf 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.\n\n**Rate Limits**: The broadcaster may remove a maximum of 10 VIPs within a 10-second window.\n\n__Authorization:__\n\nRequires a [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **channel:manage:vips** scope.", "tags": [ "Moderation" ], "externalDocs": { "description": "Remove Channel VIP", "url": "https://dev.twitch.tv/docs/api/reference#remove-channel-vip" }, "operationId": "remove-channel-vip", "parameters": [ { "name": "user_id", "in": "query", "description": "The ID of the user to remove VIP status from.", "schema": { "type": "string" }, "required": true }, { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster who owns the channel where the user has VIP status.", "schema": { "type": "string" }, "required": true } ], "responses": { "204": { "description": "Successfully removed the VIP status from the user.\n\n__Examples__\n\n_Request:_\n\nRemoves the VIP user from the broadcaster’s channel.\n\n```bash\ncurl -X DELETE 'https://api.twitch.tv/helix/channels/vips?broadcaster_id=123&user_id=456' \\\n-H 'Authorization: Bearer kpvy3cjboyptmdkiacwr0c19hotn5s' \\\n-H 'Client-Id: hof5gwx0su6owfnys0nyan9c87zr6t'\n```" }, "400": { "description": "* The ID in _broadcaster\\_id_ is not valid.\n* The ID in _user\\_id_ is not valid." }, "401": { "description": "* The Authorization header is required and must contain a user access token.\n* The user access token must include the **channel:manage:vips** scope.\n* The OAuth token is not valid.\n* The ID in the _broadcaster\\_id_ query parameter must match the user ID in the access token.\n* The client ID specified in the Client-Id header does not match the client ID specified in the OAuth token." }, "403": { "description": "* The user in _broadcaster\\_id_ doesn't have permission to remove the user's VIP status." }, "404": { "description": "* The ID in _broadcaster\\_id_ was not found.\n* The ID in _user\\_id_ was not found." }, "422": { "description": "* The user in _user\\_id_ is not a VIP in the broadcaster's channel." }, "429": { "description": "The broadcaster exceeded the number of VIPs that they may remove within a 10-second window. See Rate Limits for this endpoint above." } }, "security": [ { "twitch_auth": [ "channel:manage:vips" ] } ] } }, "/moderation/shield_mode": { "put": { "summary": "Activates or deactivates the broadcaster’s Shield Mode.", "description": "Activates or deactivates the broadcaster’s Shield Mode.\n\nTwitch’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.\n\n__Authorization:__\n\nRequires one of the following:\n\n* A [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **moderator:manage:shield\\_mode** scope. The user ID associated with the token must match the `moderator_id` in the query parameter.\n* BETA An [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens) where the application, through a prior authorization, has the **moderator:manage:shield\\_mode** scope for the user represented by the `moderator_id` query parameter.", "tags": [ "Moderation" ], "externalDocs": { "description": "Update Shield Mode Status", "url": "https://dev.twitch.tv/docs/api/reference#update-shield-mode-status" }, "operationId": "update-shield-mode-status", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster whose Shield Mode you want to activate or deactivate.", "schema": { "type": "string" }, "required": true }, { "name": "moderator_id", "in": "query", "description": "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.", "schema": { "type": "string" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateShieldModeStatusBody" }, "examples": { "Example": { "value": { "is_active": false } } } } } }, "responses": { "200": { "description": "Successfully updated the broadcaster’s Shield Mode status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateShieldModeStatusResponse" }, "examples": { "Example": { "description": "_Request:_\n\n```bash\ncurl -X PUT 'https://api.twitch.tv/helix/moderation/shield_mode?broadcaster_id=12345&moderator_id=98765' \\\n-H 'Authorization: Bearer kpvy3cjboypmiacwr0c19hotn5s' \\\n-H 'Client-Id: hof5gwx0su6owfn0yan9c87zr6t' \\\n-H 'Content-Type: application/json' \\\n-d '{\"is_active\":false}'\n```", "value": { "data": [ { "is_active": false, "moderator_id": "98765", "moderator_name": "SimplySimple", "moderator_login": "simplysimple", "last_activated_at": "2022-07-26T17:16:03.123Z" } ] } } } } } }, "400": { "description": "* The _broadcaster\\_id_ query parameter is required.\n* The ID in the _broadcaster\\_id_ query parameter is not valid.\n* The `is_active` field is required.\n* The value in the `is_active` field is not valid." }, "401": { "description": "* The ID in _moderator\\_id_ must match the user ID in the user access token.\n* The Authorization header is required and must contain a user access token.\n* The user access token must include the **moderator:manage:shield\\_mode** scope.\n* The access token is not valid.\n* The client ID specified in the Client-Id header does not match the client ID specified in the access token." }, "403": { "description": "* The user in _moderator\\_id_ is not one of the broadcaster's moderators." } }, "security": [ { "twitch_auth": [ "moderator:manage:shield_mode" ] } ] }, "get": { "summary": "Gets the broadcaster’s Shield Mode activation status.", "description": "Gets the broadcaster’s Shield Mode activation status.\n\nTo receive notification when the broadcaster activates and deactivates Shield Mode, subscribe to the [channel.shield\\_mode.begin](https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelshield%5Fmodebegin) and [channel.shield\\_mode.end](https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelshield%5Fmodeend) subscription types.\n\n__Authorization:__\n\nRequires one of the following:\n\n* A [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **moderator:read:shield\\_mode** or **moderator:manage:shield\\_mode** scope. The user ID associated with the token must match the `moderator_id` in the query parameter.\n* BETA An [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens) where the application, through a prior authorization, has the **moderator:read:shield\\_mode** or **moderator:manage:shield\\_mode** scope for the user represented by the `moderator_id` query parameter.", "tags": [ "Moderation" ], "externalDocs": { "description": "Get Shield Mode Status", "url": "https://dev.twitch.tv/docs/api/reference#get-shield-mode-status" }, "operationId": "get-shield-mode-status", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster whose Shield Mode activation status you want to get.", "schema": { "type": "string" }, "required": true }, { "name": "moderator_id", "in": "query", "description": "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.", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Successfully retrieved the broadcaster’s Shield Mode activation status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetShieldModeStatusResponse" }, "examples": { "Example": { "description": "_Request:_\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/moderation/shield_mode?broadcaster_id=12345&moderator_id=98765' \\\n-H 'Authorization: Bearer kpvy3cjboypmiacwr0c19hotn5s' \\\n-H 'Client-Id: hof5gwx0su6owfn0yan9c87zr6t'\n```", "value": { "data": [ { "is_active": true, "moderator_id": "98765", "moderator_name": "SimplySimple", "moderator_login": "simplysimple", "last_activated_at": "2022-07-26T17:16:03.123Z" } ] } } } } } }, "400": { "description": "* The _broadcaster\\_id_ query parameter is required.\n* The ID in the _broadcaster\\_id_ query parameter is not valid." }, "401": { "description": "* The ID in _moderator\\_id_ must match the user ID in the user access token.\n* The Authorization header is required and must contain a user access token.\n* The user access token must include the **moderator:read:shield\\_mode** or **moderator:manage:shield\\_mode** scope.\n* The access token is not valid.\n* The client ID specified in the Client-Id header does not match the client ID specified in the access token." }, "403": { "description": "* The user in _moderator\\_id_ is not one of the broadcaster's moderators." } }, "security": [ { "twitch_auth": [ "moderator:read:shield_mode", "moderator:manage:shield_mode" ] } ] } }, "/moderation/warnings": { "post": { "summary": "Warns a user in the specified broadcaster’s chat room, preventing them from chat interaction until the warning is acknowledged.", "description": "Warns a user in the specified broadcaster’s chat room, preventing them from chat interaction until the warning is acknowledged. New warnings can be issued to a user when they already have a warning in the channel (new warning will replace old warning).\n\n__Authorization:__\n\nRequires one of the following:\n\n* A [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **moderator:manage:warnings** scope. The user ID associated with the token must match the `moderator_id` in the query parameter.\n* BETA An [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens) where the application, through a prior authorization, has the **moderator:manage:warnings** scope for the user represented by the `moderator_id` query parameter.", "tags": [ "Moderation" ], "externalDocs": { "description": "Warn Chat User", "url": "https://dev.twitch.tv/docs/api/reference#warn-chat-user" }, "operationId": "warn-chat-user", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The ID of the channel in which the warning will take effect.", "schema": { "type": "string" }, "required": true }, { "name": "moderator_id", "in": "query", "description": "The ID of the twitch user who requested the warning.", "schema": { "type": "string" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WarnChatUserBody" }, "examples": { "Example": { "value": { "data": { "user_id": "9876", "reason": "stop doing that!" } } } } } } }, "responses": { "200": { "description": "Successfully warn a user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WarnChatUserResponse" }, "examples": { "Example": { "description": "_Request:_\n\n```bash\ncurl -X POST 'https://api.twitch.tv/helix/moderation/warnings?broadcaster_id=404040&moderator_id=404041' \\\n-H 'Authorization: Bearer 4a4x78f5wqvkybms7mxfist3jmzul' \\\n-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh' \\\n-H 'Content-Type: application/json' \\\n-d '{\"data\": {\"user_id\":\"9876\",\"reason\":\"stop doing that!\"}}'\n```", "value": { "data": [ { "broadcaster_id": "404040", "user_id": "9876", "moderator_id": "404041", "reason": "stop doing that!" } ] } } } } } }, "400": { "description": "* The _broadcaster\\_id_ query parameter is required.\n* The _moderator\\_id_ query parameter is required.\n* The _user\\_id_ query parameter is required.\n* The _reason_ query parameter is required.\n* The text in the _reason_ field is too long.\n* The user specified in the _user\\_id_ may not be warned." }, "401": { "description": "* The ID in _moderator\\_id_ must match the user ID in the user access token.\n* The Authorization header is required and must contain a user access token.\n* The user access token must include the **moderator:manage:warnings** scope.\n* The access token is not valid.\n* The client ID specified in the Client-Id header does not match the client ID specified in the access token." }, "403": { "description": "The user in _moderator\\_id_ is not one of the broadcaster’s moderators." }, "409": { "description": "You may not update the user’s warning state while someone else is updating the state. For example, someone else is currently warning the user or the user is acknowledging an existing warning. Please retry your request." }, "429": { "description": "The app has exceeded the number of requests it may make per minute for this broadcaster." }, "500": { "description": "Internal Server Error." } }, "security": [ { "twitch_auth": [ "moderator:manage:warnings" ] } ] } }, "/moderation/suspicious_users": { "post": { "summary": "NEW Adds a suspicious user status to a chatter on the broadcaster’s channel.", "description": "NEW Adds a suspicious user status to a chatter on the broadcaster’s channel.\n\n__Authorization:__\n\nRequires an [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens) or [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **moderator:manage:suspicious\\_users** scope.", "tags": [ "Moderation" ], "externalDocs": { "description": "Add Suspicious Status to Chat User", "url": "https://dev.twitch.tv/docs/api/reference#add-suspicious-status-to-chat-user" }, "operationId": "add-suspicious-status-to-chat-user", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The user ID of the broadcaster, indicating the channel where the status is being applied.", "schema": { "type": "string" }, "required": true }, { "name": "moderator_id", "in": "query", "description": "The user ID of the moderator who is applying the status.", "schema": { "type": "string" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddSuspiciousStatusToChatUserBody" }, "examples": { "Example": { "value": { "user_id": "9876", "status": "RESTRICTED" }, "description": "Mark a user as RESTRICTED." } } } } }, "responses": { "200": { "description": "Successfully applied a suspicious user status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddSuspiciousStatusToChatUserResponse" }, "examples": { "Example": { "description": "_Request:_\n\nMark a user as RESTRICTED.\n\n```bash\ncurl -X POST 'https://api.twitch.tv/helix/moderation/suspicious_users?broadcaster_id=141981764&moderator_id=12826' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \\\n-H 'Content-Type: application/json' \\\n-d '{\n \"user_id\": \"9876\",\n \"status\": \"RESTRICTED\"\n}'\n```", "value": { "data": [ { "user_id": "9876", "broadcaster_id": "141981764", "moderator_id": "12826", "updated_at": "2025-12-01T23:08:18+00:00", "status": "RESTRICTED", "types": [ "MANUALLY_ADDED" ] } ] } } } } } }, "400": { "description": "* Validation errors: Missing required fields.\n* The ID in the broadcaster\\_id query parameter was not found.\n* The status specified was invalid. Must either be ACTIVE\\_MONITORING or RESTRICTED\n* The status update is not allowed for this user." }, "401": { "description": "* The Authorization header is required and must specify user access token.\n* The user access token must include the **moderator:manage:suspicious\\_users** scope.\n* The OAuth token is not valid.\n* The ID in the Client-Id header must match the Client ID in the OAuth token." }, "403": { "description": "* The user in the moderator\\_id query parameter is not one of the broadcaster's moderators." } }, "security": [ { "twitch_auth": [ "moderator:manage:suspicious_users" ] } ] }, "delete": { "summary": "NEW Remove a suspicious user status from a chatter on broadcaster’s channel.", "description": "NEW Remove a suspicious user status from a chatter on broadcaster’s channel.\n\n__Authorization:__\n\nRequires an [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens) or [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **moderator:manage:suspicious\\_users** scope.", "tags": [ "Moderation" ], "externalDocs": { "description": "Remove Suspicious Status From Chat User", "url": "https://dev.twitch.tv/docs/api/reference#remove-suspicious-status-from-chat-user" }, "operationId": "remove-suspicious-status-from-chat-user", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The user ID of the broadcaster, indicating the channel where the status is being removed.", "schema": { "type": "string" }, "required": true }, { "name": "moderator_id", "in": "query", "description": "The user ID of the moderator who is removing the status.", "schema": { "type": "string" }, "required": true }, { "name": "user_id", "in": "query", "description": "The ID of the user having the suspicious status removed.", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Successfully removed a suspicious user status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveSuspiciousStatusFromChatUserResponse" }, "examples": { "Example": { "description": "_Request:_\n\nRemoves a suspicious user status from a user.\n\n```bash\ncurl -X DELETE 'https://api.twitch.tv/helix/moderation/suspicious_users?broadcaster_id=141981764&moderator_id=12826&user_id=9876' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```", "value": { "data": [ { "user_id": "9876", "broadcaster_id": "141981764", "moderator_id": "12826", "updated_at": "2025-12-01T23:08:18+00:00", "status": "NO_TREATMENT", "types": [ "MANUALLY_ADDED" ] } ] } } } } } }, "400": { "description": "* Validation errors: Missing required fields.\n* The ID in the broadcaster\\_id query parameter was not found.\n* The status update is not allowed for this user." }, "401": { "description": "* The Authorization header is required and must specify user access token.\n* The user access token must include the **moderator:manage:suspicious\\_users** scope.\n* The OAuth token is not valid.\n* The ID in the Client-Id header must match the Client ID in the OAuth token." }, "403": { "description": "* The user in the moderator\\_id query parameter is not one of the broadcaster's moderators." } }, "security": [ { "twitch_auth": [ "moderator:manage:suspicious_users" ] } ] } }, "/polls": { "get": { "summary": "Gets a list of polls that the broadcaster created.", "description": "Gets a list of polls that the broadcaster created.\n\nPolls are available for 90 days after they’re created.\n\n__Authorization:__\n\nRequires a [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **channel:read:polls** or **channel:manage:polls** scope.", "tags": [ "Polls" ], "externalDocs": { "description": "Get Polls", "url": "https://dev.twitch.tv/docs/api/reference#get-polls" }, "operationId": "get-polls", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster that created the polls. This ID must match the user ID in the user access token.", "schema": { "type": "string" }, "required": true }, { "name": "id", "in": "query", "description": "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. \n \nSpecify 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.", "schema": { "type": "array", "items": { "type": "string" } }, "explode": true }, { "name": "first", "in": "query", "description": "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.", "schema": { "type": "string" } }, { "name": "after", "in": "query", "description": "The cursor used to get the next page of results. The **Pagination** object in the response contains the cursor’s value. [Read More](https://dev.twitch.tv/docs/api/guide#pagination)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the broadcaster's polls.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPollsResponse" }, "examples": { "Example": { "description": "_Request:_\n\nGets the specified broadcaster’s list of polls.\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/polls?broadcaster_id=141981764&id=ed961efd-8a3f-4cf5-a9d0-e616c590cd2a' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```", "value": { "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": {} } } } } } }, "400": { "description": "* The _broadcaster\\_id_ query parameter is required." }, "401": { "description": "* The ID in _broadcaster\\_id_ must match the user ID in the access token.\n* The Authorization header is required and must contain a user access token.\n* The user access token is missing the **channel:read:polls** scope.\n* The access token is not valid.\n* The client ID specified in the Client-Id header must match the client ID specified in the access token." }, "404": { "description": "* None of the IDs in the _id_ query parameters were found." } }, "security": [ { "twitch_auth": [ "channel:read:polls", "channel:manage:polls" ] } ] }, "post": { "summary": "Creates a poll that viewers in the broadcaster’s channel can vote on.", "description": "Creates a poll that viewers in the broadcaster’s channel can vote on.\n\nThe poll begins as soon as it’s created. You may run only one poll at a time.\n\n__Authorization:__\n\nRequires a [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **channel:manage:polls** scope.", "tags": [ "Polls" ], "externalDocs": { "description": "Create Poll", "url": "https://dev.twitch.tv/docs/api/reference#create-poll" }, "operationId": "create-poll", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePollBody" }, "examples": { "Example": { "value": { "broadcaster_id": "141981764", "title": "Heads or Tails?", "choices": [ { "title": "Heads" }, { "title": "Tails" } ], "channel_points_voting_enabled": true, "channel_points_per_vote": 100, "duration": 1800 }, "description": "Creates a poll for the specified broadcaster." } } } } }, "responses": { "200": { "description": "Successfully created the poll.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePollResponse" }, "examples": { "Example": { "description": "_Request:_\n\nCreates a poll for the specified broadcaster.\n\n```bash\ncurl -X POST 'https://api.twitch.tv/helix/polls' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \\\n-H 'Content-Type: application/json' \\\n-d '{\n \"broadcaster_id\":\"141981764\",\n \"title\":\"Heads or Tails?\",\n \"choices\":[{\n \"title\":\"Heads\"\n },\n {\n \"title\":\"Tails\"\n }],\n \"channel_points_voting_enabled\":true,\n \"channel_points_per_vote\":100,\n \"duration\":1800\n}'\n```", "value": { "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" } ] } } } } } }, "400": { "description": "* The `broadcaster_id` field is required.\n* The `title` field is required.\n* The `choices` field is required.\n* The `duration` field is required.\n* The value in `duration` is outside the allowed range of values.\n* The value in `channel_points_per_vote` is outside the allowed range of values.\n* The value in `bits_per_vote` is outside the allowed range of values.\n* The poll's `title` is too long.\n* The choice's `title` is too long.\n* The choice's `title` failed AutoMod checks.\n* The number of choices in the poll may not be less than 2 or greater that 5.\n* The broadcaster already has a poll that's running; you may not create another poll until the current poll completes." }, "401": { "description": "* The ID in `broadcaster_id` must match the user ID in the access token.\n* The Authorization header is required and must contain a user access token.\n* The user access token is missing the **channel:manage:polls** scope.\n* The access token is not valid.\n* The client ID specified in the Client-Id header does not match the client ID specified in the access token." } }, "security": [ { "twitch_auth": [ "channel:manage:polls" ] } ] }, "patch": { "summary": "End an active poll.", "description": "Ends an active poll. You have the option to end it or end it and archive it.\n\n__Authorization:__\n\nRequires a [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **channel:manage:polls** scope.", "tags": [ "Polls" ], "externalDocs": { "description": "End Poll", "url": "https://dev.twitch.tv/docs/api/reference#end-poll" }, "operationId": "end-poll", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndPollBody" }, "examples": { "Example": { "value": { "broadcaster_id": "141981764", "id": "ed961efd-8a3f-4cf5-a9d0-e616c590cd2a", "status": "TERMINATED" }, "description": "Ends the specific poll, but allows the results to be visible for viewers." } } } } }, "responses": { "200": { "description": "Successfully ended the poll.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndPollResponse" }, "examples": { "Example": { "description": "_Request:_\n\nEnds the specific poll, but allows the results to be visible for viewers.\n\n```bash\ncurl -X PATCH 'https://api.twitch.tv/helix/polls' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \\\n-H 'Content-Type: application/json' \\\n-d '{\n \"broadcaster_id\":\"141981764\",\n \"id\":\"ed961efd-8a3f-4cf5-a9d0-e616c590cd2a\",\n \"status\":\"TERMINATED\"\n}'\n```", "value": { "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" } ] } } } } } }, "400": { "description": "* The `broadcaster_id` field is required.\n* The `id` field is required.\n* The `status` field is required.\n* The value in the `status` field is not valid.\n* The poll must be active to terminate or archive it." }, "401": { "description": "* The ID in `broadcaster_id` must match the user ID in the user access token.\n* The Authorization header is required and must contain a user access token.\n* The user access token must include the **channel:manage:polls** scope.\n* The access token is not valid.\n* The client ID specified in the Client-Id header must match the client ID specified in the access token." } }, "security": [ { "twitch_auth": [ "channel:manage:polls" ] } ] } }, "/predictions": { "get": { "summary": "Gets a list of Channel Points Predictions that the broadcaster created.", "description": "Gets a list of Channel Points Predictions that the broadcaster created.\n\n__Authorization:__\n\nRequires a [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **channel:read:predictions** or **channel:manage:predictions** scope.", "tags": [ "Predictions" ], "externalDocs": { "description": "Get Predictions", "url": "https://dev.twitch.tv/docs/api/reference#get-predictions" }, "operationId": "get-predictions", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster whose predictions you want to get. This ID must match the user ID in the user access token.", "schema": { "type": "string" }, "required": true }, { "name": "id", "in": "query", "description": "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.", "schema": { "type": "array", "items": { "type": "string" } }, "explode": true }, { "name": "first", "in": "query", "description": "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.", "schema": { "type": "string" } }, { "name": "after", "in": "query", "description": "The cursor used to get the next page of results. The **Pagination** object in the response contains the cursor’s value. [Read More](https://dev.twitch.tv/docs/api/guide#pagination)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the list of predictions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPredictionsResponse" }, "examples": { "Example": { "description": "_Request:_\n\nGets the specified broadcaster’s list of predictions.\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/predictions?broadcaster_id=55696719&id=d6676d5c-c86e-44d2-bfc4-100fb48f0656' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```", "value": { "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": {} } } } } } }, "400": { "description": "* The _broadcaster\\_id_ query parameter is required." }, "401": { "description": "* The ID in _broadcaster\\_id_ must match the user ID in the access token.\n* The Authorization header is required and must contain a user access token.\n* The user access token must include the **channel:read:predictions** scope.\n* The access token is not valid.\n* The client ID specified in the Client-Id header does not match the client ID specified in the access token." } }, "security": [ { "twitch_auth": [ "channel:read:predictions", "channel:manage:predictions" ] } ] }, "post": { "summary": "Create a Channel Points Prediction.", "description": "Creates a Channel Points Prediction.\n\nWith 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.\n\n__Authorization:__\n\nRequires a [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **channel:manage:predictions** scope.", "tags": [ "Predictions" ], "externalDocs": { "description": "Create Prediction", "url": "https://dev.twitch.tv/docs/api/reference#create-prediction" }, "operationId": "create-prediction", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePredictionBody" }, "examples": { "Example": { "value": { "broadcaster_id": "141981764", "title": "Any leeks in the stream?", "outcomes": [ { "title": "Yes, give it time." }, { "title": "Definitely not." } ], "prediction_window": 120 }, "description": "Creates a Channel Points Prediction for the specified broadcaster." } } } } }, "responses": { "200": { "description": "Successfully created the Channel Points Prediction.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePredictionResponse" }, "examples": { "Example": { "description": "_Request:_\n\nCreates a Channel Points Prediction for the specified broadcaster.\n\n```bash\ncurl -X POST 'https://api.twitch.tv/helix/predictions' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \\\n-H 'Content-Type: application/json' \\\n-d '{\n \"broadcaster_id\": \"141981764\",\n \"title\": \"Any leeks in the stream?\",\n \"outcomes\": [\n {\n \"title\": \"Yes, give it time.\"\n },\n {\n \"title\": \"Definitely not.\"\n }\n ],\n \"prediction_window\": 120\n}'\n```", "value": { "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 } ] } } } } } }, "400": { "description": "* The `broadcaster_id` field is required.\n* The `title` field is required.\n* The `outcomes` field is required.\n* The `prediction_window` field is required.\n* The value in `prediction_window` is outside the allowed range of values.\n* The prediction's `title` is too long.\n* The outcome's `title` is too long.\n* The outcome's `title` failed AutoMod checks.\n* There must be 2 outcomes in the prediction.\n* The broadcaster already has a prediction that's running; you may not create another prediction until the current prediction is resolved or canceled." }, "401": { "description": "* The ID in `broadcaster_id` must match the user ID in the access token.\n* The Authorization header is required and must contain a user access token.\n* The user access token must include the **channel:manage:predictions** scope.\n* The access token is not valid.\n* The client ID specified in the Client-Id header does not match the client ID specified in the access token." }, "429": { "description": "" } }, "security": [ { "twitch_auth": [ "channel:manage:predictions" ] } ] }, "patch": { "summary": "Locks, resolves, or cancels a Channel Points Prediction.", "description": "Locks, resolves, or cancels a Channel Points Prediction.\n\n__Authorization:__\n\nRequires a [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **channel:manage:predictions** scope.", "tags": [ "Predictions" ], "externalDocs": { "description": "End Prediction", "url": "https://dev.twitch.tv/docs/api/reference#end-prediction" }, "operationId": "end-prediction", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndPredictionBody" } } } }, "responses": { "200": { "description": "Successfully ended the prediction.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndPredictionResponse" }, "examples": { "Example": { "description": "_Request:_\n\nResolves the specified Channel Points Prediction.\n\n```bash\ncurl -X PATCH 'https://api.twitch.tv/helix/predictions' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \\\n-H 'Content-Type: application/json' \\\n-d '{\n \"broadcaster_id\": \"141981764\",\n \"id\": \"bc637af0-7766-4525-9308-4112f4cbf178\",\n \"status\": \"RESOLVED\",\n \"winning_outcome_id\": \"73085848-a94d-4040-9d21-2cb7a89374b7\"\n}'\n```", "value": { "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" } ] } } } } } }, "400": { "description": "* The `broadcaster_id` field is required.\n* The `id` field is required.\n* The `status` field is required.\n* The `winning_outcome_id` field is required if `status` is RESOLVED.\n* The value in the `status` field is not valid.\n* To update the prediction's status to RESOLVED or CANCELED, its current status must be ACTIVE or LOCKED.\n* To update the prediction's status to LOCKED, its current status must be ACTIVE." }, "401": { "description": "* The ID in `broadcaster_id` must match the user ID in the OAuth token.\n* The Authorization header is required and must contain a user access token.\n* The user access token must include the **channel:manage:predictions** scope.\n* The access token is not valid.\n* The client ID specified in the Client-Id header does not match the client ID specified in the access token." }, "404": { "description": "* The prediction in the `id` field was not found.\n* The outcome in the `winning_outcome_id` field was not found." } }, "security": [ { "twitch_auth": [ "channel:manage:predictions" ] } ] } }, "/raids": { "post": { "summary": "Raid another channel by sending the broadcaster’s viewers to the targeted channel.", "description": "Raid another channel by sending the broadcaster’s viewers to the targeted channel.\n\nWhen 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.\n\nTo determine whether the raid successfully occurred, you must subscribe to the [Channel Raid](https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelraid) event. For more information, see [Get notified when a raid begins](https://dev.twitch.tv/docs/api/raids#get-notified-when-a-raid-begins).\n\nTo cancel a pending raid, use the [Cancel a raid](https://dev.twitch.tv/docs/api/reference#cancel-a-raid) endpoint.\n\n**Rate Limit**: The limit is 10 requests within a 10-minute window.\n\n__Authorization:__\n\nRequires a [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **channel:manage:raids** scope.", "tags": [ "Raids" ], "externalDocs": { "description": "Start a raid", "url": "https://dev.twitch.tv/docs/api/reference#start-a-raid" }, "operationId": "start-a-raid", "parameters": [ { "name": "from_broadcaster_id", "in": "query", "description": "The ID of the broadcaster that’s sending the raiding party. This ID must match the user ID in the user access token.", "schema": { "type": "string" } }, { "name": "to_broadcaster_id", "in": "query", "description": "The ID of the broadcaster to raid.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "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](https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelraid) event.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartARaidResponse" }, "examples": { "Example": { "description": "_Request:_\n\n```bash\ncurl -X POST 'https://api.twitch.tv/helix/raids?from_broadcaster_id=12345678&to_broadcaster_id=87654321' \\\n-H 'Authorization: Bearer kpvy3cjboyptmdkiacwr0c19hotn5s' \\\n-H 'Client-Id: hof5gwx0su6owfnys0nyan9c87zr6t'\n```", "value": { "data": [ { "created_at": "2022-02-18T07:20:50.52Z", "is_mature": false } ] } } } } } }, "400": { "description": "* The raiding broadcaster is blocked from the targeted channel.\n* The targeted channel doesn't accept raids from this broadcaster.\n* There are too many viewers in the raiding party.\n* The IDs in _from\\_broadcaster\\_id_ and _to\\_broadcaster\\_id_ cannot be the same ID.\n* The ID in the _from\\_broadcaster\\_id_ query parameter is not valid.\n* The ID in the _to\\_broadcaster\\_id_ query parameter is not valid." }, "401": { "description": "* The ID in _from\\_broadcaster\\_id_ must match the user ID found in the request’s OAuth token.\n* The Authorization header is required and must contain a user access token.\n* The user access token must include the **channel:manage:raids** scope.\n* The access token is not valid.\n* The client ID specified in the Client-Id header does not match the client ID specified in the access token." }, "404": { "description": "* The targeted channel was not found." }, "409": { "description": "* The broadcaster is already in the process of raiding another channel." }, "429": { "description": "* The broadcaster exceeded the number of raid requests that they may make. The limit is 10 requests within a 10-minute window." } }, "security": [ { "twitch_auth": [ "channel:manage:raids" ] } ] }, "delete": { "summary": "Cancel a pending raid.", "description": "Cancel a pending raid.\n\nYou can cancel a raid at any point up until the broadcaster clicks **Raid Now** in the Twitch UX or the 90-second countdown expires.\n\n**Rate Limit**: The limit is 10 requests within a 10-minute window.\n\n__Authorization:__\n\nRequires a [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **channel:manage:raids** scope.", "tags": [ "Raids" ], "externalDocs": { "description": "Cancel a raid", "url": "https://dev.twitch.tv/docs/api/reference#cancel-a-raid" }, "operationId": "cancel-a-raid", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster that initiated the raid. This ID must match the user ID in the user access token.", "schema": { "type": "string" }, "required": true } ], "responses": { "204": { "description": "The pending raid was successfully canceled.\n\n__Examples__\n\n_Request:_\n\n```bash\ncurl -X DELETE 'https://api.twitch.tv/helix/raids?broadcaster_id=12345678' \\\n-H 'Authorization: Bearer kpvy3cjboyptmdkiacwr0c19hotn5s' \\\n-H 'Client-Id: hof5gwx0su6owfnys0nyan9c87zr6t'\n```" }, "400": { "description": "* The ID in the _broadcaster\\_id_ query parameter is not valid." }, "401": { "description": "* The ID in _broadcaster\\_id_ must match the user ID found in the request’s OAuth token.\n* The Authorization header is required and must contain a user access token.\n* The user access token must include the **channel:manage:raids** scope.\n* The access token is not valid.\n* The client ID specified in the Client-Id header does not match the client ID specified in the access token." }, "404": { "description": "* The broadcaster doesn't have a pending raid to cancel." }, "429": { "description": "* The broadcaster exceeded the number of raid requests that they may make. The limit is 10 requests within a 10-minute window." } }, "security": [ { "twitch_auth": [ "channel:manage:raids" ] } ] } }, "/schedule": { "get": { "summary": "Gets the broadcaster’s streaming schedule.", "description": "Gets the broadcaster’s streaming schedule. You can get the entire schedule or specific segments of the schedule. [Learn More](https://help.twitch.tv/s/article/channel-page-setup#Schedule)\n\n__Authorization:__\n\nRequires an [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens) or [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens).", "tags": [ "Schedule" ], "externalDocs": { "description": "Get Channel Stream Schedule", "url": "https://dev.twitch.tv/docs/api/reference#get-channel-stream-schedule" }, "operationId": "get-channel-stream-schedule", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster that owns the streaming schedule you want to get.", "schema": { "type": "string" }, "required": true }, { "name": "id", "in": "query", "description": "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.", "schema": { "type": "array", "items": { "type": "string" } }, "explode": true }, { "name": "start_time", "in": "query", "description": "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`).", "schema": { "type": "string", "format": "date-time" } }, { "name": "utc_offset", "in": "query", "description": "Not supported.", "schema": { "type": "string" } }, { "name": "first", "in": "query", "description": "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.", "schema": { "type": "integer", "format": "int32" } }, { "name": "after", "in": "query", "description": "The cursor used to get the next page of results. The **Pagination** object in the response contains the cursor’s value. [Read More](https://dev.twitch.tv/docs/api/guide#pagination)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the broadcaster’s streaming schedule.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetChannelStreamScheduleResponse" }, "examples": { "Example": { "description": "_Request:_\n\nGets the specified broadcaster’s streaming schedule.\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/schedule?broadcaster_id=141981764' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```", "value": { "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": {} } } } } } }, "400": { "description": "* The _broadcaster\\_id_ query parameter is required.\n* The ID in the _broadcaster\\_id_ query parameter is not valid.\n* The ID in the _id_ query parameter is not valid.\n* The format of the date and time in the _start\\_time_ query parameter is not valid." }, "401": { "description": "* The Authorization header is required and must specify a valid app access token or user access token.\n* The access token is not valid.\n* The ID in the Client-Id header must match the Client ID in the access token." }, "403": { "description": "* Only partners and affiliates may add non-recurring broadcast segments." }, "404": { "description": "* The broadcaster has not created a streaming schedule." } }, "security": [ { "twitch_auth": [] } ] } }, "/schedule/icalendar": { "get": { "summary": "Gets the broadcaster’s streaming schedule as an iCalendar.", "description": "Gets the broadcaster’s streaming schedule as an [iCalendar](https://datatracker.ietf.org/doc/html/rfc5545).\n\n__Authorization:__\n\nThe Client-Id and Authorization headers are not required.\n\n__Response Body:__\n\nThe response body contains the iCalendar data (see [RFC5545](https://datatracker.ietf.org/doc/html/rfc5545)).\n\nThe Content-Type response header is set to `text/calendar`.", "tags": [ "Schedule" ], "externalDocs": { "description": "Get Channel iCalendar", "url": "https://dev.twitch.tv/docs/api/reference#get-channel-icalendar" }, "operationId": "get-channel-icalendar", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster that owns the streaming schedule you want to get.", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Successfully retrieved the broadcaster’s schedule as an iCalendar.", "content": { "text/calendar": { "examples": { "Example": { "description": "_Request:_\n\nGets the specified broadcaster’s streaming schedule as an iCalendar.\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/schedule/icalendar?broadcaster_id=141981764'\n```", "value": "BEGIN:VCALENDAR\nPRODID:-//twitch.tv//StreamSchedule//1.0\nVERSION:2.0\nCALSCALE:GREGORIAN\nREFRESH-INTERVAL;VALUE=DURATION:PT1H\nNAME:TwitchDev\nBEGIN:VEVENT\nUID:e4acc724-371f-402c-81ca-23ada79759d4\nDTSTAMP:20210323T040131Z\nDTSTART;TZID=/America/New_York:20210701T140000\nDTEND;TZID=/America/New_York:20210701T150000\nSUMMARY:TwitchDev Monthly Update // July 1, 2021\nDESCRIPTION:Science & Technology.\nCATEGORIES:Science & Technology\nEND:VEVENT\nEND:VCALENDAR%" } } } } }, "400": { "description": "* The _broadcaster\\_id_ query parameter is required.\n* The ID in the _broadcaster\\_id_ query parameter is not valid." } } } }, "/schedule/settings": { "patch": { "summary": "Updates the broadcaster’s schedule settings, such as scheduling a vacation.", "description": "Updates the broadcaster’s schedule settings, such as scheduling a vacation.\n\n__Authorization:__\n\nRequires a [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **channel:manage:schedule** scope.", "tags": [ "Schedule" ], "externalDocs": { "description": "Update Channel Stream Schedule", "url": "https://dev.twitch.tv/docs/api/reference#update-channel-stream-schedule" }, "operationId": "update-channel-stream-schedule", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster whose schedule settings you want to update. The ID must match the user ID in the user access token.", "schema": { "type": "string" }, "required": true }, { "name": "is_vacation_enabled", "in": "query", "description": "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.", "schema": { "type": "boolean" } }, { "name": "vacation_start_time", "in": "query", "description": "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**.", "schema": { "type": "string", "format": "date-time" } }, { "name": "vacation_end_time", "in": "query", "description": "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**.", "schema": { "type": "string", "format": "date-time" } }, { "name": "timezone", "in": "query", "description": "The time zone that the broadcaster broadcasts from. Specify the time zone using [IANA time zone database](https://www.iana.org/time-zones) format (for example, America/New\\_York). Required if _is\\_vacation\\_enabled_ is **true**.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Successfully updated the broadcaster’s schedule settings.\n\n__Examples__\n\n_Request:_\n\nSchedules the broadcaster’s vacation.\n\n```bash\ncurl -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' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```" }, "400": { "description": "* The _broadcaster\\_id_ query parameter is required.\n* The ID in the _broadcaster\\_id_ query parameter is not valid.\n* The format of the string in _vacation\\_start\\_time_ is not valid.\n* The format of the string in _vacation\\_end\\_time_ is not valid.\n* The date in _vacation\\_end\\_time_ must be later than the date in _vacation\\_start\\_time_." }, "401": { "description": "* The ID in the _broadcaster\\_id_ query parameter must match the user ID in the user access token.\n* The Authorization header is required and must contain a user access token.\n* The user access token must include the **channel:manage:schedule** scope.\n* The access token is not valid.\n* The ID in the Client-Id header must match the client ID in the access token." }, "404": { "description": "* The broadcaster's schedule was not found." } }, "security": [ { "twitch_auth": [ "channel:manage:schedule" ] } ] } }, "/schedule/segment": { "post": { "summary": "Adds a single or recurring broadcast to the broadcaster’s streaming schedule.", "description": "Adds a single or recurring broadcast to the broadcaster’s streaming schedule. For information about scheduling broadcasts, see [Stream Schedule](https://help.twitch.tv/s/article/channel-page-setup#Schedule).\n\n__Authorization:__\n\nRequires a [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **channel:manage:schedule** scope.", "tags": [ "Schedule" ], "externalDocs": { "description": "Create Channel Stream Schedule Segment", "url": "https://dev.twitch.tv/docs/api/reference#create-channel-stream-schedule-segment" }, "operationId": "create-channel-stream-schedule-segment", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "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.", "schema": { "type": "string" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateChannelStreamScheduleSegmentBody" }, "examples": { "Example": { "value": { "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" }, "description": "Adds a non-recurring broadcast to the broadcaster’s streaming schedule." } } } } }, "responses": { "200": { "description": "Successfully added the broadcast segment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateChannelStreamScheduleSegmentResponse" }, "examples": { "Example": { "description": "_Request:_\n\nAdds a non-recurring broadcast to the broadcaster’s streaming schedule.\n\n```bash\ncurl -X POST 'https://api.twitch.tv/helix/schedule/segment?broadcaster_id=141981764' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \\\n-H 'Content-Type: application/json' \\\n-d '{\n \"start_time\": \"2021-07-01T18:00:00Z\",\n \"timezone\": \"America/New_York\",\n \"is_recurring\": false,\n \"duration\": \"60\",\n \"category_id\": \"509670\",\n \"title\": \"TwitchDev Monthly Update // July 1, 2021\"\n}'\n```", "value": { "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 } } } } } } }, "400": { "description": "* The _broadcaster\\_id_ query parameter is required.\n* The ID in the _broadcaster\\_id_ query parameter is not valid.\n* The format of the date and time in the `start_time` field is not valid.\n* The value in the `timezone` field is not valid.\n* The value in the `duration` field is not valid.\n* The ID in the `category_id` field is not valid.\n* The string in the `title` field is too long." }, "401": { "description": "* The ID in the _broadcaster\\_id_ query parameter must match the user ID in the user access token.\n* The Authorization header is required and must contain a user access token.\n* The user access token must include the **channel:manage:schedule** scope.\n* The access token is not valid.\n* The ID in the Client-Id header must match the client ID in the access token." }, "403": { "description": "* Only partners and affiliates may add non-recurring broadcast segments." } }, "security": [ { "twitch_auth": [ "channel:manage:schedule" ] } ] }, "patch": { "summary": "Updates a scheduled broadcast segment.", "description": "Updates a scheduled broadcast segment.\n\nFor recurring segments, updating a segment’s title, category, duration, and timezone, changes all segments in the recurring schedule, not just the specified segment.\n\n__Authorization:__\n\nRequires a [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **channel:manage:schedule** scope.", "tags": [ "Schedule" ], "externalDocs": { "description": "Update Channel Stream Schedule Segment", "url": "https://dev.twitch.tv/docs/api/reference#update-channel-stream-schedule-segment" }, "operationId": "update-channel-stream-schedule-segment", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster who owns the broadcast segment to update. This ID must match the user ID in the user access token.", "schema": { "type": "string" }, "required": true }, { "name": "id", "in": "query", "description": "The ID of the broadcast segment to update.", "schema": { "type": "string" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateChannelStreamScheduleSegmentBody" }, "examples": { "Example": { "value": { "duration": "120" }, "description": "Updates the duration of a non-recurring broadcast segment." } } } } }, "responses": { "200": { "description": "Successfully updated the broadcast segment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateChannelStreamScheduleSegmentResponse" }, "examples": { "Example": { "description": "_Request:_\n\nUpdates the duration of a non-recurring broadcast segment.\n\n```bash\ncurl -X PATCH 'https://api.twitch.tv/helix/schedule/segment?broadcaster_id=141981764&id=eyJzZWdtZW50SUQiOiJlNGFjYzcyNC0zNzFmLTQwMmMtODFjYS0yM2FkYTc5NzU5ZDQiLCJpc29ZZWFyIjoyMDIxLCJpc29XZWVrIjoyNn0=' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n-H 'Content-Type: application/json' \\\n-d '{\n \"duration\": \"120\"\n}'\n```", "value": { "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 } } } } } } }, "400": { "description": "* The _broadcaster\\_id_ query parameter is required.\n* The ID in the _broadcaster\\_id_ query parameter is not valid.\n* The _id_ query parameter is required.\n* The ID in the _id_ query parameter is not valid.\n* The format of the date and time in the `start_time` field is not valid.\n* The value in the `timezone` field is not valid.\n* The value in the `duration` field is not valid.\n* The ID in the `category_id` field is not valid.\n* The string in the `title` field is too long." }, "401": { "description": "* The ID in the _broadcaster\\_id_ query parameter must match the user ID in the user access token.\n* The Authorization header is required and must contain a user access token.\n* The user access token must include the **channel:manage:schedule** scope.\n* The access token is not valid.\n* The ID in the Client-Id header must match the client ID in the access token." }, "404": { "description": "* The specified broadcast segment was not found." } }, "security": [ { "twitch_auth": [ "channel:manage:schedule" ] } ] }, "delete": { "summary": "Deletes a broadcast from the broadcaster’s streaming schedule.", "description": "Removes a broadcast segment from the broadcaster’s streaming schedule.\n\n**NOTE**: For recurring segments, removing a segment removes all segments in the recurring schedule.\n\n__Authorization:__\n\nRequires a [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **channel:manage:schedule** scope.", "tags": [ "Schedule" ], "externalDocs": { "description": "Delete Channel Stream Schedule Segment", "url": "https://dev.twitch.tv/docs/api/reference#delete-channel-stream-schedule-segment" }, "operationId": "delete-channel-stream-schedule-segment", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster that owns the streaming schedule. This ID must match the user ID in the user access token.", "schema": { "type": "string" }, "required": true }, { "name": "id", "in": "query", "description": "The ID of the broadcast segment to remove.", "schema": { "type": "string" }, "required": true } ], "responses": { "204": { "description": "Successfully removed the broadcast segment.\n\n__Examples__\n\n_Request:_\n\nRemoves the segment from the broadcaster’s streaming schedule.\n\n```bash\ncurl -X DELETE 'https://api.twitch.tv/helix/schedule/segment?broadcaster_id=141981764&id=eyJzZWdtZW50SUQiOiI4Y2EwN2E2NC0xYTZkLTRjYWItYWE5Ni0xNjIyYzNjYWUzZDkiLCJpc29ZZWFyIjoyMDIxLCJpc29XZWVrIjoyMX0=' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```" }, "400": { "description": "* The _broadcaster\\_id_ query parameter is required.\n* The ID in the _broadcaster\\_id_ query parameter is not valid.\n* The _id_ query parameter is required.\n* The ID in the _id_ query parameter is not valid." }, "401": { "description": "* The ID in the _broadcaster\\_id_ query parameter must match the user ID in the user access token.\n* The Authorization header is required and must contain a user access token.\n* The user access token must include the **channel:manage:schedule** scope.\n* The access token is not valid.\n* The ID in the Client-Id header must match the client ID in the OAuth token." } }, "security": [ { "twitch_auth": [ "channel:manage:schedule" ] } ] } }, "/search/categories": { "get": { "summary": "Gets the games or categories that match the specified query.", "description": "Gets the games or categories that match the specified query.\n\nTo 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.\n\n__Authorization:__\n\nRequires an [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens) or [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens).", "tags": [ "Search" ], "externalDocs": { "description": "Search Categories", "url": "https://dev.twitch.tv/docs/api/reference#search-categories" }, "operationId": "search-categories", "parameters": [ { "name": "query", "in": "query", "description": "The URI-encoded search string. For example, encode _#archery_ as `%23archery` and search strings like _angel of death_ as `angel%20of%20death`.", "schema": { "type": "string" }, "required": true }, { "name": "first", "in": "query", "description": "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.", "schema": { "type": "integer", "format": "int32" } }, { "name": "after", "in": "query", "description": "The cursor used to get the next page of results. The **Pagination** object in the response contains the cursor’s value. [Read More](https://dev.twitch.tv/docs/api/guide#pagination)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the list of category names that matched the specified query string.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchCategoriesResponse" }, "examples": { "Example": { "description": "_Request:_\n\nGets the list of games and categories that contain _fort_ in the name.\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/search/categories?query=fort' \\\n-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \\\n-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'\n```", "value": { "data": [ { "id": "33214", "name": "Fortnite", "box_art_url": "https://static-cdn.jtvnw.net/ttv-boxart/33214-52x72.jpg" } ], "pagination": { "cursor": "eyJiIjpudWxsLCJhIjp7IkN" } } } } } } }, "400": { "description": "* The _query_ query parameter is required." }, "401": { "description": "* The Authorization header is required and must contain an app access token or user access token.\n* The access token is not valid.\n* The client ID specified in the Client-Id header does not match the client ID specified in the access token." } }, "security": [ { "twitch_auth": [] } ] } }, "/search/channels": { "get": { "summary": "Gets the channels that match the specified query and have streamed content within the past 6 months.", "description": "Gets the channels that match the specified query and have streamed content within the past 6 months.\n\nThe 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.\n\nTo 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.\n\nBy default, the results include both live and offline channels. To get only live channels set the _live\\_only_ query parameter to **true**.\n\n__Authorization:__\n\nRequires an [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens) or [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens).", "tags": [ "Search" ], "externalDocs": { "description": "Search Channels", "url": "https://dev.twitch.tv/docs/api/reference#search-channels" }, "operationId": "search-channels", "parameters": [ { "name": "query", "in": "query", "description": "The URI-encoded search string. For example, encode search strings like _angel of death_ as `angel%20of%20death`.", "schema": { "type": "string" }, "required": true }, { "name": "live_only", "in": "query", "description": "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**.", "schema": { "type": "boolean" } }, { "name": "first", "in": "query", "description": "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.", "schema": { "type": "integer", "format": "int32" } }, { "name": "after", "in": "query", "description": "The cursor used to get the next page of results. The **Pagination** object in the response contains the cursor’s value. [Read More](https://dev.twitch.tv/docs/api/guide#pagination)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the list of category names that matched the specified query string.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchChannelsResponse" }, "examples": { "Example 1": { "description": "_Request:_\n\nGets the list of live and offline channels where the broadcaster’s name contains _twitchdev_.\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/search/channels?query=twitchdev' \\\n-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \\\n-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'\n```", "value": { "data": [ { "broadcaster_language": "en", "broadcaster_login": "twitchdev", "display_name": "TwitchDev", "game_id": "1469308723", "game_name": "Software and Game Development", "id": "141981764", "is_live": false, "tag_ids": [], "tags": [ "WebDevelopment", "GameDevelopment", "SoftwareDevelopment", "English" ], "thumbnail_url": "https://static-cdn.jtvnw.net/jtv_user_pictures/8a6381c7-d0c0-4576-b179-38bd5ce1d6af-profile_image-300x300.png", "title": "Standard Output", "started_at": "" } ], "pagination": { "cursor": "Mg==" } } }, "Example 2": { "description": "_Request:_\n\nGets the list of live channels where the broadcaster’s name or category name contains _a\\_seagull_.\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/search/channels?query=a_seagull&live_only=true' \\\n-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \\\n-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'\n```", "value": { "data": [ { "broadcaster_language": "en", "broadcaster_login": "a_seagull", "display_name": "A_Seagull", "game_id": "506442", "game_name": "DOOM Eternal", "id": "19070311", "is_live": true, "tag_ids": [], "tags": [ "English" ], "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": {} } } } } } }, "400": { "description": "* The _query_ query parameter is required." }, "401": { "description": "* The Authorization header is required and must contain an app access token or user access token.\n* The access token is not valid.\n* The client ID specified in the Client-Id header does not match the client ID specified in the access token." } }, "security": [ { "twitch_auth": [] } ] } }, "/streams/key": { "get": { "summary": "Gets the channel’s stream key.", "description": "Gets the channel’s stream key.\n\n__Authorization:__\n\nRequires a [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **channel:read:stream\\_key** scope.", "tags": [ "Streams" ], "externalDocs": { "description": "Get Stream Key", "url": "https://dev.twitch.tv/docs/api/reference#get-stream-key" }, "operationId": "get-stream-key", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster that owns the channel. The ID must match the user ID in the access token.", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Successfully retrieved the stream’s key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetStreamKeyResponse" }, "examples": { "Example": { "description": "_Request:_\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/streams/key?broadcaster_id=141981764' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```", "value": { "data": [ { "stream_key": "live_44322889_a34ub37c8ajv98a0" } ] } } } } } }, "400": { "description": "* The _broadcaster\\_id_ field is required.\n* The ID in the _broadcaster\\_id_ field is not valid." }, "401": { "description": "* The ID in _broadcaster\\_id_ must match the user ID in the access token.\n* The Authorization header is required and must contain a user access token.\n* The user access token must include the **channel:read:stream\\_key** scope.\n* The access token is not valid.\n* The client ID specified in the Client-Id header must match the client ID specified in the access token." }, "403": { "description": "The user must complete additional steps in order to stream. Present the user with the returned error message." } }, "security": [ { "twitch_auth": [ "channel:read:stream_key" ] } ] } }, "/streams": { "get": { "summary": "Gets a list of all streams.", "description": "Gets a list of all streams. 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.\n\n__Authorization:__\n\nRequires an [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens) or [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens).", "tags": [ "Streams" ], "externalDocs": { "description": "Get Streams", "url": "https://dev.twitch.tv/docs/api/reference#get-streams" }, "operationId": "get-streams", "parameters": [ { "name": "user_id", "in": "query", "description": "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`.", "schema": { "type": "array", "items": { "type": "string" } }, "explode": true }, { "name": "user_login", "in": "query", "description": "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`.", "schema": { "type": "array", "items": { "type": "string" } }, "explode": true }, { "name": "game_id", "in": "query", "description": "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`.", "schema": { "type": "array", "items": { "type": "string" } }, "explode": true }, { "name": "type", "in": "query", "description": "The type of stream to filter the list of streams by. Possible values are: \n \n* all\n* live\n \nThe default is _all_.", "schema": { "type": "string", "enum": [ "all", "live" ] } }, { "name": "language", "in": "query", "description": "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](https://help.twitch.tv/s/article/languages-on-twitch#streamlang). \n \nYou 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`.", "schema": { "type": "array", "items": { "type": "string" } }, "explode": true }, { "name": "first", "in": "query", "description": "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.", "schema": { "type": "integer", "format": "int32" } }, { "name": "before", "in": "query", "description": "The cursor used to get the previous page of results. The **Pagination** object in the response contains the cursor’s value. [Read More](https://dev.twitch.tv/docs/api/guide#pagination)", "schema": { "type": "string" } }, { "name": "after", "in": "query", "description": "The cursor used to get the next page of results. The **Pagination** object in the response contains the cursor’s value. [Read More](https://dev.twitch.tv/docs/api/guide#pagination)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the list of streams.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetStreamsResponse" }, "examples": { "Example 1": { "description": "_Request:_\n\nGets information about the 20 most active streams.\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/streams' \\\n-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \\\n-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'\n```", "value": { "data": [ { "id": "123456789", "user_id": "98765", "user_login": "sandysanderman", "user_name": "SandySanderman", "game_id": "494131", "game_name": "Little Nightmares", "type": "live", "title": "hablamos y le damos a Little Nightmares 1", "tags": [ "Español" ], "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": [], "is_mature": false } ], "pagination": { "cursor": "eyJiIjp7IkN1cnNvciI6ImV5SnpJam8zT0RNMk5TNDBORFF4TlRjMU1UY3hOU3dpWkNJNlptRnNjMlVzSW5RaU9uUnlkV1Y5In0sImEiOnsiQ3Vyc29yIjoiZXlKeklqb3hOVGs0TkM0MU56RXhNekExTVRZNU1ESXNJbVFpT21aaGJITmxMQ0owSWpwMGNuVmxmUT09In19" } } }, "Example 2": { "description": "_Request:_\n\nGets streams for the specified logins. If the user is not live, the response doesn’t include them.\n\n```bash\ncurl -X GET\n'https://api.twitch.tv/helix/streams?user_login=afro&user_login=cohhcarnage&user_login=lana_lux' \\\n-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```", "value": { "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", "tags": [ "English" ], "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": [], "is_mature": false } ], "pagination": {} } } } } } }, "400": { "description": "* The value in the _type_ query parameter is not valid." }, "401": { "description": "* The Authorization header is required and must specify an app access token or user access token.\n* The access token is not valid.\n* The ID in the Client-Id header must match the Client ID in the access token." } }, "security": [ { "twitch_auth": [] } ] } }, "/streams/followed": { "get": { "summary": "Gets the list of broadcasters that the user follows and that are streaming live.", "description": "Gets the list of broadcasters that the user follows and that are streaming live.\n\n__Authorization:__\n\nRequires a [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **user:read:follows** scope.", "tags": [ "Streams" ], "externalDocs": { "description": "Get Followed Streams", "url": "https://dev.twitch.tv/docs/api/reference#get-followed-streams" }, "operationId": "get-followed-streams", "parameters": [ { "name": "user_id", "in": "query", "description": "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.", "schema": { "type": "string" }, "required": true }, { "name": "first", "in": "query", "description": "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.", "schema": { "type": "integer", "format": "int32" } }, { "name": "after", "in": "query", "description": "The cursor used to get the next page of results. The **Pagination** object in the response contains the cursor’s value. [Read More](https://dev.twitch.tv/docs/api/guide#pagination)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the list of broadcasters that the user follows and that are streaming live.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetFollowedStreamsResponse" }, "examples": { "Example": { "description": "_Request:_\n\nGets the streams that the broadcaster follows.\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/streams/followed?user_id=141981764' \\\n-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \\\n-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'\n```", "value": { "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": [], "tags": [ "English" ] } ], "pagination": { "cursor": "eyJiIjp7IkN1cnNvciI6ImV5SnpJam8zT0RNMk5TNDBORFF4TlRjMU1UY3hOU3dpWkNJNlptRnNjMlVzSW5RaU9uUnlkV1Y5In0sImEiOnsiQ3Vyc29yIjoiZXlKeklqb3hOVGs0TkM0MU56RXhNekExTVRZNU1ESXNJbVFpT21aaGJITmxMQ0owSWpwMGNuVmxmUT09In19" } } } } } } }, "400": { "description": "* The _user\\_id_ query parameter is required." }, "401": { "description": "* The ID in _user\\_id_ must match the user ID found in the access token.\n* The Authorization header is required and must contain a user access token.\n* The user access token must include the **user:read:follows** scope.\n* The OAuth token is not valid.\n* The client ID specified in the Client-Id header does not match the client ID specified in the access token." } }, "security": [ { "twitch_auth": [ "user:read:follows" ] } ] } }, "/streams/markers": { "post": { "summary": "Adds a marker to a live stream.", "description": "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).\n\nYou may not add markers:\n\n* If the stream is not live\n* If the stream has not enabled video on demand (VOD)\n* If the stream is a premiere (a live, first-viewing event that combines uploaded videos with live chat)\n* If the stream is a rerun of a past broadcast, including past premieres.\n\n__Authorization:__\n\nRequires a [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **channel:manage:broadcast** scope.", "tags": [ "Streams" ], "externalDocs": { "description": "Create Stream Marker", "url": "https://dev.twitch.tv/docs/api/reference#create-stream-marker" }, "operationId": "create-stream-marker", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateStreamMarkerBody" }, "examples": { "Example": { "value": { "user_id": "123", "description": "hello, this is a marker!" }, "description": "Creates a marker at the current location in user 123’s stream." } } } } }, "responses": { "200": { "description": "Successfully created the marker.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateStreamMarkerResponse" }, "examples": { "Example": { "description": "_Request:_\n\nCreates a marker at the current location in user 123’s stream.\n\n```bash\ncurl -X POST 'https://api.twitch.tv/helix/streams/markers' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \\\n-H 'Content-Type: application/json' \\\n-d '{\"user_id\":\"123\", \"description\":\"hello, this is a marker!\"}'\n```", "value": { "data": [ { "id": 123, "created_at": "2018-08-20T20:10:03Z", "description": "hello, this is a marker!", "position_seconds": 244 } ] } } } } } }, "400": { "description": "* The `user_id` field is required.\n* The length of the string in the `description` field is too long." }, "401": { "description": "* The Authorization header is required and must contain a user access token.\n* The user access token must include the **user:manage:broadcast** scope.\n* The access token is not valid.\n* The client ID specified in the Client-Id header does not match the client ID specified in the access token." }, "403": { "description": "* 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": { "description": "* The user in the `user_id` field is not streaming live.\n* The ID in the user\\_id field is not valid.\n* The user hasn't enabled video on demand (VOD)." } }, "security": [ { "twitch_auth": [ "channel:manage:broadcast" ] } ] }, "get": { "summary": "Gets a list of markers from the user’s most recent stream or from the specified VOD/video.", "description": "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).\n\n__Authorization:__\n\nRequires a [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **user:read:broadcast** or **channel:manage:broadcast** scope.", "tags": [ "Streams" ], "externalDocs": { "description": "Get Stream Markers", "url": "https://dev.twitch.tv/docs/api/reference#get-stream-markers" }, "operationId": "get-stream-markers", "parameters": [ { "name": "user_id", "in": "query", "description": "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. \n \nThis parameter and the _video\\_id_ query parameter are mutually exclusive.", "schema": { "type": "string" } }, { "name": "video_id", "in": "query", "description": "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. \n \nThis parameter and the _user\\_id_ query parameter are mutually exclusive.", "schema": { "type": "string" } }, { "name": "first", "in": "query", "description": "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.", "schema": { "type": "string" } }, { "name": "before", "in": "query", "description": "The cursor used to get the previous page of results. The **Pagination** object in the response contains the cursor’s value. [Read More](https://dev.twitch.tv/docs/api/guide#pagination)", "schema": { "type": "string" } }, { "name": "after", "in": "query", "description": "The cursor used to get the next page of results. The **Pagination** object in the response contains the cursor’s value. [Read More](https://dev.twitch.tv/docs/api/guide#pagination)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the list of markers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetStreamMarkersResponse" }, "examples": { "Example": { "description": "_Request:_\n\nGets the first 5 markers in the most recent stream of user 123.\n\n```bash\ncurl -X GET\n'https://api.twitch.tv/helix/streams/markers?user_id=123&first=5' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```", "value": { "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" } } } } } } }, "400": { "description": "* The request must specify either the _user\\_id_ or _video\\_id_ query parameter, but not both." }, "401": { "description": "* The Authorization header is required and must contain a user access token.\n* The user access token must include the **user:read:broadcast** or **user:manage:broadcast** scope.\n* The access token is not valid.\n* The client ID specified in the Client-Id header does not match the client ID specified in the access token." }, "403": { "description": "* 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": { "description": "* The user specified in the _user\\_id_ query parameter doesn't have videos." } }, "security": [ { "twitch_auth": [ "user:read:broadcast", "channel:manage:broadcast" ] } ] } }, "/subscriptions": { "get": { "summary": "Gets a list of users that subscribe to the specified broadcaster.", "description": "Gets a list of users that subscribe to the specified broadcaster.\n\n__Authorization:__\n\nRequires a [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **channel:read:subscriptions** scope.\n\nA Twitch extensions may use an app access token if the broadcaster has granted the **channel:read:subscriptions** scope from within the Twitch Extensions manager.", "tags": [ "Subscriptions" ], "externalDocs": { "description": "Get Broadcaster Subscriptions", "url": "https://dev.twitch.tv/docs/api/reference#get-broadcaster-subscriptions" }, "operationId": "get-broadcaster-subscriptions", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The broadcaster’s ID. This ID must match the user ID in the access token.", "schema": { "type": "string" }, "required": true }, { "name": "user_id", "in": "query", "description": "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.", "schema": { "type": "array", "items": { "type": "string" } }, "explode": true }, { "name": "first", "in": "query", "description": "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.", "schema": { "type": "string" } }, { "name": "after", "in": "query", "description": "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](https://dev.twitch.tv/docs/api/guide#pagination)", "schema": { "type": "string" } }, { "name": "before", "in": "query", "description": "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](https://dev.twitch.tv/docs/api/guide#pagination)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the broadcaster’s list of subscribers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetBroadcasterSubscriptionsResponse" }, "examples": { "Example": { "description": "_Request:_\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/subscriptions?broadcaster_id=141981764' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```", "value": { "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 } } } } } }, "400": { "description": "* The _broadcaster\\_id_ query parameter is required." }, "401": { "description": "* The ID in _broadcaster\\_id_ must match the user ID found in the request’s OAuth token.\n* The Authorization header is required and must contain a user access token.\n* The user access token must include the **channel:read:subscriptions** scope.\n* The access token is not valid.\n* The client ID specified in the Client-Id header does not match the client ID specified in the access token." } }, "security": [ { "twitch_auth": [ "channel:read:subscriptions" ] } ] } }, "/subscriptions/user": { "get": { "summary": "Checks whether the user subscribes to the broadcaster’s channel.", "description": "Checks whether the user subscribes to the broadcaster’s channel.\n\n__Authorization:__\n\nRequires a [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **user:read:subscriptions** scope.\n\nA Twitch extensions may use an app access token if the broadcaster has granted the **user:read:subscriptions** scope from within the Twitch Extensions manager.", "tags": [ "Subscriptions" ], "externalDocs": { "description": "Check User Subscription", "url": "https://dev.twitch.tv/docs/api/reference#check-user-subscription" }, "operationId": "check-user-subscription", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The ID of a partner or affiliate broadcaster.", "schema": { "type": "string" }, "required": true }, { "name": "user_id", "in": "query", "description": "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.", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "The user subscribes to the broadcaster.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckUserSubscriptionResponse" }, "examples": { "Example": { "description": "_Request:_\n\nChecks whether the user subscribes to the broadcaster’s channel.\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/subscriptions/user?broadcaster_id=149747285&user_id=141981764' \\\n-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \\\n-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'\n```", "value": { "data": [ { "broadcaster_id": "149747285", "broadcaster_name": "TwitchPresents", "broadcaster_login": "twitchpresents", "is_gift": false, "tier": "1000" } ] } } } } } }, "400": { "description": "* The _broadcaster\\_id_ query parameter is required.\n* The _user\\_id_ query parameter is required." }, "401": { "description": "* The ID in _user\\_id_ must match the user ID found in the request’s OAuth token.\n* The Authorization header is required and must contain a user access token.\n* The user access token must include the **user:read:subscriptions** scope.\n* The access token is not valid.\n* The client ID specified in the Client-Id header does not match the client ID specified in the access token." }, "404": { "description": "* The user in _user\\_id_ does not subscribe to the broadcaster in _broadcaster\\_id_." } }, "security": [ { "twitch_auth": [ "user:read:subscriptions" ] } ] } }, "/tags/streams": { "get": { "summary": "Gets the list of all stream tags that Twitch defines. You can also filter the list by one or more tag IDs.", "description": "**IMPORTANT** Twitch is moving from Twitch-defined tags to channel-defined tags. **IMPORTANT** As of February 28, 2023, this endpoint returns an empty array. On July 13, 2023, it will return a 410 response.\n\nGets 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](https://www.twitch.tv/directory/all/tags).\n\n__Authorization:__\n\nRequires an [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens) or [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens).", "tags": [ "Tags" ], "externalDocs": { "description": "Get All Stream Tags", "url": "https://dev.twitch.tv/docs/api/reference#get-all-stream-tags" }, "operationId": "get-all-stream-tags", "parameters": [ { "name": "tag_id", "in": "query", "description": "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.", "schema": { "type": "array", "items": { "type": "string" } }, "explode": true }, { "name": "first", "in": "query", "description": "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.", "schema": { "type": "integer", "format": "int32" } }, { "name": "after", "in": "query", "description": "The cursor used to get the next page of results. The **Pagination** object in the response contains the cursor’s value. [Read More](https://dev.twitch.tv/docs/api/guide#pagination)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the list of tags.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAllStreamTagsResponse" }, "examples": { "Example": { "description": "_Request:_\n\nGets the first page of stream tags that Twitch defines.\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/tags/streams' \\\n-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```\n\n```bash\n# Twitch CLI example that gets the first page of stream tags.\ntwitch api get /tags/streams\n\n# Twitch CLI example that gets the specified stream tags.\ntwitch api get /tags/streams -q tag_id=39490173-ed5f-4271-96a8-26ab546ee1e9 -q tag_id=233f4789-1ad0-403c-aaf9-7d37a22264e7\n```", "value": { "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..." } } } } } } }, "400": { "description": "* The _tag\\_id_ query parameter is empty (for example, `&tag_id=`).\n* The list of tag IDs is too long." }, "401": { "description": "* The Authorization header is required and must specify an app access token or user access token.\n* The access token is not valid.\n* The ID in the Client-Id header must match the Client ID in the access token." } }, "security": [ { "twitch_auth": [] } ], "deprecated": true } }, "/streams/tags": { "get": { "summary": "Gets the list of stream tags that the broadcaster or Twitch added to their channel.", "description": "**IMPORTANT** Twitch is moving from Twitch-defined tags to channel-defined tags. **IMPORTANT** As of February 28, 2023, this endpoint returns an empty array. On July 13, 2023, it will return a 410 response. If you use this endpoint, please update your code to use [Get Channel Information](https://dev.twitch.tv/docs/api/reference#get-channel-information).\n\nGets the list of stream tags that the broadcaster or Twitch added to their channel.\n\n__Authorization:__\n\nRequires an [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens) or [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens).", "tags": [ "Tags" ], "externalDocs": { "description": "Get Stream Tags", "url": "https://dev.twitch.tv/docs/api/reference#get-stream-tags" }, "operationId": "get-stream-tags", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster whose stream tags you want to get.", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Successfully retrieved the list of tags.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetStreamTagsResponse" }, "examples": { "Example": { "description": "_Request:_\n\nGets the TwitchGaming channel’s tags.\n\n```bash\ncurl -X GET\n'https://api.twitch.tv/helix/streams/tags?broadcaster_id=527115020' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```\n\n```bash\n# Twitch CLI example that gets the TwitchGaming channel's tags.\ntwitch api get /streams/tags -q broadcaster_id=527115020\n```", "value": { "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" } } ] } } } } } }, "400": { "description": "* The _broadcaster\\_id_ field is required.\n* The ID in the _broadcaster\\_id_ field is not valid." }, "401": { "description": "* The Authorization header is required and must specify an app access token or user access token.\n* The access token is not valid.\n* The ID in the Client-Id header must match the Client ID in the access token." } }, "security": [ { "twitch_auth": [] } ], "deprecated": true } }, "/teams/channel": { "get": { "summary": "Gets the list of Twitch teams that the broadcaster is a member of.", "description": "Gets the list of Twitch teams that the broadcaster is a member of.\n\n__Authorization:__\n\nRequires an [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens) or [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens).", "tags": [ "Teams" ], "externalDocs": { "description": "Get Channel Teams", "url": "https://dev.twitch.tv/docs/api/reference#get-channel-teams" }, "operationId": "get-channel-teams", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster whose teams you want to get.", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Successfully retrieved the list of teams.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetChannelTeamsResponse" }, "examples": { "Example": { "description": "_Request:_\n\nGets a list of Twitch Teams that the specified broadcaster is a member of.\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/teams/channel?broadcaster_id=96909659' \\\n-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \\\n-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'\n```", "value": { "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": "

An outgoing and enthusiastic group of friendly channels that write code, teach about technology, and promote the technical community.

", "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" } ] } } } } } }, "400": { "description": "* The _broadcaster\\_id_ query parameter is missing or invalid." }, "401": { "description": "* The Authorization header must contain an app access token or user access token.\n* The access token is not valid.\n* The ID specified in the Client-Id header does not match the client ID specified in the access token." }, "404": { "description": "* The broadcaster was not found." } }, "security": [ { "twitch_auth": [] } ] } }, "/teams": { "get": { "summary": "Gets information about the specified Twitch team.", "description": "Gets information about the specified Twitch team. [Read More](https://help.twitch.tv/s/article/twitch-teams)\n\n__Authorization:__\n\nRequires an [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens) or [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens).", "tags": [ "Teams" ], "externalDocs": { "description": "Get Teams", "url": "https://dev.twitch.tv/docs/api/reference#get-teams" }, "operationId": "get-teams", "parameters": [ { "name": "name", "in": "query", "description": "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.", "schema": { "type": "string" } }, { "name": "id", "in": "query", "description": "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.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the team's information.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetTeamsResponse" }, "examples": { "Example": { "description": "_Request:_\n\nGets information about the specified team.\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/teams?id=6358' \\\n-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \\\n-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'\n```", "value": { "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": "

An outgoing and enthusiastic group of friendly channels that write code, teach about technology, and promote the technical community.

", "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" } ] } } } } } }, "400": { "description": "* The _name_ or _id_ query parameter is required.\n* Specify either the _name_ or _id_ query parameter but not both.\n* The ID in the _id_ query parameter is not valid." }, "401": { "description": "* The Authorization header must contain an app access token or user access token.\n* The access token is not valid.\n* The ID specified in the Client-Id header does not match the client ID specified in the access token." }, "404": { "description": "* The specified team was not found." } }, "security": [ { "twitch_auth": [] } ] } }, "/users": { "get": { "summary": "Gets information about one or more users.", "description": "Gets information about one or more users. \n \nYou 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. \n \nIf 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. \n \nTo include the user’s verified email address in the response, you must use a user access token that includes the **user:read:email** scope.\n\n__Authorization:__\n\nRequires an [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens) or [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens).", "tags": [ "Users" ], "externalDocs": { "description": "Get Users", "url": "https://dev.twitch.tv/docs/api/reference#get-users" }, "operationId": "get-users", "parameters": [ { "name": "id", "in": "query", "description": "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.", "schema": { "type": "array", "items": { "type": "string" } }, "explode": true }, { "name": "login", "in": "query", "description": "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.", "schema": { "type": "array", "items": { "type": "string" } }, "explode": true } ], "responses": { "200": { "description": "Successfully retrieved the specified users’ information.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetUsersResponse" }, "examples": { "Example": { "description": "_Request:_\n\nGets information about the specified user.\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/users?id=141981764' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```", "value": { "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" } ] } } } } } }, "400": { "description": "* The \\*id\\* or \\*login\\* query parameter is required unless the request uses a user access token.\n* The request exceeded the maximum allowed number of \\*id\\* and/or \\*login\\* query parameters." }, "401": { "description": "* The Authorization header is required and must contain an app access token or user access token.\n* The access token is not valid.\n* The ID specified in the Client-Id header does not match the client ID specified in the access token." } }, "security": [ { "twitch_auth": [] } ] }, "put": { "summary": "Updates the user’s information.", "description": "Updates the specified user’s information. The user ID in the OAuth token identifies the user whose information you want to update.\n\nTo include the user’s verified email address in the response, the user access token must also include the **user:read:email** scope.\n\n__Authorization:__\n\nRequires a [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **user:edit** scope.", "tags": [ "Users" ], "externalDocs": { "description": "Update User", "url": "https://dev.twitch.tv/docs/api/reference#update-user" }, "operationId": "update-user", "parameters": [ { "name": "description", "in": "query", "description": "The string to update the channel’s description to. The description is limited to a maximum of 300 characters. \n \nTo remove the description, specify this parameter but don’t set it’s value (for example, `?description=`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully updated the specified user's information.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserResponse" }, "examples": { "Example": { "description": "_Request:_\n\nUpdates the description of the specified user.\n\n```bash\ncurl -X PUT 'https://api.twitch.tv/helix/users?description=BaldAngel' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```", "value": { "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" } ] } } } } } }, "400": { "description": "* The string in the _description_ query parameter is too long." }, "401": { "description": "* The Authorization header is required and must contain a user access token.\n* The user access token must include the **user:edit** scope.\n* The access token is not valid.\n* The ID specified in the Client-Id header does not match the client ID specified in the access token." }, "429": { "description": "The app exceeded the number of requests that it may make." } }, "security": [ { "twitch_auth": [ "user:edit" ] } ] } }, "/authorization/users": { "get": { "summary": "NEW Gets the authorization scopes that the specified user has granted the application.", "description": "NEW Gets the authorization scopes that the specified user(s) have granted the application.\n\n__Authorization:__\n\nRequires an [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens).", "tags": [ "Users" ], "externalDocs": { "description": "Get Authorization By User", "url": "https://dev.twitch.tv/docs/api/reference#get-authorization-by-user" }, "operationId": "get-authorization-by-user", "parameters": [ { "name": "user_id", "in": "query", "description": "The ID of the user(s) you want to check authorization for. 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 you may specify is 10.", "schema": { "type": "array", "items": { "type": "string" } }, "required": true, "explode": true } ], "responses": { "200": { "description": "Successfully retrieved user authorization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAuthorizationByUserResponse" }, "examples": { "Example": { "description": "_Request:_\n\nGets the authorized scopes for the TwitchDev user and the TwitchRivals user.\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/authorization/users?user_id=141981764&user_id=197886470' \\\n-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```", "value": { "data": [ { "user_id": "141981764", "user_name": "TwitchDev", "user_login": "twitchdev", "scopes": [ "bits:read", "channel:bot", "channel:manage:predictions" ] }, { "user_id": "197886470", "user_name": "TwitchRivals", "user_login": "twitchrivals", "scopes": [ "channel:manage:predictions" ] } ] } } } } } }, "400": { "description": "Request is malformed - invalid parameters or missing parameters." }, "401": { "description": "* The access token is not valid.\n* Authorization header is required and must specify an app access token." }, "403": { "description": "The client-id in the header must match the client ID in the access token." }, "500": { "description": "Internal Server Error." } }, "security": [ { "twitch_auth": [] } ] } }, "/users/blocks": { "get": { "summary": "Gets the list of users that the broadcaster has blocked.", "description": "Gets the list of users that the broadcaster has blocked. [Read More](https://help.twitch.tv/s/article/how-to-manage-harassment-in-chat?language=en%5FUS#BlockWhispersandMessagesfromStrangers)\n\n__Authorization:__\n\nRequires a [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **user:read:blocked\\_users** scope.", "tags": [ "Users" ], "externalDocs": { "description": "Get User Block List", "url": "https://dev.twitch.tv/docs/api/reference#get-user-block-list" }, "operationId": "get-user-block-list", "parameters": [ { "name": "broadcaster_id", "in": "query", "description": "The ID of the broadcaster whose list of blocked users you want to get.", "schema": { "type": "string" }, "required": true }, { "name": "first", "in": "query", "description": "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.", "schema": { "type": "integer", "format": "int32" } }, { "name": "after", "in": "query", "description": "The cursor used to get the next page of results. The **Pagination** object in the response contains the cursor’s value. [Read More](https://dev.twitch.tv/docs/api/guide#pagination)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the broadcaster's list of blocked users.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetUserBlockListResponse" }, "examples": { "Example": { "description": "_Request:_\n\nGets the specified broadcaster’s list of blocked users.\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/users/blocks?broadcaster_id=141981764' \\\n-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \\\n-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz' \\\n```", "value": { "data": [ { "user_id": "135093069", "user_login": "bluelava", "display_name": "BlueLava" }, { "user_id": "27419011", "user_login": "travistyoj", "display_name": "TravistyOJ" } ] } } } } } }, "400": { "description": "* The _broadcaster\\_id_ query parameter is required." }, "401": { "description": "* The ID in _broadcaster\\_id_ must match the user ID found in the request’s access token.\n* The Authorization header is required and must contain a user access token.\n* The user access token must include the **user:read:blocked\\_users** scope.\n* The access token is not valid.\n* The ID specified in the Client-Id header does not match the client ID specified in the access token." } }, "security": [ { "twitch_auth": [ "user:read:blocked_users" ] } ] }, "put": { "summary": "Blocks the specified user from interacting with or having contact with the broadcaster.", "description": "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.\n\nTo learn more about blocking users, see [Block Other Users on Twitch](https://help.twitch.tv/s/article/how-to-manage-harassment-in-chat?language=en%5FUS#BlockWhispersandMessagesfromStrangers).\n\n__Authorization:__\n\nRequires a [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **user:manage:blocked\\_users** scope.", "tags": [ "Users" ], "externalDocs": { "description": "Block User", "url": "https://dev.twitch.tv/docs/api/reference#block-user" }, "operationId": "block-user", "parameters": [ { "name": "target_user_id", "in": "query", "description": "The ID of the user to block. The API ignores the request if the broadcaster has already blocked the user.", "schema": { "type": "string" }, "required": true }, { "name": "source_context", "in": "query", "description": "The location where the harassment took place that is causing the brodcaster to block the user. Possible values are: \n \n* chat\n* whisper\n \n.", "schema": { "type": "string", "enum": [ "chat", "whisper" ] } }, { "name": "reason", "in": "query", "description": "The reason that the broadcaster is blocking the user. Possible values are: \n \n* harassment\n* spam\n* other", "schema": { "type": "string", "enum": [ "harassment", "spam", "other" ] } } ], "responses": { "204": { "description": "Successfully blocked the user.\n\n__Examples__\n\n_Request:_\n\nBlocks the specified user.\n\n```bash\ncurl -X PUT 'https://api.twitch.tv/helix/users/blocks?target_user_id=198704263' \\\n-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \\\n-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz' \\\n```" }, "400": { "description": "* The _target\\_user\\_id_ query parameter is required.\n* The ID in _target\\_user\\_id_ cannot be the same as the user ID in the access token.\n* The value in _source\\_context_ is not valid.\n* The value in _reason_ is not valid." }, "401": { "description": "* The Authorization header is required and must contain a user access token.\n* The user access token must include the **user:manage:blocked\\_users** scope.\n* The access token is not valid.\n* The ID specified in the Client-Id header does not match the client ID specified in the access token." } }, "security": [ { "twitch_auth": [ "user:manage:blocked_users" ] } ] }, "delete": { "summary": "Removes the user from the broadcaster’s list of blocked users.", "description": "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.\n\n__Authorization:__\n\nRequires a [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **user:manage:blocked\\_users** scope.", "tags": [ "Users" ], "externalDocs": { "description": "Unblock User", "url": "https://dev.twitch.tv/docs/api/reference#unblock-user" }, "operationId": "unblock-user", "parameters": [ { "name": "target_user_id", "in": "query", "description": "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.", "schema": { "type": "string" }, "required": true } ], "responses": { "204": { "description": "Successfully removed the block.\n\n__Examples__\n\n_Request:_\n\nUnblocks the specified user.\n\n```bash\ncurl -X DELETE 'https://api.twitch.tv/helix/users/blocks?target_user_id=198704263' \\\n-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \\\n-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz' \\\n```" }, "400": { "description": "* The _target\\_user\\_id_ query parameter is required." }, "401": { "description": "* The Authorization header is required and must contain a user access token.\n* The user access token must include the **user:read:blocked\\_users** scope.\n* The access token is not valid.\n* The ID specified in the Client-Id header does not match the client ID specified in the access token." } }, "security": [ { "twitch_auth": [ "user:manage:blocked_users" ] } ] } }, "/users/extensions/list": { "get": { "summary": "Gets a list of all extensions (both active and inactive) that the broadcaster has installed.", "description": "Gets a list of all extensions (both active and inactive) that the broadcaster has installed. The user ID in the access token identifies the broadcaster.\n\n__Authorization:__\n\nRequires a [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **user:read:broadcast** or **user:edit:broadcast** scope. To include inactive extensions, you must include the **user:edit:broadcast** scope.", "tags": [ "Users" ], "externalDocs": { "description": "Get User Extensions", "url": "https://dev.twitch.tv/docs/api/reference#get-user-extensions" }, "operationId": "get-user-extensions", "responses": { "200": { "description": "Successfully retrieved the user's installed extensions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetUserExtensionsResponse" }, "examples": { "Example": { "description": "_Request:_\n\nGets the extensions that the user has installed.\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/users/extensions/list' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```", "value": { "data": [ { "id": "wi08ebtatdc7oj83wtl9uxwz807l8b", "version": "1.1.8", "name": "Streamlabs Leaderboard", "can_activate": true, "type": [ "panel" ] }, { "id": "d4uvtfdr04uq6raoenvj7m86gdk16v", "version": "2.0.2", "name": "Prime Subscription and Loot Reminder", "can_activate": true, "type": [ "overlay" ] }, { "id": "rh6jq1q334hqc2rr1qlzqbvwlfl3x0", "version": "1.1.0", "name": "TopClip", "can_activate": true, "type": [ "mobile", "panel" ] }, { "id": "zfh2irvx2jb4s60f02jq0ajm8vwgka", "version": "1.0.19", "name": "Streamlabs", "can_activate": true, "type": [ "mobile", "overlay" ] }, { "id": "lqnf3zxk0rv0g7gq92mtmnirjz2cjj", "version": "0.0.1", "name": "Dev Experience Test", "can_activate": true, "type": [ "component", "mobile", "panel", "overlay" ] } ] } } } } } }, "401": { "description": "* The Authorization header is required and must contain a user access token.\n* The user access token must include the **user:read:broadcast** scope.\n* The access token is not valid.\n* The ID specified in the Client-Id header does not match the client ID specified in the access token." } }, "security": [ { "twitch_auth": [ "user:read:broadcast", "user:edit:broadcast" ] } ] } }, "/users/extensions": { "get": { "summary": "Gets the active extensions that the broadcaster has installed for each configuration.", "description": "Gets the active extensions that the broadcaster has installed for each configuration.\n\nNOTE: To include extensions that you have under development, you must specify a user access token that includes the **user:read:broadcast** or **user:edit:broadcast** scope.\n\n__Authorization:__\n\nRequires an [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens) or [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens).", "tags": [ "Users" ], "externalDocs": { "description": "Get User Active Extensions", "url": "https://dev.twitch.tv/docs/api/reference#get-user-active-extensions" }, "operationId": "get-user-active-extensions", "parameters": [ { "name": "user_id", "in": "query", "description": "The ID of the broadcaster whose active extensions you want to get. \n \nThis parameter is required if you specify an app access token and is optional if you specify a user access token. If you specify a user access token and don’t specify this parameter, the API uses the user ID from the access token.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the user's active extensions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetUserActiveExtensionsResponse" }, "examples": { "Example": { "description": "_Request:_\n\nGets the user’s active extensions. The API gets the user from the access token.\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/users/extensions' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```", "value": { "data": { "panel": { "1": { "active": true, "id": "rh6jq1q334hqc2rr1qlzqbvwlfl3x0", "version": "1.1.0", "name": "TopClip" }, "2": { "active": true, "id": "wi08ebtatdc7oj83wtl9uxwz807l8b", "version": "1.1.8", "name": "Streamlabs Leaderboard" }, "3": { "active": true, "id": "naty2zwfp7vecaivuve8ef1hohh6bo", "version": "1.0.9", "name": "Streamlabs Stream Schedule & Countdown" } }, "overlay": { "1": { "active": true, "id": "zfh2irvx2jb4s60f02jq0ajm8vwgka", "version": "1.0.19", "name": "Streamlabs" } }, "component": { "1": { "active": true, "id": "lqnf3zxk0rv0g7gq92mtmnirjz2cjj", "version": "0.0.1", "name": "Dev Experience Test", "x": 0, "y": 0 }, "2": { "active": false } } } } } } } } }, "400": { "description": "* The _user\\_id_ query parameter is required if you specify an app access token." }, "401": { "description": "* The Authorization header is required and must contain an app access token or user access token.\n* The access token is not valid.\n* The ID specified in the Client-Id header does not match the client ID specified in the access token." } }, "security": [ { "twitch_auth": [] } ] }, "put": { "summary": "Updates an installed extension’s information.", "description": "Updates an installed extension’s information. You can update the extension’s activation state, ID, and version number. The user ID in the access token identifies the broadcaster whose extensions you’re updating.\n\nNOTE: If you try to activate an extension under multiple extension types, the last write wins (and there is no guarantee of write order).\n\n__Authorization:__\n\nRequires a [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **user:edit:broadcast** scope.", "tags": [ "Users" ], "externalDocs": { "description": "Update User Extensions", "url": "https://dev.twitch.tv/docs/api/reference#update-user-extensions" }, "operationId": "update-user-extensions", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserExtensionsBody" }, "examples": { "Example": { "value": { "data": { "panel": { "1": { "active": true, "id": "rh6jq1q334hqc2rr1qlzqbvwlfl3x0", "version": "1.1.0" }, "2": { "active": true, "id": "wi08ebtatdc7oj83wtl9uxwz807l8b", "version": "1.1.8" }, "3": { "active": true, "id": "naty2zwfp7vecaivuve8ef1hohh6bo", "version": "1.0.9" } }, "overlay": { "1": { "active": true, "id": "zfh2irvx2jb4s60f02jq0ajm8vwgka", "version": "1.0.19" } }, "component": { "1": { "active": true, "id": "lqnf3zxk0rv0g7gq92mtmnirjz2cjj", "version": "0.0.1", "x": 0, "y": 0 }, "2": { "active": false } } } }, "description": "Updates the the user’s installed extensions." } } } } }, "responses": { "200": { "description": "Successfully updated the active extensions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserExtensionsResponse" }, "examples": { "Example": { "description": "_Request:_\n\nUpdates the the user’s installed extensions.\n\n```bash\ncurl -X PUT 'https://api.twitch.tv/helix/users/extensions' \\\n-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \\\n-H \"Content-Type: application/json\" \\\n-d '{\n \"data\": {\n \"panel\": {\n \"1\": {\n \"active\": true,\n \"id\": \"rh6jq1q334hqc2rr1qlzqbvwlfl3x0\",\n \"version\": \"1.1.0\"\n },\n \"2\": {\n \"active\": true,\n \"id\": \"wi08ebtatdc7oj83wtl9uxwz807l8b\",\n \"version\": \"1.1.8\"\n },\n \"3\": {\n \"active\": true,\n \"id\": \"naty2zwfp7vecaivuve8ef1hohh6bo\",\n \"version\": \"1.0.9\"\n }\n },\n \"overlay\": {\n \"1\": {\n \"active\": true,\n \"id\": \"zfh2irvx2jb4s60f02jq0ajm8vwgka\",\n \"version\": \"1.0.19\"\n }\n },\n \"component\": {\n \"1\": {\n \"active\": true,\n \"id\": \"lqnf3zxk0rv0g7gq92mtmnirjz2cjj\",\n \"version\": \"0.0.1\",\n \"x\": 0,\n \"y\": 0\n },\n \"2\": {\n \"active\": false\n }\n }\n }\n}'\n```", "value": { "data": { "panel": { "1": { "active": true, "id": "rh6jq1q334hqc2rr1qlzqbvwlfl3x0", "version": "1.1.0", "name": "TopClip" }, "2": { "active": true, "id": "wi08ebtatdc7oj83wtl9uxwz807l8b", "version": "1.1.8", "name": "Streamlabs Leaderboard" }, "3": { "active": true, "id": "naty2zwfp7vecaivuve8ef1hohh6bo", "version": "1.0.9", "name": "Streamlabs Stream Schedule & Countdown" } }, "overlay": { "1": { "active": true, "id": "zfh2irvx2jb4s60f02jq0ajm8vwgka", "version": "1.0.19", "name": "Streamlabs" } }, "component": { "1": { "active": true, "id": "lqnf3zxk0rv0g7gq92mtmnirjz2cjj", "version": "0.0.1", "name": "Dev Experience Test", "x": 0, "y": 0 }, "2": { "active": false } } } } } } } } }, "400": { "description": "* The JSON payload is malformed." }, "401": { "description": "* The Authorization header is required and must contain a user access token.\n* The user access token must include the **user:edit:broadcast** scope.\n* The access token is not valid.\n* The ID specified in the Client-Id header does not match the client ID specified in the access token." }, "404": { "description": "* An extension with the specified `id` and `version` values was not found." } }, "security": [ { "twitch_auth": [ "user:edit:broadcast" ] } ] } }, "/videos": { "get": { "summary": "Gets information about one or more published videos.", "description": "Gets information about one or more published videos. You may get videos by ID, by user, or by game/category.\n\nYou may apply several filters to get a subset of the videos. The filters are applied as an AND operation to each video. For example, if _language_ is set to ‘de’ and _game\\_id_ is set to 21779, the response includes only videos that show playing League of Legends by users that stream in German. The filters apply only if you get videos by user ID or game ID.\n\n__Authorization:__\n\nRequires an [app access token](https://dev.twitch.tv/docs/authentication#app-access-tokens) or [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens).", "tags": [ "Videos" ], "externalDocs": { "description": "Get Videos", "url": "https://dev.twitch.tv/docs/api/reference#get-videos" }, "operationId": "get-videos", "parameters": [ { "name": "id", "in": "query", "description": "A list of IDs that identify the videos you want to get. To get more than one video, include this parameter for each video you want to get. For example, `id=1234&id=5678`. You may specify a maximum of 100 IDs. The endpoint ignores duplicate IDs and IDs that weren't found (if there's at least one valid ID). \n \nThe _id_, _user\\_id_, and _game\\_id_ parameters are mutually exclusive.", "schema": { "type": "array", "items": { "type": "string" } }, "explode": true }, { "name": "user_id", "in": "query", "description": "The ID of the user whose list of videos you want to get. \n \nThe _id_, _user\\_id_, and _game\\_id_ parameters are mutually exclusive.", "schema": { "type": "string" } }, { "name": "game_id", "in": "query", "description": "A category or game ID. The response contains a maximum of 500 videos that show this content. To get category/game IDs, use the [Search Categories](https://dev.twitch.tv/docs/api/reference#search-categories) endpoint. \n \nThe _id_, _user\\_id_, and _game\\_id_ parameters are mutually exclusive.", "schema": { "type": "string" } }, { "name": "language", "in": "query", "description": "A filter used to filter the list of videos by the language that the video owner broadcasts in. For example, to get videos that were broadcast in German, set this parameter to the ISO 639-1 two-letter code for German (i.e., DE). For a list of supported languages, see [Supported Stream Language](https://help.twitch.tv/s/article/languages-on-twitch#streamlang). If the language is not supported, use “other.” \n \nSpecify this parameter only if you specify the _game\\_id_ query parameter.", "schema": { "type": "string" } }, { "name": "period", "in": "query", "description": "A filter used to filter the list of videos by when they were published. For example, videos published in the last week. Possible values are: \n \n* all\n* day\n* month\n* week\n \nThe default is \"all,\" which returns videos published in all periods. \n \nSpecify this parameter only if you specify the _game\\_id_ or _user\\_id_ query parameter.", "schema": { "type": "string", "enum": [ "all", "day", "month", "week" ] } }, { "name": "sort", "in": "query", "description": "The order to sort the returned videos in. Possible values are: \n \n* time — Sort the results in descending order by when they were created (i.e., latest video first).\n* trending — Sort the results in descending order by biggest gains in viewership (i.e., highest trending video first).\n* views — Sort the results in descending order by most views (i.e., highest number of views first).\n \nThe default is \"time.\" \n \nSpecify this parameter only if you specify the _game\\_id_ or _user\\_id_ query parameter.", "schema": { "type": "string", "enum": [ "time", "trending", "views" ] } }, { "name": "type", "in": "query", "description": "A filter used to filter the list of videos by the video's type. Possible case-sensitive values are: \n \n* all\n* archive — On-demand videos (VODs) of past streams.\n* highlight — Highlight reels of past streams.\n* upload — External videos that the broadcaster uploaded using the Video Producer.\n \nThe default is \"all,\" which returns all video types. \n \nSpecify this parameter only if you specify the _game\\_id_ or _user\\_id_ query parameter.", "schema": { "type": "string", "enum": [ "all", "archive", "highlight", "upload" ] } }, { "name": "first", "in": "query", "description": "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. \n \nSpecify this parameter only if you specify the _game\\_id_ or _user\\_id_ query parameter.", "schema": { "type": "string" } }, { "name": "after", "in": "query", "description": "The cursor used to get the next page of results. The **Pagination** object in the response contains the cursor’s value. [Read More](https://dev.twitch.tv/docs/api/guide#pagination) \n \nSpecify this parameter only if you specify the _user\\_id_ query parameter.", "schema": { "type": "string" } }, { "name": "before", "in": "query", "description": "The cursor used to get the previous page of results. The **Pagination** object in the response contains the cursor’s value. [Read More](https://dev.twitch.tv/docs/api/guide#pagination) \n \nSpecify this parameter only if you specify the _user\\_id_ query parameter.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the list of videos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetVideosResponse" }, "examples": { "Example": { "description": "_Request:_\n\nGets information about the specified video.\n\n```bash\ncurl -X GET 'https://api.twitch.tv/helix/videos?id=335921245' \\\n-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```", "value": { "data": [ { "id": "335921245", "stream_id": null, "user_id": "141981764", "user_login": "twitchdev", "user_name": "TwitchDev", "title": "Twitch Developers 101", "description": "Welcome to Twitch development! Here is a quick overview of our products and information to help you get started.", "created_at": "2018-11-14T21:30:18Z", "published_at": "2018-11-14T22:04:30Z", "url": "https://www.twitch.tv/videos/335921245", "thumbnail_url": "https://static-cdn.jtvnw.net/cf_vods/d2nvs31859zcd8/twitchdev/335921245/ce0f3a7f-57a3-4152-bc06-0c6610189fb3/thumb/index-0000000000-%{width}x%{height}.jpg", "viewable": "public", "view_count": 1863062, "language": "en", "type": "upload", "duration": "3m21s", "muted_segments": [ { "duration": 30, "offset": 120 } ] } ], "pagination": {} } } } } } }, "400": { "description": "* The request must specify either the _id_ or _user\\_id_ or _game\\_id_ query parameter.\n* The _id_, _user\\_id_, and _game\\_id_ query parameters are mutually exclusive; you must specify only one of them.\n* The value in the _id_ query parameter is not valid.\n* The ID in the _game\\_id_ query parameter is not valid.\n* The value in the _type_ query parameter is not valid.\n* The value in the _period_ query parameter is not valid.\n* The value in the _sort_ query parameter is not valid." }, "401": { "description": "* The Authorization header is required and must contain an app access token or user access token.\n* The access token is not valid.\n* The ID specified in the Client-Id header does not match the client ID specified in the access token." }, "404": { "description": "* The ID in the _game\\_id_ query parameter was not found.\n* The ID in the _id_ query parameter was not found. Returned only if all the IDs were not found; otherwise, the ID is ignored." } }, "security": [ { "twitch_auth": [] } ] }, "delete": { "summary": "Deletes one or more videos.", "description": "Deletes one or more videos. You may delete past broadcasts, highlights, or uploads.\n\n__Authorization:__\n\nRequires a [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **channel:manage:videos** scope.", "tags": [ "Videos" ], "externalDocs": { "description": "Delete Videos", "url": "https://dev.twitch.tv/docs/api/reference#delete-videos" }, "operationId": "delete-videos", "parameters": [ { "name": "id", "in": "query", "description": "The list of videos to delete. To specify more than one video, include the _id_ parameter for each video to delete. For example, `id=1234&id=5678`. You can delete a maximum of 5 videos per request. Ignores invalid video IDs. \n \nIf the user doesn’t have permission to delete one of the videos in the list, none of the videos are deleted.", "schema": { "type": "array", "items": { "type": "string" } }, "required": true, "explode": true } ], "responses": { "200": { "description": "Successfully deleted the list of videos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteVideosResponse" }, "examples": { "Example": { "description": "_Request:_\n\nDeletes the two specified videos.\n\n```bash\ncurl -X DELETE 'https://api.twitch.tv/helix/videos?id=1234&id=9876' \\\n-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \\\n-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'\n```", "value": { "data": [ "1234", "9876" ] } } } } } }, "400": { "description": "* The _id_ query parameter is required.\n* The request exceeded the number of allowed _id_ query parameters." }, "401": { "description": "* The caller is not authorized to delete the specified video.\n* The Authorization header is required and must contain a user access token.\n* The user access token must include the **channel:manage:videos** scope.\n* The access token is not valid.\n* The ID specified in the Client-Id header does not match the client ID specified in the access token." } }, "security": [ { "twitch_auth": [ "channel:manage:videos" ] } ] } }, "/whispers": { "post": { "summary": "Sends a whisper message to the specified user.", "description": "Sends a whisper message to the specified user.\n\nNOTE: The user sending the whisper must have a verified phone number (see the **Phone Number** setting in your [Security and Privacy](https://www.twitch.tv/settings/security) settings).\n\nNOTE: The API may silently drop whispers that it suspects of violating Twitch policies. (The API does not indicate that it dropped the whisper; it returns a 204 status code as if it succeeded.)\n\n**Rate Limits**: You may whisper to a maximum of 40 unique recipients per day. Within the per day limit, you may whisper a maximum of 3 whispers per second and a maximum of 100 whispers per minute.\n\n__Authorization:__\n\nRequires a [user access token](https://dev.twitch.tv/docs/authentication#user-access-tokens) that includes the **user:manage:whispers** scope.", "tags": [ "Whispers" ], "externalDocs": { "description": "Send Whisper", "url": "https://dev.twitch.tv/docs/api/reference#send-whisper" }, "operationId": "send-whisper", "parameters": [ { "name": "from_user_id", "in": "query", "description": "The ID of the user sending the whisper. This user must have a verified phone number. This ID must match the user ID in the user access token.", "schema": { "type": "string" }, "required": true }, { "name": "to_user_id", "in": "query", "description": "The ID of the user to receive the whisper.", "schema": { "type": "string" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendWhisperBody" }, "examples": { "Example": { "value": { "message": "hello" }, "description": "Send the user a whisper message." } } } } }, "responses": { "204": { "description": "Successfully sent the whisper message or the message was silently dropped.\n\n__Examples__\n\n_Request:_\n\nSend the user a whisper message.\n\n```bash\ncurl -X POST 'https://api.twitch.tv/helix/whispers?from_user_id=123&to_user_id=456' \\\n-H 'Authorization: Bearer kpvy3cjboyptmdkiacwr0c19hotn5s' \\\n-H 'Client-Id: hof5gwx0su6owfnys0nyan9c87zr6t' \\\n-H 'Content-Type: application/json' \\\n-d '{\"message\":\"hello\"}'\n```" }, "400": { "description": "* The ID in the _from\\_user\\_id_ and _to\\_user\\_id_ query parameters must be different.\n* The `message` field must not contain an empty string.\n* The user that you're sending the whisper to doesn't allow whisper messages (see the **Block Whispers from Strangers** setting in your [Security and Privacy](https://www.twitch.tv/settings/security) settings).\n* Whisper messages may not be sent to suspended users.\n* The ID in the _from\\_user\\_id_ query parameter is not valid.\n* The ID in the _to\\_user\\_id_ query parameter is not valid." }, "401": { "description": "* The user in the _from\\_user\\_id_ query parameter must have a verified phone number.\n* The Authorization header is required and must contain a user access token.\n* The user access token must include the **user:manage:whispers** scope.\n* The access token is not valid.\n* This ID in _from\\_user\\_id_ must match the user ID in the user access token.\n* The client ID specified in the Client-Id header does not match the client ID specified in the access token." }, "403": { "description": "* Suspended users may not send whisper messages.\n* The account that's sending the message doesn't allow sending whispers." }, "404": { "description": "* The ID in _to\\_user\\_id_ was not found." }, "429": { "description": "* The sending user exceeded the number of whisper requests that they may make. See Rate Limits for this endpoint above." } }, "security": [ { "twitch_auth": [ "user:manage:whispers" ] } ] } } }, "components": { "schemas": { "StartCommercialBody": { "type": "object", "required": [ "broadcaster_id", "length" ], "properties": { "broadcaster_id": { "type": "string", "description": "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": { "type": "integer", "description": "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.", "format": "int32" } } }, "StartCommercialResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "An array that contains a single object with the status of your start commercial request.", "items": { "type": "object", "required": [ "length", "message", "retry_after" ], "properties": { "length": { "type": "integer", "description": "The length of the commercial you requested. If you request a commercial that’s longer than 180 seconds, the API uses 180 seconds.", "format": "int32" }, "message": { "type": "string", "description": "A message that indicates whether Twitch was able to serve an ad." }, "retry_after": { "type": "integer", "description": "The number of seconds you must wait before running another commercial.", "format": "int32" } } } } } }, "GetAdScheduleResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "A list that contains information related to the channel’s ad schedule.", "items": { "type": "object", "required": [ "snooze_count", "snooze_refresh_at", "next_ad_at", "duration", "last_ad_at", "preroll_free_time" ], "properties": { "snooze_count": { "type": "integer", "description": "The number of snoozes available for the broadcaster.", "format": "int32" }, "snooze_refresh_at": { "type": "integer", "description": "The UTC timestamp when the broadcaster will gain an additional snooze, in RFC3339 format. Can be `0`.", "format": "int64" }, "next_ad_at": { "type": "integer", "description": "The UTC timestamp of the broadcaster’s next scheduled ad, in RFC3339 format. `0` if the channel has no ad scheduled or is not live.", "format": "int64" }, "duration": { "type": "integer", "description": "The length in seconds of the scheduled upcoming ad break.", "format": "int32" }, "last_ad_at": { "type": "integer", "description": "The UTC timestamp of the broadcaster’s last ad-break, in RFC3339 format. Empty if the channel has not run an ad or is not live.", "format": "int64" }, "preroll_free_time": { "type": "integer", "description": "The amount of pre-roll free time remaining for the channel in seconds. Returns 0 if they are currently not pre-roll free.", "format": "int32" } } } } } }, "SnoozeNextAdResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "A list that contains information about the channel’s snoozes and next upcoming ad after successfully snoozing.", "items": { "type": "object", "required": [ "snooze_count", "snooze_refresh_at", "next_ad_at" ], "properties": { "snooze_count": { "type": "integer", "description": "The number of snoozes available for the broadcaster.", "format": "int32" }, "snooze_refresh_at": { "type": "integer", "description": "The UTC timestamp when the broadcaster will gain an additional snooze, in RFC3339 format. Can be `0`.", "format": "int64" }, "next_ad_at": { "type": "integer", "description": "The UTC timestamp of the broadcaster’s next scheduled ad, in RFC3339 format. `0` if the channel has no ad scheduled or is not live.", "format": "int64" } } } } } }, "ExtensionAnalytics": { "type": "object", "required": [ "extension_id", "URL", "type", "date_range" ], "properties": { "extension_id": { "type": "string", "description": "An ID that identifies the extension that the report was generated for." }, "URL": { "type": "string", "description": "The URL that you use to download the report. The URL is valid for 5 minutes." }, "type": { "type": "string", "description": "The type of report." }, "date_range": { "description": "The reporting window’s start and end dates, in RFC3339 format.", "type": "object", "required": [ "started_at", "ended_at" ], "properties": { "started_at": { "type": "string", "description": "The reporting window’s start date.", "format": "date-time" }, "ended_at": { "type": "string", "description": "The reporting window’s end date.", "format": "date-time" } } } } }, "GetExtensionAnalyticsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "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.", "items": { "$ref": "#/components/schemas/ExtensionAnalytics" } }, "pagination": { "description": "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](https://dev.twitch.tv/docs/api/guide#pagination)", "type": "object", "properties": { "cursor": { "type": "string", "description": "The cursor used to get the next page of results. Use the cursor to set the request’s _after_ query parameter." } } } } }, "GameAnalytics": { "type": "object", "required": [ "game_id", "URL", "type", "date_range" ], "properties": { "game_id": { "type": "string", "description": "An ID that identifies the game that the report was generated for." }, "URL": { "type": "string", "description": "The URL that you use to download the report. The URL is valid for 5 minutes." }, "type": { "type": "string", "description": "The type of report." }, "date_range": { "description": "The reporting window’s start and end dates, in RFC3339 format.", "type": "object", "required": [ "started_at", "ended_at" ], "properties": { "started_at": { "type": "string", "description": "The reporting window’s start date.", "format": "date-time" }, "ended_at": { "type": "string", "description": "The reporting window’s end date.", "format": "date-time" } } } } }, "GetGameAnalyticsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "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.", "items": { "$ref": "#/components/schemas/GameAnalytics" } }, "pagination": { "description": "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](https://dev.twitch.tv/docs/api/guide#pagination)", "type": "object", "properties": { "cursor": { "type": "string", "description": "The cursor used to get the next page of results. Use the cursor to set the request’s _after_ query parameter." } } } } }, "BitsLeaderboard": { "type": "object", "required": [ "user_id", "user_login", "user_name", "rank", "score" ], "properties": { "user_id": { "type": "string", "description": "An ID that identifies a user on the leaderboard." }, "user_login": { "type": "string", "description": "The user’s login name." }, "user_name": { "type": "string", "description": "The user’s display name." }, "rank": { "type": "integer", "description": "The user’s position on the leaderboard.", "format": "int32" }, "score": { "type": "integer", "description": "The number of Bits the user has cheered.", "format": "int32" } } }, "GetBitsLeaderboardResponse": { "type": "object", "required": [ "data", "date_range", "total" ], "properties": { "data": { "type": "array", "description": "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.", "items": { "$ref": "#/components/schemas/BitsLeaderboard" } }, "date_range": { "description": "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.", "type": "object", "required": [ "started_at", "ended_at" ], "properties": { "started_at": { "type": "string", "description": "The reporting window’s start date.", "format": "date-time" }, "ended_at": { "type": "string", "description": "The reporting window’s end date.", "format": "date-time" } } }, "total": { "type": "integer", "description": "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.", "format": "int32" } } }, "CheermoteImageFormat": { "type": "object", "properties": { "1": { "type": "string" }, "2": { "type": "string" }, "3": { "type": "string" }, "4": { "type": "string" }, "1.5": { "type": "string" } } }, "CheermoteImageTheme": { "type": "object", "properties": { "animated": { "$ref": "#/components/schemas/CheermoteImageFormat" }, "static": { "$ref": "#/components/schemas/CheermoteImageFormat" } } }, "CheermoteImages": { "type": "object", "properties": { "light": { "$ref": "#/components/schemas/CheermoteImageTheme" }, "dark": { "$ref": "#/components/schemas/CheermoteImageTheme" } } }, "Cheermote": { "type": "object", "required": [ "prefix", "tiers", "type", "order", "last_updated", "is_charitable" ], "properties": { "prefix": { "type": "string", "description": "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": { "type": "array", "description": "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.", "items": { "type": "object", "required": [ "min_bits", "id", "color", "images", "can_cheer", "show_in_bits_card" ], "properties": { "min_bits": { "type": "integer", "description": "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.", "format": "int32" }, "id": { "type": "string", "description": "The tier level. Possible tiers are: \n \n* 1\n* 100\n* 500\n* 1000\n* 5000\n* 10000\n* 100000", "enum": [ "1", "100", "500", "1000", "5000", "10000", "100000" ] }, "color": { "type": "string", "description": "The hex code of the color associated with this tier level (for example, #979797)." }, "images": { "$ref": "#/components/schemas/CheermoteImages" }, "can_cheer": { "type": "boolean", "description": "A Boolean value that determines whether users can cheer at this tier level." }, "show_in_bits_card": { "type": "boolean", "description": "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": { "type": "string", "description": "The type of Cheermote. Possible values are: \n \n* global\\_first\\_party — A Twitch-defined Cheermote that is shown in the Bits card.\n* global\\_third\\_party — A Twitch-defined Cheermote that is not shown in the Bits card.\n* channel\\_custom — A broadcaster-defined Cheermote.\n* display\\_only — Do not use; for internal use only.\n* 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.", "enum": [ "global_first_party", "global_third_party", "channel_custom", "display_only", "sponsored" ] }, "order": { "type": "integer", "description": "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.", "format": "int32" }, "last_updated": { "type": "string", "description": "The date and time, in RFC3339 format, when this Cheermote was last updated.", "format": "date-time" }, "is_charitable": { "type": "boolean", "description": "A Boolean value that indicates whether this Cheermote provides a charitable contribution match during charity campaigns." } } }, "GetCheermotesResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "The list of Cheermotes. The list is in ascending order by the `order` field’s value.", "items": { "$ref": "#/components/schemas/Cheermote" } } } }, "ExtensionTransaction": { "type": "object", "required": [ "id", "timestamp", "broadcaster_id", "broadcaster_login", "broadcaster_name", "user_id", "user_login", "user_name", "product_type", "product_data" ], "properties": { "id": { "type": "string", "description": "An ID that identifies the transaction." }, "timestamp": { "type": "string", "description": "The UTC date and time (in RFC3339 format) of the transaction.", "format": "date-time" }, "broadcaster_id": { "type": "string", "description": "The ID of the broadcaster that owns the channel where the transaction occurred." }, "broadcaster_login": { "type": "string", "description": "The broadcaster’s login name." }, "broadcaster_name": { "type": "string", "description": "The broadcaster’s display name." }, "user_id": { "type": "string", "description": "The ID of the user that purchased the digital product." }, "user_login": { "type": "string", "description": "The user’s login name." }, "user_name": { "type": "string", "description": "The user’s display name." }, "product_type": { "type": "string", "description": "The type of transaction. Possible values are: \n \n* BITS\\_IN\\_EXTENSION", "enum": [ "BITS_IN_EXTENSION" ] }, "product_data": { "description": "Contains details about the digital product.", "type": "object", "required": [ "sku", "domain", "cost", "inDevelopment", "displayName", "expiration", "broadcast" ], "properties": { "sku": { "type": "string", "description": "An ID that identifies the digital product." }, "domain": { "type": "string", "description": "Set to `twitch.ext.` \\+ ``." }, "cost": { "description": "Contains details about the digital product’s cost.", "type": "object", "required": [ "amount", "type" ], "properties": { "amount": { "type": "integer", "description": "The amount exchanged for the digital product.", "format": "int32" }, "type": { "type": "string", "description": "The type of currency exchanged. Possible values are: \n \n* bits", "enum": [ "bits" ] } } }, "inDevelopment": { "type": "boolean", "description": "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": { "type": "string", "description": "The name of the digital product." }, "expiration": { "type": "string", "description": "This field is always empty since you may purchase only unexpired products." }, "broadcast": { "type": "boolean", "description": "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." } } } } }, "GetExtensionTransactionsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "The list of transactions.", "items": { "$ref": "#/components/schemas/ExtensionTransaction" } }, "pagination": { "description": "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](https://dev.twitch.tv/docs/api/guide#pagination)", "type": "object", "properties": { "cursor": { "type": "string", "description": "The cursor used to get the next page of results. Use the cursor to set the request’s _after_ query parameter." } } } } }, "ChannelInformation": { "type": "object", "required": [ "broadcaster_id", "broadcaster_login", "broadcaster_name", "broadcaster_language", "game_name", "game_id", "title", "delay", "tags", "content_classification_labels", "is_branded_content" ], "properties": { "broadcaster_id": { "type": "string", "description": "An ID that uniquely identifies the broadcaster." }, "broadcaster_login": { "type": "string", "description": "The broadcaster’s login name." }, "broadcaster_name": { "type": "string", "description": "The broadcaster’s display name." }, "broadcaster_language": { "type": "string", "description": "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": { "type": "string", "description": "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": { "type": "string", "description": "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": { "type": "string", "description": "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": { "type": "integer", "description": "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.", "format": "int32" }, "tags": { "type": "array", "description": "The tags applied to the channel.", "items": { "type": "string" } }, "content_classification_labels": { "type": "array", "description": "The CCLs applied to the channel.", "items": { "type": "string" } }, "is_branded_content": { "type": "boolean", "description": "Boolean flag indicating if the channel has branded content." } } }, "GetChannelInformationResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "A list that contains information about the specified channels. The list is empty if the specified channels weren’t found.", "items": { "$ref": "#/components/schemas/ChannelInformation" } } } }, "ModifyChannelInformationBody": { "type": "object", "properties": { "game_id": { "type": "string", "description": "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": { "type": "string", "description": "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": { "type": "string", "description": "The title of the user’s stream. You may not set this field to an empty string." }, "delay": { "type": "integer", "description": "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).", "format": "int32" }, "tags": { "type": "array", "description": "A list of channel-defined tags to apply to the channel. To remove all tags from the channel, set tags to an empty array. Tags help identify the content that the channel streams. [Learn More](https://help.twitch.tv/s/article/guide-to-tags) \n \nA channel may specify a maximum of 10 tags. Each tag is limited to a maximum of 25 characters and may not be an empty string or contain spaces or special characters. Tags are case insensitive. For readability, consider using camelCasing or PascalCasing.", "items": { "type": "string" } }, "content_classification_labels": { "type": "array", "description": "List of labels that should be set as the Channel’s CCLs.", "items": { "type": "object", "required": [ "id", "is_enabled" ], "properties": { "id": { "type": "string", "description": "ID of the [Content Classification Labels](https://help.twitch.tv/s/article/content-classification-labels) that must be added/removed from the channel. Can be one of the following values: \n \n* DebatedSocialIssuesAndPolitics\n* DrugsIntoxication\n* SexualThemes\n* ViolentGraphic\n* Gambling\n* ProfanityVulgarity", "enum": [ "DebatedSocialIssuesAndPolitics", "DrugsIntoxication", "SexualThemes", "ViolentGraphic", "Gambling", "ProfanityVulgarity" ] }, "is_enabled": { "type": "boolean", "description": "Boolean flag indicating whether the label should be enabled (true) or disabled for the channel." } } } }, "is_branded_content": { "type": "boolean", "description": "Boolean flag indicating if the channel has branded content." } } }, "ChannelEditor": { "type": "object", "required": [ "user_id", "user_name", "created_at" ], "properties": { "user_id": { "type": "string", "description": "An ID that uniquely identifies a user with editor permissions." }, "user_name": { "type": "string", "description": "The user’s display name." }, "created_at": { "type": "string", "description": "The date and time, in RFC3339 format, when the user became one of the broadcaster’s editors.", "format": "date-time" } } }, "GetChannelEditorsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "A list of users that are editors for the specified broadcaster. The list is empty if the broadcaster doesn’t have editors.", "items": { "$ref": "#/components/schemas/ChannelEditor" } } } }, "GetFollowedChannelsResponse": { "type": "object", "required": [ "data", "total" ], "properties": { "data": { "type": "array", "description": "The list of broadcasters that the user follows. The list is in descending order by `followed_at` (with the most recently followed broadcaster first). The list is empty if the user doesn’t follow anyone.", "items": { "type": "object", "required": [ "broadcaster_id", "broadcaster_login", "broadcaster_name", "followed_at" ], "properties": { "broadcaster_id": { "type": "string", "description": "An ID that uniquely identifies the broadcaster that this user is following." }, "broadcaster_login": { "type": "string", "description": "The broadcaster’s login name." }, "broadcaster_name": { "type": "string", "description": "The broadcaster’s display name." }, "followed_at": { "type": "string", "description": "The UTC timestamp when the user started following the broadcaster.", "format": "date-time" } } } }, "pagination": { "description": "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](https://dev.twitch.tv/docs/api/guide#pagination).", "type": "object", "properties": { "cursor": { "type": "string", "description": "The cursor used to get the next page of results. Use the cursor to set the request’s _after_ query parameter." } } }, "total": { "type": "integer", "description": "The total number of broadcasters that the user follows. As someone pages through the list, the number may change as the user follows or unfollows broadcasters.", "format": "int32" } } }, "GetChannelFollowersResponse": { "type": "object", "required": [ "data", "total" ], "properties": { "data": { "type": "array", "description": "The list of users that follow the specified broadcaster. The list is in descending order by `followed_at` (with the most recent follower first). The list is empty if nobody follows the broadcaster, the specified `user_id` isn’t in the follower list, the user access token is missing the **moderator:read:followers** scope, or the user isn’t the broadcaster or moderator for the channel.", "items": { "type": "object", "required": [ "followed_at", "user_id", "user_login", "user_name" ], "properties": { "followed_at": { "type": "string", "description": "The UTC timestamp when the user started following the broadcaster.", "format": "date-time" }, "user_id": { "type": "string", "description": "An ID that uniquely identifies the user that’s following the broadcaster." }, "user_login": { "type": "string", "description": "The user’s login name." }, "user_name": { "type": "string", "description": "The user’s display name." } } } }, "pagination": { "description": "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](https://dev.twitch.tv/docs/api/guide#pagination).", "type": "object", "properties": { "cursor": { "type": "string", "description": "The cursor used to get the next page of results. Use the cursor to set the request’s _after_ query parameter." } } }, "total": { "type": "integer", "description": "The total number of users that follow this broadcaster. As someone pages through the list, the number of users may change as users follow or unfollow the broadcaster.", "format": "int32" } } }, "CreateCustomRewardsBody": { "type": "object", "required": [ "title", "cost" ], "properties": { "title": { "type": "string", "description": "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": { "type": "integer", "description": "The cost of the reward, in Channel Points. The minimum is 1 point.", "format": "int64" }, "prompt": { "type": "string", "description": "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": { "type": "boolean", "description": "A Boolean value that determines whether the reward is enabled. Viewers see only enabled rewards. The default is **true**." }, "background_color": { "type": "string", "description": "The background color to use for the reward. Specify the color using Hex format (for example, #9147FF)." }, "is_user_input_required": { "type": "boolean", "description": "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": { "type": "boolean", "description": "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": { "type": "integer", "description": "The maximum number of redemptions allowed per live stream. Applied only if `is_max_per_stream_enabled` is **true**. The minimum value is 1.", "format": "int32" }, "is_max_per_user_per_stream_enabled": { "type": "boolean", "description": "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": { "type": "integer", "description": "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.", "format": "int32" }, "is_global_cooldown_enabled": { "type": "boolean", "description": "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": { "type": "integer", "description": "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.", "format": "int32" }, "should_redemptions_skip_request_queue": { "type": "boolean", "description": "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**." } } }, "CustomReward": { "type": "object", "required": [ "broadcaster_id", "broadcaster_login", "broadcaster_name", "id", "title", "prompt", "cost", "image", "default_image", "background_color", "is_enabled", "is_user_input_required", "max_per_stream_setting", "max_per_user_per_stream_setting", "global_cooldown_setting", "is_paused", "is_in_stock", "should_redemptions_skip_request_queue", "redemptions_redeemed_current_stream", "cooldown_expires_at" ], "properties": { "broadcaster_id": { "type": "string", "description": "The ID that uniquely identifies the broadcaster." }, "broadcaster_login": { "type": "string", "description": "The broadcaster’s login name." }, "broadcaster_name": { "type": "string", "description": "The broadcaster’s display name." }, "id": { "type": "string", "description": "The ID that uniquely identifies this custom reward." }, "title": { "type": "string", "description": "The title of the reward." }, "prompt": { "type": "string", "description": "The prompt shown to the viewer when they redeem the reward if user input is required. See the `is_user_input_required` field." }, "cost": { "type": "integer", "description": "The cost of the reward in Channel Points.", "format": "int64" }, "image": { "description": "A set of custom images for the reward. This field is **null** if the broadcaster didn’t upload images.", "type": "object", "required": [ "url_1x", "url_2x", "url_4x" ], "properties": { "url_1x": { "type": "string", "description": "The URL to a small version of the image." }, "url_2x": { "type": "string", "description": "The URL to a medium version of the image." }, "url_4x": { "type": "string", "description": "The URL to a large version of the image." } } }, "default_image": { "description": "A set of default images for the reward.", "type": "object", "required": [ "url_1x", "url_2x", "url_4x" ], "properties": { "url_1x": { "type": "string", "description": "The URL to a small version of the image." }, "url_2x": { "type": "string", "description": "The URL to a medium version of the image." }, "url_4x": { "type": "string", "description": "The URL to a large version of the image." } } }, "background_color": { "type": "string", "description": "The background color to use for the reward. The color is in Hex format (for example, #00E5CB)." }, "is_enabled": { "type": "boolean", "description": "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": { "type": "boolean", "description": "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": { "description": "The settings used to determine whether to apply a maximum to the number of redemptions allowed per live stream.", "type": "object", "required": [ "is_enabled", "max_per_stream" ], "properties": { "is_enabled": { "type": "boolean", "description": "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": { "type": "integer", "description": "The maximum number of redemptions allowed per live stream.", "format": "int64" } } }, "max_per_user_per_stream_setting": { "description": "The settings used to determine whether to apply a maximum to the number of redemptions allowed per user per live stream.", "type": "object", "required": [ "is_enabled", "max_per_user_per_stream" ], "properties": { "is_enabled": { "type": "boolean", "description": "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": { "type": "integer", "description": "The maximum number of redemptions allowed per user per live stream.", "format": "int64" } } }, "global_cooldown_setting": { "description": "The settings used to determine whether to apply a cooldown period between redemptions and the length of the cooldown.", "type": "object", "required": [ "is_enabled", "global_cooldown_seconds" ], "properties": { "is_enabled": { "type": "boolean", "description": "A Boolean value that determines whether to apply a cooldown period. Is **true** if a cooldown period is enabled." }, "global_cooldown_seconds": { "type": "integer", "description": "The cooldown period, in seconds.", "format": "int64" } } }, "is_paused": { "type": "boolean", "description": "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": { "type": "boolean", "description": "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": { "type": "boolean", "description": "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": { "type": "integer", "description": "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.", "format": "int32", "nullable": true }, "cooldown_expires_at": { "type": "string", "description": "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.", "format": "date-time", "nullable": true } } }, "CreateCustomRewardsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "A list that contains the single custom reward you created.", "items": { "$ref": "#/components/schemas/CustomReward" } } } }, "GetCustomRewardResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "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.", "items": { "$ref": "#/components/schemas/CustomReward" } } } }, "CustomRewardRedemption": { "type": "object", "required": [ "broadcaster_id", "broadcaster_login", "broadcaster_name", "id", "user_id", "user_name", "user_login", "reward", "user_input", "status", "redeemed_at" ], "properties": { "broadcaster_id": { "type": "string", "description": "The ID that uniquely identifies the broadcaster." }, "broadcaster_login": { "type": "string", "description": "The broadcaster’s login name." }, "broadcaster_name": { "type": "string", "description": "The broadcaster’s display name." }, "id": { "type": "string", "description": "The ID that uniquely identifies this redemption.." }, "user_id": { "type": "string", "description": "The ID of the user that redeemed the reward." }, "user_name": { "type": "string", "description": "The user’s display name." }, "user_login": { "type": "string", "description": "The user’s login name." }, "reward": { "description": "An object that describes the reward that the user redeemed.", "type": "object", "required": [ "id", "title", "prompt", "cost" ], "properties": { "id": { "type": "string", "description": "The ID that uniquely identifies the reward." }, "title": { "type": "string", "description": "The reward’s title." }, "prompt": { "type": "string", "description": "The prompt displayed to the viewer if user input is required." }, "cost": { "type": "integer", "description": "The reward’s cost, in Channel Points.", "format": "int64" } } }, "user_input": { "type": "string", "description": "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": { "type": "string", "description": "The state of the redemption. Possible values are: \n \n* CANCELED\n* FULFILLED\n* UNFULFILLED", "enum": [ "CANCELED", "FULFILLED", "UNFULFILLED" ] }, "redeemed_at": { "type": "string", "description": "The date and time of when the reward was redeemed, in RFC3339 format.", "format": "date-time" } } }, "GetCustomRewardRedemptionResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "The list of redemptions for the specified reward. The list is empty if there are no redemptions that match the redemption criteria.", "items": { "$ref": "#/components/schemas/CustomRewardRedemption" } }, "pagination": { "description": "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](https://dev.twitch.tv/docs/api/guide#pagination)", "type": "object", "properties": { "cursor": { "type": "string", "description": "The cursor used to get the next page of results. Use the cursor to set the request’s _after_ query parameter." } } } } }, "UpdateCustomRewardBody": { "type": "object", "properties": { "title": { "type": "string", "description": "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": { "type": "string", "description": "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": { "type": "integer", "description": "The cost of the reward, in channel points. The minimum is 1 point.", "format": "int64" }, "background_color": { "type": "string", "description": "The background color to use for the reward. Specify the color using Hex format (for example, \\\\#00E5CB)." }, "is_enabled": { "type": "boolean", "description": "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": { "type": "boolean", "description": "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": { "type": "boolean", "description": "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": { "type": "integer", "description": "The maximum number of redemptions allowed per live stream. Applied only if `is_max_per_stream_enabled` is **true**. The minimum value is 1.", "format": "int64" }, "is_max_per_user_per_stream_enabled": { "type": "boolean", "description": "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": { "type": "integer", "description": "The maximum number of redemptions allowed per user per stream. Applied only if `is_max_per_user_per_stream_enabled` is **true**.", "format": "int64" }, "is_global_cooldown_enabled": { "type": "boolean", "description": "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": { "type": "integer", "description": "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.", "format": "int64" }, "is_paused": { "type": "boolean", "description": "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": { "type": "boolean", "description": "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." } } }, "UpdateCustomRewardResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "The list contains the single reward that you updated.", "items": { "$ref": "#/components/schemas/CustomReward" } } } }, "UpdateRedemptionStatusBody": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "description": "The status to set the redemption to. Possible values are: \n \n* CANCELED\n* FULFILLED\n \nSetting the status to CANCELED refunds the user’s channel points.", "enum": [ "CANCELED", "FULFILLED" ] } } }, "UpdateRedemptionStatusResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "The list contains the single redemption that you updated.", "items": { "$ref": "#/components/schemas/CustomRewardRedemption" } } } }, "CharityCampaign": { "type": "object", "required": [ "id", "broadcaster_id", "broadcaster_login", "broadcaster_name", "charity_name", "charity_description", "charity_logo", "charity_website", "current_amount", "target_amount" ], "properties": { "id": { "type": "string", "description": "An ID that identifies the charity campaign." }, "broadcaster_id": { "type": "string", "description": "An ID that identifies the broadcaster that’s running the campaign." }, "broadcaster_login": { "type": "string", "description": "The broadcaster’s login name." }, "broadcaster_name": { "type": "string", "description": "The broadcaster’s display name." }, "charity_name": { "type": "string", "description": "The charity’s name." }, "charity_description": { "type": "string", "description": "A description of the charity." }, "charity_logo": { "type": "string", "description": "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": { "type": "string", "description": "A URL to the charity’s website." }, "current_amount": { "description": "The current amount of donations that the campaign has received.", "type": "object", "required": [ "value", "decimal_places", "currency" ], "properties": { "value": { "type": "integer", "description": "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.", "format": "int32" }, "decimal_places": { "type": "integer", "description": "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: \n \n`value / 10^decimal_places`", "format": "int32" }, "currency": { "type": "string", "description": "The ISO-4217 three-letter currency code that identifies the type of currency in `value`." } } }, "target_amount": { "description": "The campaign’s fundraising goal. This field is **null** if the broadcaster has not defined a fundraising goal.", "type": "object", "required": [ "value", "decimal_places", "currency" ], "properties": { "value": { "type": "integer", "description": "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.", "format": "int32" }, "decimal_places": { "type": "integer", "description": "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: \n \n`value / 10^decimal_places`", "format": "int32" }, "currency": { "type": "string", "description": "The ISO-4217 three-letter currency code that identifies the type of currency in `value`." } } } } }, "GetCharityCampaignResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "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.", "items": { "$ref": "#/components/schemas/CharityCampaign" } } } }, "CharityCampaignDonation": { "type": "object", "required": [ "id", "campaign_id", "user_id", "user_login", "user_name", "amount" ], "properties": { "id": { "type": "string", "description": "An ID that identifies the donation. The ID is unique across campaigns." }, "campaign_id": { "type": "string", "description": "An ID that identifies the charity campaign that the donation applies to." }, "user_id": { "type": "string", "description": "An ID that identifies a user that donated money to the campaign." }, "user_login": { "type": "string", "description": "The user’s login name." }, "user_name": { "type": "string", "description": "The user’s display name." }, "amount": { "description": "An object that contains the amount of money that the user donated.", "type": "object", "required": [ "value", "decimal_places", "currency" ], "properties": { "value": { "type": "integer", "description": "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.", "format": "int32" }, "decimal_places": { "type": "integer", "description": "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: \n \n`value / 10^decimal_places`", "format": "int32" }, "currency": { "type": "string", "description": "The ISO-4217 three-letter currency code that identifies the type of currency in `value`." } } } } }, "GetCharityCampaignDonationsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "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.", "items": { "$ref": "#/components/schemas/CharityCampaignDonation" } }, "pagination": { "description": "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](https://dev.twitch.tv/docs/api/guide#pagination)", "type": "object", "properties": { "cursor": { "type": "string", "description": "The cursor used to get the next page of results. Use the cursor to set the request’s _after_ query parameter." } } } } }, "Chatter": { "type": "object", "required": [ "user_id", "user_login", "user_name" ], "properties": { "user_id": { "type": "string", "description": "The ID of a user that’s connected to the broadcaster’s chat room." }, "user_login": { "type": "string", "description": "The user’s login name." }, "user_name": { "type": "string", "description": "The user’s display name." } } }, "GetChattersResponse": { "type": "object", "required": [ "data", "total" ], "properties": { "data": { "type": "array", "description": "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.", "items": { "$ref": "#/components/schemas/Chatter" } }, "pagination": { "description": "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](https://dev.twitch.tv/docs/api/guide#pagination)", "type": "object", "properties": { "cursor": { "type": "string", "description": "The cursor used to get the next page of results. Use the cursor to set the request’s _after_ query parameter." } } }, "total": { "type": "integer", "description": "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.", "format": "int32" } } }, "ChannelEmote": { "type": "object", "required": [ "id", "name", "images", "tier", "emote_type", "emote_set_id", "format", "scale", "theme_mode" ], "properties": { "id": { "type": "string", "description": "An ID that identifies this emote." }, "name": { "type": "string", "description": "The name of the emote. This is the name that viewers type in the chat window to get the emote to appear." }, "images": { "description": "The image URLs for the emote. These image URLs always provide a static, non-animated emote image with a light background. \n \n**NOTE:** You should use the templated URL in the `template` field to fetch the image instead of using these URLs.", "type": "object", "required": [ "url_1x", "url_2x", "url_4x" ], "properties": { "url_1x": { "type": "string", "description": "A URL to the small version (28px x 28px) of the emote." }, "url_2x": { "type": "string", "description": "A URL to the medium version (56px x 56px) of the emote." }, "url_4x": { "type": "string", "description": "A URL to the large version (112px x 112px) of the emote." } } }, "tier": { "type": "string", "description": "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": { "type": "string", "description": "The type of emote. The possible values are: \n \n* bitstier — A custom Bits tier emote.\n* follower — A custom follower emote.\n* subscriptions — A custom subscriber emote.", "enum": [ "bitstier", "follower", "subscriptions" ] }, "emote_set_id": { "type": "string", "description": "An ID that identifies the emote set that the emote belongs to." }, "format": { "type": "array", "description": "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: \n \n* animated — An animated GIF is available for this emote.\n* static — A static PNG file is available for this emote.", "items": { "type": "string", "enum": [ "animated", "static" ] } }, "scale": { "type": "array", "description": "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: \n \n* 1.0 — A small version (28px x 28px) is available.\n* 2.0 — A medium version (56px x 56px) is available.\n* 3.0 — A large version (112px x 112px) is available.", "items": { "type": "string", "enum": [ "1.0", "2.0", "3.0" ] } }, "theme_mode": { "type": "array", "description": "The background themes that the emote is available in. Possible themes are: \n \n* dark\n* light", "items": { "type": "string", "enum": [ "dark", "light" ] } } } }, "GetChannelEmotesResponse": { "type": "object", "required": [ "data", "template" ], "properties": { "data": { "type": "array", "description": "The list of emotes that the specified broadcaster created. If the broadcaster hasn't created custom emotes, the list is empty.", "items": { "$ref": "#/components/schemas/ChannelEmote" } }, "template": { "type": "string", "description": "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](https://dev.twitch.tv/docs/irc/emotes#cdn-template). You should use this template instead of using the URLs in the `images` object." } } }, "GlobalEmote": { "type": "object", "required": [ "id", "name", "images", "format", "scale", "theme_mode" ], "properties": { "id": { "type": "string", "description": "An ID that identifies this emote." }, "name": { "type": "string", "description": "The name of the emote. This is the name that viewers type in the chat window to get the emote to appear." }, "images": { "description": "The image URLs for the emote. These image URLs always provide a static, non-animated emote image with a light background. \n \n**NOTE:** You should use the templated URL in the `template` field to fetch the image instead of using these URLs.", "type": "object", "required": [ "url_1x", "url_2x", "url_4x" ], "properties": { "url_1x": { "type": "string", "description": "A URL to the small version (28px x 28px) of the emote." }, "url_2x": { "type": "string", "description": "A URL to the medium version (56px x 56px) of the emote." }, "url_4x": { "type": "string", "description": "A URL to the large version (112px x 112px) of the emote." } } }, "format": { "type": "array", "description": "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: \n \n* animated — An animated GIF is available for this emote.\n* static — A static PNG file is available for this emote.", "items": { "type": "string", "enum": [ "animated", "static" ] } }, "scale": { "type": "array", "description": "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: \n \n* 1.0 — A small version (28px x 28px) is available.\n* 2.0 — A medium version (56px x 56px) is available.\n* 3.0 — A large version (112px x 112px) is available.", "items": { "type": "string", "enum": [ "1.0", "2.0", "3.0" ] } }, "theme_mode": { "type": "array", "description": "The background themes that the emote is available in. Possible themes are: \n \n* dark\n* light", "items": { "type": "string", "enum": [ "dark", "light" ] } } } }, "GetGlobalEmotesResponse": { "type": "object", "required": [ "data", "template" ], "properties": { "data": { "type": "array", "description": "The list of global emotes.", "items": { "$ref": "#/components/schemas/GlobalEmote" } }, "template": { "type": "string", "description": "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](https://dev.twitch.tv/docs/irc/emotes#cdn-template). You should use this template instead of using the URLs in the `images` object." } } }, "Emote": { "type": "object", "required": [ "id", "name", "images", "emote_type", "emote_set_id", "owner_id", "format", "scale", "theme_mode" ], "properties": { "id": { "type": "string", "description": "An ID that uniquely identifies this emote." }, "name": { "type": "string", "description": "The name of the emote. This is the name that viewers type in the chat window to get the emote to appear." }, "images": { "description": "The image URLs for the emote. These image URLs always provide a static, non-animated emote image with a light background. \n \n**NOTE:** You should use the templated URL in the `template` field to fetch the image instead of using these URLs.", "type": "object", "required": [ "url_1x", "url_2x", "url_4x" ], "properties": { "url_1x": { "type": "string", "description": "A URL to the small version (28px x 28px) of the emote." }, "url_2x": { "type": "string", "description": "A URL to the medium version (56px x 56px) of the emote." }, "url_4x": { "type": "string", "description": "A URL to the large version (112px x 112px) of the emote." } } }, "emote_type": { "type": "string", "description": "The type of emote. The possible values are: \n \n* bitstier — A Bits tier emote.\n* follower — A follower emote.\n* subscriptions — A subscriber emote.", "enum": [ "bitstier", "follower", "subscriptions" ] }, "emote_set_id": { "type": "string", "description": "An ID that identifies the emote set that the emote belongs to." }, "owner_id": { "type": "string", "description": "The ID of the broadcaster who owns the emote." }, "format": { "type": "array", "description": "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: \n \n* animated — An animated GIF is available for this emote.\n* static — A static PNG file is available for this emote.", "items": { "type": "string", "enum": [ "animated", "static" ] } }, "scale": { "type": "array", "description": "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: \n \n* 1.0 — A small version (28px x 28px) is available.\n* 2.0 — A medium version (56px x 56px) is available.\n* 3.0 — A large version (112px x 112px) is available.", "items": { "type": "string", "enum": [ "1.0", "2.0", "3.0" ] } }, "theme_mode": { "type": "array", "description": "The background themes that the emote is available in. Possible themes are: \n \n* dark\n* light", "items": { "type": "string", "enum": [ "dark", "light" ] } } } }, "GetEmoteSetsResponse": { "type": "object", "required": [ "data", "template" ], "properties": { "data": { "type": "array", "description": "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.", "items": { "$ref": "#/components/schemas/Emote" } }, "template": { "type": "string", "description": "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](https://dev.twitch.tv/docs/irc/emotes#cdn-template). You should use this template instead of using the URLs in the `images` object." } } }, "ChatBadge": { "type": "object", "required": [ "set_id", "versions" ], "properties": { "set_id": { "type": "string", "description": "An ID that identifies this set of chat badges. For example, Bits or Subscriber." }, "versions": { "type": "array", "description": "The list of chat badges in this set.", "items": { "type": "object", "required": [ "id", "image_url_1x", "image_url_2x", "image_url_4x", "title", "description", "click_action", "click_url" ], "properties": { "id": { "type": "string", "description": "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": { "type": "string", "description": "A URL to the small version (18px x 18px) of the badge." }, "image_url_2x": { "type": "string", "description": "A URL to the medium version (36px x 36px) of the badge." }, "image_url_4x": { "type": "string", "description": "A URL to the large version (72px x 72px) of the badge." }, "title": { "type": "string", "description": "The title of the badge." }, "description": { "type": "string", "description": "The description of the badge." }, "click_action": { "type": "string", "description": "The action to take when clicking on the badge. Set to `null` if no action is specified." }, "click_url": { "type": "string", "description": "The URL to navigate to when clicking on the badge. Set to `null` if no URL is specified." } } } } } }, "GetChannelChatBadgesResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "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`.", "items": { "$ref": "#/components/schemas/ChatBadge" } } } }, "GetGlobalChatBadgesResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "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`.", "items": { "$ref": "#/components/schemas/ChatBadge" } } } }, "ChatSettings": { "type": "object", "required": [ "broadcaster_id", "emote_mode", "follower_mode", "follower_mode_duration", "slow_mode", "slow_mode_wait_time", "subscriber_mode", "unique_chat_mode" ], "properties": { "broadcaster_id": { "type": "string", "description": "The ID of the broadcaster specified in the request." }, "emote_mode": { "type": "boolean", "description": "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": { "type": "boolean", "description": "A Boolean value that determines whether the broadcaster restricts the chat room to followers only. \n \nIs **true** if the broadcaster restricts the chat room to followers only; otherwise, **false**. \n \nSee 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": { "type": "integer", "description": "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**.", "format": "int32", "nullable": true }, "moderator_id": { "type": "string", "description": "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": { "type": "boolean", "description": "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**. \n \nThe 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": { "type": "integer", "description": "The amount of time, in seconds, that messages are delayed before appearing in chat. Is **null** if `non_moderator_chat_delay` is **false**. \n \nThe 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.", "format": "int32", "nullable": true }, "slow_mode": { "type": "boolean", "description": "A Boolean value that determines whether the broadcaster limits how often users in the chat room are allowed to send messages. \n \nIs **true** if the broadcaster applies a delay; otherwise, **false**. \n \nSee the `slow_mode_wait_time` field for the delay." }, "slow_mode_wait_time": { "type": "integer", "description": "The amount of time, in seconds, that users must wait between sending messages. \n \nIs **null** if slow\\_mode is **false**.", "format": "int32", "nullable": true }, "subscriber_mode": { "type": "boolean", "description": "A Boolean value that determines whether only users that subscribe to the broadcaster’s channel may talk in the chat room. \n \nIs **true** if the broadcaster restricts the chat room to subscribers only; otherwise, **false**." }, "unique_chat_mode": { "type": "boolean", "description": "A Boolean value that determines whether the broadcaster requires users to post only unique messages in the chat room. \n \nIs **true** if the broadcaster requires unique messages only; otherwise, **false**." } } }, "GetChatSettingsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "The list of chat settings. The list contains a single object with all the settings.", "items": { "$ref": "#/components/schemas/ChatSettings" } } } }, "GetSharedChatSessionResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "", "items": { "type": "object", "required": [ "session_id", "host_broadcaster_id", "participants", "created_at", "updated_at" ], "properties": { "session_id": { "type": "string", "description": "The unique identifier for the shared chat session." }, "host_broadcaster_id": { "type": "string", "description": "The User ID of the host channel." }, "participants": { "type": "array", "description": "The list of participants in the session.", "items": { "type": "object", "required": [ "broadcaster_id" ], "properties": { "broadcaster_id": { "type": "string", "description": "The User ID of the participant channel." } } } }, "created_at": { "type": "string", "description": "The UTC date and time (in RFC3339 format) for when the session was created.", "format": "date-time" }, "updated_at": { "type": "string", "description": "The UTC date and time (in RFC3339 format) for when the session was last updated.", "format": "date-time" } } } } } }, "GetUserEmotesResponse": { "type": "object", "required": [ "data", "template" ], "properties": { "data": { "type": "array", "description": "", "items": { "type": "object", "required": [ "id", "name", "emote_type", "emote_set_id", "owner_id", "format", "scale", "theme_mode" ], "properties": { "id": { "type": "string", "description": "An ID that uniquely identifies this emote." }, "name": { "type": "string", "description": "The User ID of broadcaster whose channel is receiving the unban request." }, "emote_type": { "type": "string", "description": "The type of emote. The possible values are: \n \n* **none** — No emote type was assigned to this emote.\n* **bitstier** — A Bits tier emote.\n* **follower** — A follower emote.\n* **subscriptions** — A subscriber emote.\n* **channelpoints** — An emote granted by using channel points.\n* **rewards** — An emote granted to the user through a special event.\n* **hypetrain** — An emote granted for participation in a Hype Train.\n* **prime** — An emote granted for linking an Amazon Prime account.\n* **turbo** — An emote granted for having Twitch Turbo.\n* **smilies** — Emoticons supported by Twitch.\n* **globals** — An emote accessible by everyone.\n* **owl2019** — Emotes related to Overwatch League 2019.\n* **twofactor** — Emotes granted by enabling two-factor authentication on an account.\n* **limitedtime** — Emotes that were granted for only a limited time.", "enum": [ "none", "bitstier", "follower", "subscriptions", "channelpoints", "rewards", "hypetrain", "prime", "turbo", "smilies", "globals", "owl2019", "twofactor", "limitedtime" ] }, "emote_set_id": { "type": "string", "description": "An ID that identifies the emote set that the emote belongs to." }, "owner_id": { "type": "string", "description": "The ID of the broadcaster who owns the emote." }, "format": { "type": "array", "description": "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. \n \n* **animated** — An animated GIF is available for this emote.\n* **static** — A static PNG file is available for this emote.", "items": { "type": "string" } }, "scale": { "type": "array", "description": "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\\. \n \n* **1.0** — A small version (28px x 28px) is available.\n* **2.0** — A medium version (56px x 56px) is available.\n* **3.0** — A large version (112px x 112px) is available.", "items": { "type": "string" } }, "theme_mode": { "type": "array", "description": "The background themes that the emote is available in. \n \n* **dark**\n* **light**", "items": { "type": "string" } } } } }, "template": { "type": "string", "description": "A templated URL. Uses 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. \n \n For information about what the template looks like and how to use it to fetch emotes, see [Emote CDN URL](https://dev.twitch.tv/docs/irc/emotes#cdn-template) format." }, "pagination": { "description": "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. \n \n For more information about pagination support, see [Twitch API Guide - Pagination](https://dev.twitch.tv/docs/api/guide#pagination).", "type": "object", "properties": { "cursor": { "type": "string", "description": "The cursor used to get the next page of results. Use the cursor to set the request’s after query parameter." } } } } }, "UpdateChatSettingsBody": { "type": "object", "properties": { "emote_mode": { "type": "boolean", "description": "A Boolean value that determines whether chat messages must contain only emotes. \n \nSet to **true** if only emotes are allowed; otherwise, **false**. The default is **false**." }, "follower_mode": { "type": "boolean", "description": "A Boolean value that determines whether the broadcaster restricts the chat room to followers only. \n \nSet to **true** if the broadcaster restricts the chat room to followers only; otherwise, **false**. The default is **true**. \n \nTo 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": { "type": "integer", "description": "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.", "format": "int32" }, "non_moderator_chat_delay": { "type": "boolean", "description": "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. \n \nSet to **true** if the broadcaster applies a delay; otherwise, **false**. The default is **false**. \n \nTo specify the length of the delay, see the `non_moderator_chat_delay_duration` field." }, "non_moderator_chat_delay_duration": { "type": "integer", "description": "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: \n \n* 2 — 2 second delay (recommended)\n* 4 — 4 second delay\n* 6 — 6 second delay", "format": "int32", "enum": [ 2, 4, 6 ] }, "slow_mode": { "type": "boolean", "description": "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**. \n \nTo specify the delay, see the `slow_mode_wait_time` field." }, "slow_mode_wait_time": { "type": "integer", "description": "The amount of time, in seconds, that users must wait between sending messages. Set only if `slow_mode` is **true**. \n \nPossible values are: 3 (3 second delay) through 120 (2 minute delay). The default is 30 seconds.", "format": "int32" }, "subscriber_mode": { "type": "boolean", "description": "A Boolean value that determines whether only users that subscribe to the broadcaster’s channel may talk in the chat room. \n \nSet to **true** if the broadcaster restricts the chat room to subscribers only; otherwise, **false**. The default is **false**." }, "unique_chat_mode": { "type": "boolean", "description": "A Boolean value that determines whether the broadcaster requires users to post only unique messages in the chat room. \n \nSet to **true** if the broadcaster allows only unique messages; otherwise, **false**. The default is **false**." } } }, "ChatSettingsUpdated": { "type": "object", "required": [ "broadcaster_id", "emote_mode", "follower_mode", "follower_mode_duration", "non_moderator_chat_delay", "non_moderator_chat_delay_duration", "slow_mode", "slow_mode_wait_time", "subscriber_mode", "unique_chat_mode" ], "properties": { "broadcaster_id": { "type": "string", "description": "The ID of the broadcaster specified in the request." }, "emote_mode": { "type": "boolean", "description": "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": { "type": "boolean", "description": "A Boolean value that determines whether the broadcaster restricts the chat room to followers only. \n \nIs **true** if the broadcaster restricts the chat room to followers only; otherwise, **false**. \n \nSee 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": { "type": "integer", "description": "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**.", "format": "int32", "nullable": true }, "moderator_id": { "type": "string", "description": "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": { "type": "boolean", "description": "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": { "type": "integer", "description": "The amount of time, in seconds, that messages are delayed before appearing in chat. Is **null** if `non_moderator_chat_delay` is **false**.", "format": "int32", "nullable": true }, "slow_mode": { "type": "boolean", "description": "A Boolean value that determines whether the broadcaster limits how often users in the chat room are allowed to send messages. \n \nIs **true** if the broadcaster applies a delay; otherwise, **false**. \n \nSee the `slow_mode_wait_time` field for the delay." }, "slow_mode_wait_time": { "type": "integer", "description": "The amount of time, in seconds, that users must wait between sending messages. \n \nIs **null** if slow\\_mode is **false**.", "format": "int32", "nullable": true }, "subscriber_mode": { "type": "boolean", "description": "A Boolean value that determines whether only users that subscribe to the broadcaster’s channel may talk in the chat room. \n \nIs **true** if the broadcaster restricts the chat room to subscribers only; otherwise, **false**." }, "unique_chat_mode": { "type": "boolean", "description": "A Boolean value that determines whether the broadcaster requires users to post only unique messages in the chat room. \n \nIs **true** if the broadcaster requires unique messages only; otherwise, **false**." } } }, "UpdateChatSettingsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "The list of chat settings. The list contains a single object with all the settings.", "items": { "$ref": "#/components/schemas/ChatSettingsUpdated" } } } }, "SendChatAnnouncementBody": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "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": { "type": "string", "description": "The color used to highlight the announcement. Possible case-sensitive values are: \n \n* blue\n* green\n* orange\n* purple\n* primary (default)\n \nIf `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](https://www.twitch.tv/settings/profile), **Channel and Videos**, and **Brand**).", "enum": [ "blue", "green", "orange", "purple", "primary" ], "default": "primary" }, "source-only": { "type": "boolean", "description": "Determines if the chat announcement is sent only to the source channel defined by broadcaster\\_id during a shared chat session. This has no effect if the announcement is not sent sent during a shared chat session. The default value is `false`. NOTE: This parameter can only be set when utilizing an App Access Token. It cannot be specified when a User Access Token is used, and will instead result in an HTTP 400 error." } } }, "SendChatMessageBody": { "type": "object", "required": [ "broadcaster_id", "sender_id", "message" ], "properties": { "broadcaster_id": { "type": "string", "description": "The ID of the broadcaster whose chat room the message will be sent to." }, "sender_id": { "type": "string", "description": "The ID of the user sending the message. This ID must match the user ID in the user access token." }, "message": { "type": "string", "description": "The message to send. The message is limited to a maximum of 500 characters. Chat messages can also include emoticons. To include emoticons, use the name of the emote. The names are case sensitive. Don’t include colons around the name (e.g., :bleedPurple:). If Twitch recognizes the name, Twitch converts the name to the emote before writing the chat message to the chat room" }, "reply_parent_message_id": { "type": "string", "description": "The ID of the chat message being replied to." }, "for_source_only": { "type": "boolean", "description": "**NOTE:** This parameter can only be set when utilizing an App Access Token. It cannot be specified when a User Access Token is used, and will instead result in an HTTP 400 error. \n \nDetermines if the chat message is sent only to the source channel (defined by _broadcaster\\_id_) during a shared chat session. This has no effect if the message is not sent during a shared chat session. \n \nIf this parameter is not set, the default value when using an App Access Token is `false`. On May 19, 2025 the default value for this parameter will be updated to `true`, and chat messages sent using an App Access Token will only be shared with the source channel by default. If you prefer to send a chat message to both channels in a shared chat session, make sure this parameter is explicitly set to `false` in your API request before May 19." } } }, "SendChatMessageResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "", "items": { "type": "object", "required": [ "message_id", "is_sent" ], "properties": { "message_id": { "type": "string", "description": "The message id for the message that was sent." }, "is_sent": { "type": "boolean", "description": "If the message passed all checks and was sent." }, "drop_reason": { "description": "The reason the message was dropped, if any.", "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Code for why the message was dropped." }, "message": { "type": "string", "description": "Message for why the message was dropped." } } } } } } } }, "UserChatColor": { "type": "object", "required": [ "user_id", "user_login", "user_name", "color" ], "properties": { "user_id": { "type": "string", "description": "An ID that uniquely identifies the user." }, "user_login": { "type": "string", "description": "The user’s login name." }, "user_name": { "type": "string", "description": "The user’s display name." }, "color": { "type": "string", "description": "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." } } }, "GetUserChatColorResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "The list of users and the color code they use for their name.", "items": { "$ref": "#/components/schemas/UserChatColor" } } } }, "CreateClipResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "A list containing the created clip.", "items": { "type": "object", "required": [ "id", "edit_url" ], "properties": { "id": { "type": "string", "description": "An ID that uniquely identifies the clip." }, "edit_url": { "type": "string", "description": "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](https://help.twitch.tv/s/article/how-to-use-clips) \n \nThe URL is valid for up to 24 hours or until the clip is published, whichever comes first." } } } } } }, "CreateClipFromVODResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "A list containing the created clip.", "items": { "type": "object", "required": [ "id", "edit_url" ], "properties": { "id": { "type": "string", "description": "An ID that uniquely identifies the clip." }, "edit_url": { "type": "string", "description": "A URL you can use to edit the clip’s title, feature the clip, create a portrait version of the clip, download the clip media, and share the clip directly to third-party platforms." } } } } } }, "Clip": { "type": "object", "required": [ "id", "url", "embed_url", "broadcaster_id", "broadcaster_name", "creator_id", "creator_name", "video_id", "game_id", "language", "title", "view_count", "created_at", "thumbnail_url", "duration", "vod_offset", "is_featured" ], "properties": { "id": { "type": "string", "description": "An ID that uniquely identifies the clip." }, "url": { "type": "string", "description": "A URL to the clip." }, "embed_url": { "type": "string", "description": "A URL that you can use in an iframe to embed the clip (see [Embedding Video and Clips](https://dev.twitch.tv/docs/embed/video-and-clips/))." }, "broadcaster_id": { "type": "string", "description": "An ID that identifies the broadcaster that the video was clipped from." }, "broadcaster_name": { "type": "string", "description": "The broadcaster’s display name." }, "creator_id": { "type": "string", "description": "An ID that identifies the user that created the clip." }, "creator_name": { "type": "string", "description": "The user’s display name." }, "video_id": { "type": "string", "description": "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": { "type": "string", "description": "The ID of the game that was being played when the clip was created." }, "language": { "type": "string", "description": "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": { "type": "string", "description": "The title of the clip." }, "view_count": { "type": "integer", "description": "The number of times the clip has been viewed.", "format": "int32" }, "created_at": { "type": "string", "description": "The date and time of when the clip was created. The date and time is in RFC3339 format.", "format": "date-time" }, "thumbnail_url": { "type": "string", "description": "A URL to a thumbnail image of the clip." }, "duration": { "type": "number", "description": "The length of the clip, in seconds. Precision is 0.1.", "format": "float" }, "vod_offset": { "type": "integer", "description": "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`). \n \nNote 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.", "format": "int32", "nullable": true }, "is_featured": { "type": "boolean", "description": "A Boolean value that indicates if the clip is featured or not." } } }, "GetClipsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "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.", "items": { "$ref": "#/components/schemas/Clip" } }, "pagination": { "description": "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](https://dev.twitch.tv/docs/api/guide#pagination)", "type": "object", "properties": { "cursor": { "type": "string", "description": "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." } } } } }, "GetClipsDownloadResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "List of clips and their download URLs.", "items": { "type": "object", "required": [ "clip_id", "landscape_download_url", "portrait_download_url" ], "properties": { "clip_id": { "type": "string", "description": "An ID that uniquely identifies the clip." }, "landscape_download_url": { "type": "string", "description": "The landscape URL to download the clip. This field is `null` if the URL is not available." }, "portrait_download_url": { "type": "string", "description": "The portrait URL to download the clip. This field is `null` if the URL is not available." } } } } } }, "GetConduitsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "List of information about the client’s conduits.", "items": { "type": "object", "required": [ "id", "shard_count" ], "properties": { "id": { "type": "string", "description": "Conduit ID." }, "shard_count": { "type": "integer", "description": "Number of shards associated with this conduit.", "format": "int32" } } } } } }, "CreateConduitsBody": { "type": "object", "required": [ "shard_count" ], "properties": { "shard_count": { "type": "integer", "description": "The number of shards to create for this conduit.", "format": "int32" } } }, "CreateConduitsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "List of information about the client’s conduits.", "items": { "type": "object", "required": [ "id", "shard_count" ], "properties": { "id": { "type": "string", "description": "Conduit ID." }, "shard_count": { "type": "integer", "description": "Number of shards created for this conduit.", "format": "int32" } } } } } }, "UpdateConduitsBody": { "type": "object", "required": [ "id", "shard_count" ], "properties": { "id": { "type": "string", "description": "Conduit ID." }, "shard_count": { "type": "integer", "description": "The new number of shards for this conduit.", "format": "int32" } } }, "UpdateConduitsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "List of information about the client’s conduits.", "items": { "type": "object", "required": [ "id", "shard_count" ], "properties": { "id": { "type": "string", "description": "Conduit ID." }, "shard_count": { "type": "integer", "description": "Number of shards associated with this conduit after the update.", "format": "int32" } } } } } }, "GetConduitShardsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "List of information about a conduit's shards.", "items": { "type": "object", "required": [ "id", "status", "transport" ], "properties": { "id": { "type": "string", "description": "Shard ID." }, "status": { "type": "string", "description": "The shard status. The subscriber receives events only for enabled shards. Possible values are: \n \n* enabled — The shard is enabled.\n* webhook\\_callback\\_verification\\_pending — The shard is pending verification of the specified callback URL.\n* webhook\\_callback\\_verification\\_failed — The specified callback URL failed verification.\n* notification\\_failures\\_exceeded — The notification delivery failure rate was too high.\n* websocket\\_disconnected — The client closed the connection.\n* websocket\\_failed\\_ping\\_pong — The client failed to respond to a ping message.\n* websocket\\_received\\_inbound\\_traffic — The client sent a non-pong message. Clients may only send pong messages (and only in response to a ping message).\n* websocket\\_internal\\_error — The Twitch WebSocket server experienced an unexpected error.\n* websocket\\_network\\_timeout — The Twitch WebSocket server timed out writing the message to the client.\n* websocket\\_network\\_error — The Twitch WebSocket server experienced a network error writing the message to the client.\n* websocket\\_failed\\_to\\_reconnect - The client failed to reconnect to the Twitch WebSocket server within the required time after a Reconnect Message.", "enum": [ "enabled", "webhook_callback_verification_pending", "webhook_callback_verification_failed", "notification_failures_exceeded", "websocket_disconnected", "websocket_failed_ping_pong", "websocket_received_inbound_traffic", "websocket_internal_error", "websocket_network_timeout", "websocket_network_error", "websocket_failed_to_reconnect" ] }, "transport": { "description": "The transport details used to send the notifications.", "type": "object", "required": [ "method" ], "properties": { "method": { "type": "string", "description": "The transport method. Possible values are: \n \n* webhook\n* websocket", "enum": [ "webhook", "websocket" ] }, "callback": { "type": "string", "description": "The callback URL where the notifications are sent. Included only if method is set to webhook." }, "session_id": { "type": "string", "description": "An ID that identifies the WebSocket that notifications are sent to. Included only if method is set to websocket." }, "connected_at": { "type": "string", "description": "The UTC date and time that the WebSocket connection was established. Included only if method is set to websocket.", "format": "date-time" }, "disconnected_at": { "type": "string", "description": "The UTC date and time that the WebSocket connection was lost. Included only if method is set to websocket.", "format": "date-time" } } } } } }, "pagination": { "description": "Contains information used to page through a list of results. The object is empty if there are no more pages left to page through.", "type": "object", "properties": { "cursor": { "type": "string", "description": "The cursor used to get the next page of results. Use the cursor to set the request’s after query parameter." } } } } }, "UpdateConduitShardsBody": { "type": "object", "required": [ "conduit_id", "shards" ], "properties": { "conduit_id": { "type": "string", "description": "Conduit ID." }, "shards": { "type": "array", "description": "List of shards to update.", "items": { "type": "object", "required": [ "id", "transport" ], "properties": { "id": { "type": "string", "description": "Shard ID." }, "transport": { "description": "The transport details that you want Twitch to use when sending you notifications.", "type": "object", "properties": { "method": { "type": "string", "description": "The transport method. Possible values are: \n \n* webhook\n* websocket", "enum": [ "webhook", "websocket" ] }, "callback": { "type": "string", "description": "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": { "type": "string", "description": "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": { "type": "string", "description": "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." } } } } } } } }, "UpdateConduitShardsResponse": { "type": "object", "required": [ "data", "errors" ], "properties": { "data": { "type": "array", "description": "List of successful shard updates.", "items": { "type": "object", "required": [ "id", "status", "transport" ], "properties": { "id": { "type": "string", "description": "Shard ID." }, "status": { "type": "string", "description": "The shard status. The subscriber receives events only for enabled shards. Possible values are: \n \n* enabled — The shard is enabled.\n* webhook\\_callback\\_verification\\_pending — The shard is pending verification of the specified callback URL.\n* webhook\\_callback\\_verification\\_failed — The specified callback URL failed verification.\n* notification\\_failures\\_exceeded — The notification delivery failure rate was too high.\n* websocket\\_disconnected — The client closed the connection.\n* websocket\\_failed\\_ping\\_pong — The client failed to respond to a ping message.\n* websocket\\_received\\_inbound\\_traffic — The client sent a non-pong message. Clients may only send pong messages (and only in response to a ping message).\n* websocket\\_internal\\_error — The Twitch WebSocket server experienced an unexpected error.\n* websocket\\_network\\_timeout — The Twitch WebSocket server timed out writing the message to the client.\n* websocket\\_network\\_error — The Twitch WebSocket server experienced a network error writing the message to the client.\n* websocket\\_failed\\_to\\_reconnect - The client failed to reconnect to the Twitch WebSocket server within the required time after a Reconnect Message.", "enum": [ "enabled", "webhook_callback_verification_pending", "webhook_callback_verification_failed", "notification_failures_exceeded", "websocket_disconnected", "websocket_failed_ping_pong", "websocket_received_inbound_traffic", "websocket_internal_error", "websocket_network_timeout", "websocket_network_error", "websocket_failed_to_reconnect" ] }, "transport": { "description": "The transport details used to send the notifications.", "type": "object", "required": [ "method" ], "properties": { "method": { "type": "string", "description": "The transport method. Possible values are: \n \n* webhook\n* websocket", "enum": [ "webhook", "websocket" ] }, "callback": { "type": "string", "description": "The callback URL where the notifications are sent. Included only if method is set to webhook." }, "session_id": { "type": "string", "description": "An ID that identifies the WebSocket that notifications are sent to. Included only if method is set to websocket." }, "connected_at": { "type": "string", "description": "The UTC date and time that the WebSocket connection was established. Included only if method is set to websocket.", "format": "date-time" }, "disconnected_at": { "type": "string", "description": "The UTC date and time that the WebSocket connection was lost. Included only if method is set to websocket.", "format": "date-time" } } } } } }, "errors": { "type": "array", "description": "List of unsuccessful updates.", "items": { "type": "object", "required": [ "id", "message", "code" ], "properties": { "id": { "type": "string", "description": "Shard ID." }, "message": { "type": "string", "description": "The error that occurred while updating the shard. Possible errors: \n \n* The length of the string in the secret field is not valid.\n* The URL in the transport's callback field is not valid. The URL must use the HTTPS protocol and the 443 port number.\n* The value specified in the method field is not valid.\n* The callback field is required if you specify the webhook transport method.\n* The session\\_id field is required if you specify the WebSocket transport method.\n* The websocket session is not connected.\n* The shard id is outside of the conduit’s range." }, "code": { "type": "string", "description": "Error codes used to represent a specific error condition while attempting to update shards." } } } } } }, "ContentClassificationLabel": { "type": "object", "required": [ "id", "description", "name" ], "properties": { "id": { "type": "string", "description": "Unique identifier for the CCL." }, "description": { "type": "string", "description": "Localized description of the CCL." }, "name": { "type": "string", "description": "Localized name of the CCL." } } }, "GetContentClassificationLabelsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "A list that contains information about the available content classification labels.", "items": { "$ref": "#/components/schemas/ContentClassificationLabel" } } } }, "DropsEntitlement": { "type": "object", "required": [ "id", "benefit_id", "timestamp", "user_id", "game_id", "fulfillment_status", "last_updated" ], "properties": { "id": { "type": "string", "description": "An ID that identifies the entitlement." }, "benefit_id": { "type": "string", "description": "An ID that identifies the benefit (reward)." }, "timestamp": { "type": "string", "description": "The UTC date and time (in RFC3339 format) of when the entitlement was granted.", "format": "date-time" }, "user_id": { "type": "string", "description": "An ID that identifies the user who was granted the entitlement." }, "game_id": { "type": "string", "description": "An ID that identifies the game the user was playing when the reward was entitled." }, "fulfillment_status": { "type": "string", "description": "The entitlement’s fulfillment status. Possible values are: \n \n* CLAIMED\n* FULFILLED", "enum": [ "CLAIMED", "FULFILLED" ] }, "last_updated": { "type": "string", "description": "The UTC date and time (in RFC3339 format) of when the entitlement was last updated.", "format": "date-time" } } }, "GetDropsEntitlementsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "The list of entitlements.", "items": { "$ref": "#/components/schemas/DropsEntitlement" } }, "pagination": { "description": "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](https://dev.twitch.tv/docs/api/guide#pagination)", "type": "object", "properties": { "cursor": { "type": "string", "description": "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." } } } } }, "UpdateDropsEntitlementsBody": { "type": "object", "properties": { "entitlement_ids": { "type": "array", "description": "A list of IDs that identify the entitlements to update. You may specify a maximum of 100 IDs.", "items": { "type": "string" } }, "fulfillment_status": { "type": "string", "description": "The fulfillment status to set the entitlements to. Possible values are: \n \n* CLAIMED — The user claimed the benefit.\n* FULFILLED — The developer granted the benefit that the user claimed.", "enum": [ "CLAIMED", "FULFILLED" ] } } }, "DropsEntitlementUpdated": { "type": "object", "required": [ "status", "ids" ], "properties": { "status": { "type": "string", "description": "A string that indicates whether the status of the entitlements in the `ids` field were successfully updated. Possible values are: \n \n* INVALID\\_ID — The entitlement IDs in the `ids` field are not valid.\n* NOT\\_FOUND — The entitlement IDs in the `ids` field were not found.\n* SUCCESS — The status of the entitlements in the `ids` field were successfully updated.\n* UNAUTHORIZED — The user or organization identified by the user access token is not authorized to update the entitlements.\n* UPDATE\\_FAILED — The update failed. These are considered transient errors and the request should be retried later.", "enum": [ "INVALID_ID", "NOT_FOUND", "SUCCESS", "UNAUTHORIZED", "UPDATE_FAILED" ] }, "ids": { "type": "array", "description": "The list of entitlements that the status in the `status` field applies to.", "items": { "type": "string" } } } }, "UpdateDropsEntitlementsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "A list that indicates which entitlements were successfully updated and those that weren’t.", "items": { "$ref": "#/components/schemas/DropsEntitlementUpdated" } } } }, "ExtensionConfigurationSegment": { "type": "object", "required": [ "segment", "content", "version" ], "properties": { "segment": { "type": "string", "description": "The type of segment. Possible values are: \n \n* broadcaster\n* developer\n* global", "enum": [ "broadcaster", "developer", "global" ] }, "broadcaster_id": { "type": "string", "description": "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": { "type": "string", "description": "The contents of the segment. This string may be a plain-text string or a string-encoded JSON object." }, "version": { "type": "string", "description": "The version number that identifies this definition of the segment’s data." } } }, "GetExtensionConfigurationSegmentResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "The list of requested configuration segments. The list is returned in the same order that you specified the list of segments in the request.", "items": { "$ref": "#/components/schemas/ExtensionConfigurationSegment" } } } }, "SetExtensionConfigurationSegmentBody": { "type": "object", "required": [ "extension_id", "segment" ], "properties": { "extension_id": { "type": "string", "description": "The ID of the extension to update." }, "segment": { "type": "string", "description": "The configuration segment to update. Possible case-sensitive values are: \n \n* broadcaster\n* developer\n* global", "enum": [ "broadcaster", "developer", "global" ] }, "broadcaster_id": { "type": "string", "description": "The ID of the broadcaster that installed the extension. Include this field only if the `segment` is set to developer or broadcaster." }, "content": { "type": "string", "description": "The contents of the segment. This string may be a plain-text string or a string-encoded JSON object." }, "version": { "type": "string", "description": "The version number that identifies this definition of the segment’s data. If not specified, the latest definition is updated." } } }, "SetExtensionRequiredConfigurationBody": { "type": "object", "required": [ "extension_id", "extension_version", "required_configuration" ], "properties": { "extension_id": { "type": "string", "description": "The ID of the extension to update." }, "extension_version": { "type": "string", "description": "The version of the extension to update." }, "required_configuration": { "type": "string", "description": "The required\\_configuration string to use with the extension." } } }, "SendExtensionPubSubMessageBody": { "type": "object", "required": [ "target", "broadcaster_id", "message" ], "properties": { "target": { "type": "array", "description": "The target of the message. Possible values are: \n \n* broadcast\n* global\n* whisper-\n \nIf `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.", "items": { "type": "string", "enum": [ "broadcast", "global", "whisper-" ] } }, "broadcaster_id": { "type": "string", "description": "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": { "type": "boolean", "description": "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": { "type": "string", "description": "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." } } }, "ExtensionLiveChannel": { "type": "object", "required": [ "broadcaster_id", "broadcaster_name", "game_name", "game_id", "title" ], "properties": { "broadcaster_id": { "type": "string", "description": "The ID of the broadcaster that is streaming live and has installed or activated the extension." }, "broadcaster_name": { "type": "string", "description": "The broadcaster’s display name." }, "game_name": { "type": "string", "description": "The name of the category or game being streamed." }, "game_id": { "type": "string", "description": "The ID of the category or game being streamed." }, "title": { "type": "string", "description": "The title of the broadcaster’s stream. May be an empty string if not specified." } } }, "GetExtensionLiveChannelsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "The list of broadcasters that are streaming live and that have installed or activated the extension.", "items": { "$ref": "#/components/schemas/ExtensionLiveChannel" } }, "pagination": { "type": "string", "description": "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](https://dev.twitch.tv/docs/api/guide#pagination)" } } }, "ExtensionSecret": { "type": "object", "required": [ "format_version", "secrets" ], "properties": { "format_version": { "type": "integer", "description": "The version number that identifies this definition of the secret’s data.", "format": "int32" }, "secrets": { "type": "array", "description": "The list of secrets.", "items": { "type": "object", "required": [ "content", "active_at", "expires_at" ], "properties": { "content": { "type": "string", "description": "The raw secret that you use with JWT encoding." }, "active_at": { "type": "string", "description": "The UTC date and time (in RFC3339 format) that you may begin using this secret to sign a JWT.", "format": "date-time" }, "expires_at": { "type": "string", "description": "The UTC date and time (in RFC3339 format) that you must stop using this secret to decode a JWT.", "format": "date-time" } } } } } }, "GetExtensionSecretsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "The list of shared secrets that the extension created.", "items": { "$ref": "#/components/schemas/ExtensionSecret" } } } }, "CreateExtensionSecretResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "A list that contains the newly added secrets.", "items": { "$ref": "#/components/schemas/ExtensionSecret" } } } }, "SendExtensionChatMessageBody": { "type": "object", "required": [ "text", "extension_id", "extension_version" ], "properties": { "text": { "type": "string", "description": "The message. The message may contain a maximum of 280 characters." }, "extension_id": { "type": "string", "description": "The ID of the extension that’s sending the chat message." }, "extension_version": { "type": "string", "description": "The extension’s version number." } } }, "ExtensionIconUrls": { "type": "object", "description": "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.", "properties": { "100x100": { "type": "string" }, "24x24": { "type": "string" }, "300x200": { "type": "string" } } }, "Extension": { "type": "object", "required": [ "author_name", "bits_enabled", "can_install", "configuration_location", "description", "eula_tos_url", "has_chat_support", "icon_url", "icon_urls", "id", "name", "privacy_policy_url", "request_identity_link", "screenshot_urls", "state", "subscriptions_support_level", "summary", "support_email", "version", "viewer_summary", "views", "allowlisted_config_urls", "allowlisted_panel_urls" ], "properties": { "author_name": { "type": "string", "description": "The name of the user or organization that owns the extension." }, "bits_enabled": { "type": "boolean", "description": "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": { "type": "boolean", "description": "A Boolean value that determines whether a user can install the extension on their channel. Is **true** if a user can install the extension. \n \nTypically, 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](https://dev.twitch.tv/console/extensions) under the **Extensions** \\-> **Extension** \\-> **Version** \\-> **Access**)." }, "configuration_location": { "type": "string", "description": "The location of where the extension’s configuration is stored. Possible values are: \n \n* hosted — The Extensions Configuration Service hosts the configuration.\n* custom — The Extension Backend Service (EBS) hosts the configuration.\n* none — The extension doesn't require configuration.", "enum": [ "hosted", "custom", "none" ] }, "description": { "type": "string", "description": "A longer description of the extension. It appears on the details page." }, "eula_tos_url": { "type": "string", "description": "A URL to the extension’s Terms of Service." }, "has_chat_support": { "type": "boolean", "description": "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": { "type": "string", "description": "A URL to the default icon that’s displayed in the Extensions directory." }, "icon_urls": { "$ref": "#/components/schemas/ExtensionIconUrls" }, "id": { "type": "string", "description": "The extension’s ID." }, "name": { "type": "string", "description": "The extension’s name." }, "privacy_policy_url": { "type": "string", "description": "A URL to the extension’s privacy policy." }, "request_identity_link": { "type": "boolean", "description": "A Boolean value that determines whether the extension wants to explicitly ask viewers to link their Twitch identity." }, "screenshot_urls": { "type": "array", "description": "A list of URLs to screenshots that are shown in the Extensions marketplace.", "items": { "type": "string" } }, "state": { "type": "string", "description": "The extension’s state. Possible values are: \n \n* Approved\n* AssetsUploaded\n* Deleted\n* Deprecated\n* InReview\n* InTest\n* PendingAction\n* Rejected\n* Released", "enum": [ "Approved", "AssetsUploaded", "Deleted", "Deprecated", "InReview", "InTest", "PendingAction", "Rejected", "Released" ] }, "subscriptions_support_level": { "type": "string", "description": "Indicates whether the extension can view the user’s subscription level on the channel that the extension is installed on. Possible values are: \n \n* none — The extension can't view the user’s subscription level.\n* optional — The extension can view the user’s subscription level.", "enum": [ "none", "optional" ] }, "summary": { "type": "string", "description": "A short description of the extension that streamers see when hovering over the discovery splash screen in the Extensions manager." }, "support_email": { "type": "string", "description": "The email address that users use to get support for the extension." }, "version": { "type": "string", "description": "The extension’s version number." }, "viewer_summary": { "type": "string", "description": "A brief description displayed on the channel to explain how the extension works." }, "views": { "description": "Describes all views-related information such as how the extension is displayed on mobile devices.", "type": "object", "required": [ "mobile", "panel", "video_overlay", "component", "config" ], "properties": { "mobile": { "description": "Describes how the extension is displayed on mobile devices.", "type": "object", "required": [ "viewer_url" ], "properties": { "viewer_url": { "type": "string", "description": "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": { "description": "Describes how the extension is rendered if the extension may be activated as a panel extension.", "type": "object", "required": [ "viewer_url", "height", "can_link_external_content" ], "properties": { "viewer_url": { "type": "string", "description": "The HTML file that is shown to viewers on the channel page when the extension is activated in a Panel slot." }, "height": { "type": "integer", "description": "The height, in pixels, of the panel component that the extension is rendered in.", "format": "int32" }, "can_link_external_content": { "type": "boolean", "description": "A Boolean value that determines whether the extension can link to non-Twitch domains." } } }, "video_overlay": { "description": "Describes how the extension is rendered if the extension may be activated as a video-overlay extension.", "type": "object", "required": [ "viewer_url", "can_link_external_content" ], "properties": { "viewer_url": { "type": "string", "description": "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": { "type": "boolean", "description": "A Boolean value that determines whether the extension can link to non-Twitch domains." } } }, "component": { "description": "Describes how the extension is rendered if the extension may be activated as a video-component extension.", "type": "object", "required": [ "viewer_url", "aspect_ratio_x", "aspect_ratio_y", "autoscale", "scale_pixels", "target_height", "can_link_external_content" ], "properties": { "viewer_url": { "type": "string", "description": "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": { "type": "integer", "description": "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.", "format": "int32" }, "aspect_ratio_y": { "type": "integer", "description": "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.", "format": "int32" }, "autoscale": { "type": "boolean", "description": "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": { "type": "integer", "description": "The base width, in pixels, of the extension to use when scaling (see `autoscale`). This value is ignored if `autoscale` is **false**.", "format": "int32" }, "target_height": { "type": "integer", "description": "The height as a percent of the maximum height of a video component extension. Values are between 1% - 100%.", "format": "int32" }, "can_link_external_content": { "type": "boolean", "description": "A Boolean value that determines whether the extension can link to non-Twitch domains." } } }, "config": { "description": "Describes the view that is shown to broadcasters while they are configuring your extension within the Extension Manager.", "type": "object", "required": [ "viewer_url", "can_link_external_content" ], "properties": { "viewer_url": { "type": "string", "description": "The HTML file shown to broadcasters while they are configuring your extension within the Extension Manager." }, "can_link_external_content": { "type": "boolean", "description": "A Boolean value that determines whether the extension can link to non-Twitch domains." } } } } }, "allowlisted_config_urls": { "type": "array", "description": "Allowlisted configuration URLs for displaying the extension (the allowlist is configured on Twitch’s [developer site](https://dev.twitch.tv/console/extensions) under the **Extensions** \\-> **Extension** \\-> **Version** \\-> **Capabilities**).", "items": { "type": "string" } }, "allowlisted_panel_urls": { "type": "array", "description": "Allowlisted panel URLs for displaying the extension (the allowlist is configured on Twitch’s [developer site](https://dev.twitch.tv/console/extensions) under the **Extensions** \\-> **Extension** \\-> **Version** \\-> **Capabilities**).", "items": { "type": "string" } } } }, "GetExtensionsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "A list that contains the specified extension.", "items": { "$ref": "#/components/schemas/Extension" } } } }, "GetReleasedExtensionsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "A list that contains the specified extension.", "items": { "$ref": "#/components/schemas/Extension" } } } }, "ExtensionBitsProduct": { "type": "object", "required": [ "sku", "cost", "in_development", "display_name", "expiration", "is_broadcast" ], "properties": { "sku": { "type": "string", "description": "The product's SKU. The SKU is unique across an extension's products." }, "cost": { "description": "An object that contains the product's cost information.", "type": "object", "required": [ "amount", "type" ], "properties": { "amount": { "type": "integer", "description": "The product's price.", "format": "int32" }, "type": { "type": "string", "description": "The type of currency. Possible values are: \n \n* bits", "enum": [ "bits" ] } } }, "in_development": { "type": "boolean", "description": "A Boolean value that indicates whether the product is in development. If **true**, the product is not available for public use." }, "display_name": { "type": "string", "description": "The product's name as displayed in the extension." }, "expiration": { "type": "string", "description": "The date and time, in RFC3339 format, when the product expires.", "format": "date-time" }, "is_broadcast": { "type": "boolean", "description": "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." } } }, "GetExtensionBitsProductsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "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.", "items": { "$ref": "#/components/schemas/ExtensionBitsProduct" } } } }, "UpdateExtensionBitsProductBody": { "type": "object", "required": [ "sku", "cost", "display_name" ], "properties": { "sku": { "type": "string", "description": "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": { "description": "An object that contains the product's cost information.", "type": "object", "required": [ "amount", "type" ], "properties": { "amount": { "type": "integer", "description": "The product's price.", "format": "int32" }, "type": { "type": "string", "description": "The type of currency. Possible values are: \n \n* bits — The minimum price is 1 and the maximum is 10000.", "enum": [ "bits" ] } } }, "display_name": { "type": "string", "description": "The product's name as displayed in the extension. The maximum length is 255 characters." }, "in_development": { "type": "boolean", "description": "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": { "type": "string", "description": "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.", "format": "date-time" }, "is_broadcast": { "type": "boolean", "description": "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**." } } }, "UpdateExtensionBitsProductResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "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.", "items": { "$ref": "#/components/schemas/ExtensionBitsProduct" } } } }, "CreateEventSubSubscriptionBody": { "type": "object", "required": [ "type", "version", "condition", "transport" ], "properties": { "type": { "type": "string", "description": "The type of subscription to create. For a list of subscriptions that you can create, see [Subscription Types](https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#subscription-types). Set this field to the value in the **Name** column of the Subscription Types table.", "enum": [ "automod.message.hold", "automod.message.update", "automod.settings.update", "automod.terms.update", "channel.bits.use", "channel.update", "channel.follow", "channel.ad_break.begin", "channel.chat.clear", "channel.chat.clear_user_messages", "channel.chat.message", "channel.chat.message_delete", "channel.chat.notification", "channel.chat_settings.update", "channel.chat.user_message_hold", "channel.chat.user_message_update", "channel.shared_chat.begin", "channel.shared_chat.update", "channel.shared_chat.end", "channel.subscribe", "channel.subscription.end", "channel.subscription.gift", "channel.subscription.message", "channel.cheer", "channel.raid", "channel.ban", "channel.unban", "channel.unban_request.create", "channel.unban_request.resolve", "channel.moderate", "channel.moderator.add", "channel.moderator.remove", "channel.guest_star_session.begin", "channel.guest_star_session.end", "channel.guest_star_guest.update", "channel.guest_star_settings.update", "channel.channel_points_automatic_reward_redemption.add", "channel.channel_points_custom_reward.add", "channel.channel_points_custom_reward.update", "channel.channel_points_custom_reward.remove", "channel.channel_points_custom_reward_redemption.add", "channel.channel_points_custom_reward_redemption.update", "channel.poll.begin", "channel.poll.progress", "channel.poll.end", "channel.prediction.begin", "channel.prediction.progress", "channel.prediction.lock", "channel.prediction.end", "channel.suspicious_user.message", "channel.suspicious_user.update", "channel.vip.add", "channel.vip.remove", "channel.warning.acknowledge", "channel.warning.send", "channel.charity_campaign.donate", "channel.charity_campaign.start", "channel.charity_campaign.progress", "channel.charity_campaign.stop", "conduit.shard.disabled", "drop.entitlement.grant", "extension.bits_transaction.create", "channel.goal.begin", "channel.goal.progress", "channel.goal.end", "channel.hype_train.begin", "channel.hype_train.progress", "channel.hype_train.end", "channel.shield_mode.begin", "channel.shield_mode.end", "channel.shoutout.create", "channel.shoutout.receive", "stream.online", "stream.offline", "user.authorization.grant", "user.authorization.revoke", "user.update", "user.whisper.message" ] }, "version": { "type": "string", "description": "The version number that identifies the definition of the subscription type that you want the response to use." }, "condition": { "type": "object", "description": "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": { "description": "The transport details that you want Twitch to use when sending you notifications.", "type": "object", "required": [ "method" ], "properties": { "method": { "type": "string", "description": "The transport method. Possible values are: \n \n* webhook\n* websocket\n* conduit", "enum": [ "webhook", "websocket", "conduit" ] }, "callback": { "type": "string", "description": "The callback URL where the notifications are sent. The URL must use the HTTPS protocol and port 443\\. See [Processing an event](https://dev.twitch.tv/docs/eventsub/handling-webhook-events#processing-an-event). Specify this field only if `method` is set to **webhook**.\n\n**NOTE**: Redirects are not followed." }, "secret": { "type": "string", "description": "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](https://dev.twitch.tv/docs/eventsub/handling-webhook-events#verifying-the-event-message). Specify this field only if `method` is set to **webhook**." }, "session_id": { "type": "string", "description": "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**." }, "conduit_id": { "type": "string", "description": "An ID that identifies the conduit to send notifications to. When you create a conduit, the server returns the conduit ID. Specify this field only if `method` is set to **conduit**." } } } } }, "EventSubSubscription": { "type": "object", "required": [ "id", "status", "type", "version", "condition", "created_at", "transport", "cost" ], "properties": { "id": { "type": "string", "description": "An ID that identifies the subscription." }, "status": { "type": "string", "description": "The subscription's status. The subscriber receives events only for **enabled** subscriptions. Possible values are: \n \n* enabled — The subscription is enabled.\n* webhook\\_callback\\_verification\\_pending — The subscription is pending verification of the specified callback URL.\n* webhook\\_callback\\_verification\\_failed — The specified callback URL failed verification.\n* notification\\_failures\\_exceeded — The notification delivery failure rate was too high.\n* authorization\\_revoked — The authorization was revoked for one or more users specified in the **Condition** object.\n* moderator\\_removed — The moderator that authorized the subscription is no longer one of the broadcaster's moderators.\n* user\\_removed — One of the users specified in the **Condition** object was removed.\n* version\\_removed — The subscription to subscription type and version is no longer supported.\n* beta\\_maintenance — The subscription to the beta subscription type was removed due to maintenance.\n* websocket\\_disconnected — The client closed the connection.\n* websocket\\_failed\\_ping\\_pong — The client failed to respond to a ping message.\n* websocket\\_received\\_inbound\\_traffic — The client sent a non-pong message. Clients may only send pong messages (and only in response to a ping message).\n* websocket\\_connection\\_unused — The client failed to subscribe to events within the required time.\n* websocket\\_internal\\_error — The Twitch WebSocket server experienced an unexpected error.\n* websocket\\_network\\_timeout — The Twitch WebSocket server timed out writing the message to the client.\n* websocket\\_network\\_error — The Twitch WebSocket server experienced a network error writing the message to the client.", "enum": [ "enabled", "webhook_callback_verification_pending", "webhook_callback_verification_failed", "notification_failures_exceeded", "authorization_revoked", "moderator_removed", "user_removed", "version_removed", "beta_maintenance", "websocket_disconnected", "websocket_failed_ping_pong", "websocket_received_inbound_traffic", "websocket_connection_unused", "websocket_internal_error", "websocket_network_timeout", "websocket_network_error" ] }, "type": { "type": "string", "description": "The subscription's type. See [Subscription Types](https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#subscription-types).", "enum": [ "automod.message.hold", "automod.message.update", "automod.settings.update", "automod.terms.update", "channel.bits.use", "channel.update", "channel.follow", "channel.ad_break.begin", "channel.chat.clear", "channel.chat.clear_user_messages", "channel.chat.message", "channel.chat.message_delete", "channel.chat.notification", "channel.chat_settings.update", "channel.chat.user_message_hold", "channel.chat.user_message_update", "channel.shared_chat.begin", "channel.shared_chat.update", "channel.shared_chat.end", "channel.subscribe", "channel.subscription.end", "channel.subscription.gift", "channel.subscription.message", "channel.cheer", "channel.raid", "channel.ban", "channel.unban", "channel.unban_request.create", "channel.unban_request.resolve", "channel.moderate", "channel.moderator.add", "channel.moderator.remove", "channel.guest_star_session.begin", "channel.guest_star_session.end", "channel.guest_star_guest.update", "channel.guest_star_settings.update", "channel.channel_points_automatic_reward_redemption.add", "channel.channel_points_custom_reward.add", "channel.channel_points_custom_reward.update", "channel.channel_points_custom_reward.remove", "channel.channel_points_custom_reward_redemption.add", "channel.channel_points_custom_reward_redemption.update", "channel.poll.begin", "channel.poll.progress", "channel.poll.end", "channel.prediction.begin", "channel.prediction.progress", "channel.prediction.lock", "channel.prediction.end", "channel.suspicious_user.message", "channel.suspicious_user.update", "channel.vip.add", "channel.vip.remove", "channel.warning.acknowledge", "channel.warning.send", "channel.charity_campaign.donate", "channel.charity_campaign.start", "channel.charity_campaign.progress", "channel.charity_campaign.stop", "conduit.shard.disabled", "drop.entitlement.grant", "extension.bits_transaction.create", "channel.goal.begin", "channel.goal.progress", "channel.goal.end", "channel.hype_train.begin", "channel.hype_train.progress", "channel.hype_train.end", "channel.shield_mode.begin", "channel.shield_mode.end", "channel.shoutout.create", "channel.shoutout.receive", "stream.online", "stream.offline", "user.authorization.grant", "user.authorization.revoke", "user.update", "user.whisper.message" ] }, "version": { "type": "string", "description": "The version number that identifies this definition of the subscription's data." }, "condition": { "type": "object", "description": "The subscription's parameter values. This is a string-encoded JSON object whose contents are determined by the subscription type." }, "created_at": { "type": "string", "description": "The date and time (in RFC3339 format) of when the subscription was created.", "format": "date-time" }, "transport": { "description": "The transport details used to send the notifications.", "type": "object", "required": [ "method" ], "properties": { "method": { "type": "string", "description": "The transport method. Possible values are: \n \n* webhook\n* websocket", "enum": [ "webhook", "websocket" ] }, "callback": { "type": "string", "description": "The callback URL where the notifications are sent. Included only if `method` is set to **webhook**." }, "session_id": { "type": "string", "description": "An ID that identifies the WebSocket that notifications are sent to. Included only if `method` is set to **websocket**." }, "connected_at": { "type": "string", "description": "The UTC date and time that the WebSocket connection was established. Included only if `method` is set to **websocket**.", "format": "date-time" }, "disconnected_at": { "type": "string", "description": "The UTC date and time that the WebSocket connection was lost. Included only if `method` is set to **websocket**.", "format": "date-time" } } }, "cost": { "type": "integer", "description": "The amount that the subscription counts against your limit. [Learn More](https://dev.twitch.tv/docs/eventsub/manage-subscriptions/#subscription-limits)", "format": "int32" } } }, "CreateEventSubSubscriptionResponse": { "type": "object", "required": [ "data", "total", "total_cost", "max_total_cost" ], "properties": { "data": { "type": "array", "description": "A list that contains the single subscription that you created.", "items": { "$ref": "#/components/schemas/EventSubSubscription" } }, "total": { "type": "integer", "description": "The total number of subscriptions you’ve created.", "format": "int32" }, "total_cost": { "type": "integer", "description": "The sum of all of your subscription costs. [Learn More](https://dev.twitch.tv/docs/eventsub/manage-subscriptions/#subscription-limits)", "format": "int32" }, "max_total_cost": { "type": "integer", "description": "The maximum total cost that you’re allowed to incur for all subscriptions you create.", "format": "int32" } } }, "GetEventSubSubscriptionsResponse": { "type": "object", "required": [ "data", "total", "total_cost", "max_total_cost" ], "properties": { "data": { "type": "array", "description": "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.", "items": { "$ref": "#/components/schemas/EventSubSubscription" } }, "total": { "type": "integer", "description": "The total number of subscriptions that you've created.", "format": "int32" }, "total_cost": { "type": "integer", "description": "The sum of all of your subscription costs. [Learn More](https://dev.twitch.tv/docs/eventsub/manage-subscriptions/#subscription-limits)", "format": "int32" }, "max_total_cost": { "type": "integer", "description": "The maximum total cost that you're allowed to incur for all subscriptions that you create.", "format": "int32" }, "pagination": { "description": "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.", "type": "object", "properties": { "cursor": { "type": "string", "description": "The cursor value that you set the _after_ query parameter to." } } } } }, "Game": { "type": "object", "required": [ "id", "name", "box_art_url", "igdb_id" ], "properties": { "id": { "type": "string", "description": "An ID that identifies the category or game." }, "name": { "type": "string", "description": "The category’s or game’s name." }, "box_art_url": { "type": "string", "description": "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": { "type": "string", "description": "The ID that [IGDB](https://www.igdb.com/) uses to identify this game. If the IGDB ID is not available to Twitch, this field is set to an empty string." } } }, "GetTopGamesResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "The list of broadcasts. The broadcasts are sorted by the number of viewers, with the most popular first.", "items": { "$ref": "#/components/schemas/Game" } }, "pagination": { "description": "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](https://dev.twitch.tv/docs/api/guide#pagination)", "type": "object", "properties": { "cursor": { "type": "string", "description": "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." } } } } }, "GetGamesResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "The list of categories and games. The list is empty if the specified categories and games weren’t found.", "items": { "$ref": "#/components/schemas/Game" } } } }, "CreatorGoal": { "type": "object", "required": [ "id", "broadcaster_id", "broadcaster_name", "broadcaster_login", "type", "description", "current_amount", "target_amount", "created_at" ], "properties": { "id": { "type": "string", "description": "An ID that identifies this goal." }, "broadcaster_id": { "type": "string", "description": "An ID that identifies the broadcaster that created the goal." }, "broadcaster_name": { "type": "string", "description": "The broadcaster’s display name." }, "broadcaster_login": { "type": "string", "description": "The broadcaster’s login name." }, "type": { "type": "string", "description": "The type of goal. Possible values are: \n \n* follower — The goal is to increase followers.\n* subscription — The goal is to increase subscriptions. This type shows the net increase or decrease in tier points associated with the subscriptions.\n* subscription\\_count — The goal is to increase subscriptions. This type shows the net increase or decrease in the number of subscriptions.\n* 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).\n* 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).", "enum": [ "follower", "subscription", "subscription_count", "new_subscription", "new_subscription_count" ] }, "description": { "type": "string", "description": "A description of the goal. Is an empty string if not specified." }, "current_amount": { "type": "integer", "description": "The goal’s current value. \n \nThe goal’s `type` determines how this value is increased or decreased. \n \n* 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.\n* 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.\n* If `type` is subscription\\_count, this field is increased by 1 for each new subscription and decreased by 1 for each user that unsubscribes.\n* 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.\n* If `type` is new\\_subscription\\_count, this field is increased by 1 for each new subscription.", "format": "int32" }, "target_amount": { "type": "integer", "description": "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.", "format": "int32" }, "created_at": { "type": "string", "description": "The UTC date and time (in RFC3339 format) that the broadcaster created the goal.", "format": "date-time" } } }, "GetCreatorGoalsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "The list of goals. The list is empty if the broadcaster hasn’t created goals.", "items": { "$ref": "#/components/schemas/CreatorGoal" } } } }, "GetChannelGuestStarSettingsResponse": { "type": "object", "required": [ "is_moderator_send_live_enabled", "slot_count", "is_browser_source_audio_enabled", "group_layout", "browser_source_token" ], "properties": { "is_moderator_send_live_enabled": { "type": "boolean", "description": "Flag determining if Guest Star moderators have access to control whether a guest is live once assigned to a slot." }, "slot_count": { "type": "integer", "description": "Number of slots the Guest Star call interface will allow the host to add to a call. Required to be between 1 and 6.", "format": "int32" }, "is_browser_source_audio_enabled": { "type": "boolean", "description": "Flag determining if Browser Sources subscribed to sessions on this channel should output audio" }, "group_layout": { "type": "string", "description": "This setting determines how the guests within a session should be laid out within the browser source. Can be one of the following values: \n \n* `TILED_LAYOUT`: All live guests are tiled within the browser source with the same size.\n* `SCREENSHARE_LAYOUT`: All live guests are tiled within the browser source with the same size. If there is an active screen share, it is sized larger than the other guests.", "enum": [ "TILED_LAYOUT", "SCREENSHARE_LAYOUT" ] }, "browser_source_token": { "type": "string", "description": "View only token to generate browser source URLs" } } }, "UpdateChannelGuestStarSettingsBody": { "type": "object", "properties": { "is_moderator_send_live_enabled": { "type": "boolean", "description": "Flag determining if Guest Star moderators have access to control whether a guest is live once assigned to a slot." }, "slot_count": { "type": "integer", "description": "Number of slots the Guest Star call interface will allow the host to add to a call. Required to be between 1 and 6.", "format": "int32" }, "is_browser_source_audio_enabled": { "type": "boolean", "description": "Flag determining if Browser Sources subscribed to sessions on this channel should output audio" }, "group_layout": { "type": "string", "description": "This setting determines how the guests within a session should be laid out within the browser source. Can be one of the following values: \n \n* `TILED_LAYOUT`: All live guests are tiled within the browser source with the same size.\n* `SCREENSHARE_LAYOUT`: All live guests are tiled within the browser source with the same size. If there is an active screen share, it is sized larger than the other guests.\n* `HORIZONTAL_LAYOUT`: All live guests are arranged in a horizontal bar within the browser source\n* `VERTICAL_LAYOUT`: All live guests are arranged in a vertical bar within the browser source", "enum": [ "TILED_LAYOUT", "SCREENSHARE_LAYOUT", "HORIZONTAL_LAYOUT", "VERTICAL_LAYOUT" ] }, "regenerate_browser_sources": { "type": "boolean", "description": "Flag determining if Guest Star should regenerate the auth token associated with the channel’s browser sources. Providing a true value for this will immediately invalidate all browser sources previously configured in your streaming software." } } }, "Guest": { "type": "object", "required": [ "slot_id", "is_live", "user_id", "user_display_name", "user_login", "volume", "assigned_at", "audio_settings", "video_settings" ], "properties": { "slot_id": { "type": "string", "description": "ID representing this guest’s slot assignment. \n \n* Host is always in slot \"0\"\n* Guests are assigned the following consecutive IDs (e.g, \"1\", \"2\", \"3\", etc)\n* Screen Share is represented as a special guest with the ID \"SCREENSHARE\"\n* The identifier here matches the ID referenced in browser source links used in broadcasting software." }, "is_live": { "type": "boolean", "description": "Flag determining whether or not the guest is visible in the browser source in the host’s streaming software." }, "user_id": { "type": "string", "description": "User ID of the guest assigned to this slot." }, "user_display_name": { "type": "string", "description": "Display name of the guest assigned to this slot." }, "user_login": { "type": "string", "description": "Login of the guest assigned to this slot." }, "volume": { "type": "integer", "description": "Value from 0 to 100 representing the host’s volume setting for this guest.", "format": "int32" }, "assigned_at": { "type": "string", "description": "Timestamp when this guest was assigned a slot in the session.", "format": "date-time" }, "audio_settings": { "description": "Information about the guest’s audio settings", "type": "object", "required": [ "is_host_enabled", "is_guest_enabled", "is_available" ], "properties": { "is_host_enabled": { "type": "boolean", "description": "Flag determining whether the host is allowing the guest’s audio to be seen or heard within the session." }, "is_guest_enabled": { "type": "boolean", "description": "Flag determining whether the guest is allowing their audio to be transmitted to the session." }, "is_available": { "type": "boolean", "description": "Flag determining whether the guest has an appropriate audio device available to be transmitted to the session." } } }, "video_settings": { "description": "Information about the guest’s video settings", "type": "object", "required": [ "is_host_enabled", "is_guest_enabled", "is_available" ], "properties": { "is_host_enabled": { "type": "boolean", "description": "Flag determining whether the host is allowing the guest’s video to be seen or heard within the session." }, "is_guest_enabled": { "type": "boolean", "description": "Flag determining whether the guest is allowing their video to be transmitted to the session." }, "is_available": { "type": "boolean", "description": "Flag determining whether the guest has an appropriate video device available to be transmitted to the session." } } } } }, "GuestStarSession": { "type": "object", "required": [ "id", "guests" ], "properties": { "id": { "type": "string", "description": "ID uniquely representing the Guest Star session." }, "guests": { "type": "array", "description": "List of guests currently interacting with the Guest Star session.", "items": { "$ref": "#/components/schemas/Guest" } } } }, "GetGuestStarSessionResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "Summary of the session details", "items": { "$ref": "#/components/schemas/GuestStarSession" } } } }, "CreateGuestStarSessionResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "Summary of the session details.", "items": { "$ref": "#/components/schemas/GuestStarSession" } } } }, "EndGuestStarSessionResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "Summary of the session details when the session was ended.", "items": { "$ref": "#/components/schemas/GuestStarSession" } } } }, "GuestStarInvite": { "type": "object", "required": [ "user_id", "invited_at", "status", "is_video_enabled", "is_audio_enabled", "is_video_available", "is_audio_available" ], "properties": { "user_id": { "type": "string", "description": "Twitch User ID corresponding to the invited guest" }, "invited_at": { "type": "string", "description": "Timestamp when this user was invited to the session.", "format": "date-time" }, "status": { "type": "string", "description": "Status representing the invited user’s join state. Can be one of the following: \n \n* `INVITED`: The user has been invited to the session but has not acknowledged it.\n* `ACCEPTED`: The invited user has acknowledged the invite and joined the waiting room, but may still be setting up their media devices or otherwise preparing to join the call.\n* `READY`: The invited user has signaled they are ready to join the call from the waiting room." }, "is_video_enabled": { "type": "boolean", "description": "Flag signaling that the invited user has chosen to disable their local video device. The user has hidden themselves, but they may choose to reveal their video feed upon joining the session." }, "is_audio_enabled": { "type": "boolean", "description": "Flag signaling that the invited user has chosen to disable their local audio device. The user has muted themselves, but they may choose to unmute their audio feed upon joining the session." }, "is_video_available": { "type": "boolean", "description": "Flag signaling that the invited user has a video device available for sharing." }, "is_audio_available": { "type": "boolean", "description": "Flag signaling that the invited user has an audio device available for sharing." } } }, "GetGuestStarInvitesResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "A list of invite objects describing the invited user as well as their ready status.", "items": { "$ref": "#/components/schemas/GuestStarInvite" } } } }, "GetHypeTrainStatusResponse": { "type": "object", "required": [ "data", "all_time_high", "shared_all_time_high" ], "properties": { "data": { "type": "array", "description": "A list that contains information related to the channel’s Hype Train.", "items": { "type": "object", "required": [ "current" ], "properties": { "current": { "description": "An object describing the current Hype Train. Null if a Hype Train is not active.", "type": "object", "required": [ "id", "broadcaster_user_id", "broadcaster_user_login", "broadcaster_user_name", "level", "total", "progress", "goal", "top_contributions" ], "properties": { "id": { "type": "string", "description": "The Hype Train ID." }, "broadcaster_user_id": { "type": "string", "description": "The broadcaster ID." }, "broadcaster_user_login": { "type": "string", "description": "The broadcaster login." }, "broadcaster_user_name": { "type": "string", "description": "The broadcaster display name." }, "level": { "type": "integer", "description": "The current level of the Hype Train.", "format": "int32" }, "total": { "type": "integer", "description": "Total points contributed to the Hype Train.", "format": "int32" }, "progress": { "type": "integer", "description": "The number of points contributed to the Hype Train at the current level.", "format": "int32" }, "goal": { "type": "integer", "description": "The number of points required to reach the next level.", "format": "int32" }, "top_contributions": { "type": "array", "description": "The contributors with the most points contributed.", "items": { "type": "object", "required": [ "user_id", "user_login", "user_name", "type", "total", "shared_train_participants", "started_at", "expires_at", "type", "is_shared_train" ], "properties": { "user_id": { "type": "string", "description": "The ID of the user that made the contribution." }, "user_login": { "type": "string", "description": "The user’s login name." }, "user_name": { "type": "string", "description": "The user’s display name." }, "type": { "type": "string", "description": "The type of the Hype Train. Possible values are: \n \n* **treasure**\n* **golden\\_kappa**\n* **regular**\n \n[Learn More](https://help.twitch.tv/s/article/hype-train-guide#special)", "enum": [ "treasure", "golden_kappa", "regular" ] }, "total": { "type": "integer", "description": "The total number of points contributed for the type.", "format": "int32" }, "shared_train_participants": { "type": "array", "description": "A list containing the broadcasters participating in the shared Hype Train. Null if the Hype Train is not shared.", "items": { "type": "object", "required": [ "broadcaster_user_id", "broadcaster_user_login", "broadcaster_user_name" ], "properties": { "broadcaster_user_id": { "type": "string", "description": "The broadcaster ID." }, "broadcaster_user_login": { "type": "string", "description": "The broadcaster login." }, "broadcaster_user_name": { "type": "string", "description": "The broadcaster display name." } } } }, "started_at": { "type": "string", "description": "The time when the Hype Train started.", "format": "date-time" }, "expires_at": { "type": "string", "description": "The time when the Hype Train expires. The expiration is extended when the Hype Train reaches a new level.", "format": "date-time" }, "is_shared_train": { "type": "boolean", "description": "Indicates if the Hype Train is shared. When true, shared\\_train\\_participants will contain the list of broadcasters the train is shared with." } } } } } } } } }, "all_time_high": { "description": "An object with information about the channel’s Hype Train records. Null if a Hype Train has not occurred.", "type": "object", "required": [ "level", "total", "achieved_at" ], "properties": { "level": { "type": "integer", "description": "The level of the record Hype Train.", "format": "int32" }, "total": { "type": "integer", "description": "Total points contributed to the record Hype Train.", "format": "int32" }, "achieved_at": { "type": "string", "description": "The time when the record was achieved.", "format": "date-time" } } }, "shared_all_time_high": { "description": "An object with information about the channel’s shared Hype Train records. Null if a Hype Train has not occurred.", "type": "object", "required": [ "level", "total", "achieved_at" ], "properties": { "level": { "type": "integer", "description": "The level of the record Hype Train.", "format": "int32" }, "total": { "type": "integer", "description": "Total points contributed to the record Hype Train.", "format": "int32" }, "achieved_at": { "type": "string", "description": "The time when the record was achieved.", "format": "date-time" } } } } }, "CheckAutoModStatusBody": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "The list of messages to check. The list must contain at least one message and may contain up to a maximum of 100 messages.", "items": { "type": "object", "required": [ "msg_id", "msg_text" ], "properties": { "msg_id": { "type": "string", "description": "A caller-defined ID used to correlate this message with the same message in the response." }, "msg_text": { "type": "string", "description": "The message to check." } } } } } }, "AutoModStatus": { "type": "object", "required": [ "msg_id", "is_permitted" ], "properties": { "msg_id": { "type": "string", "description": "The caller-defined ID passed in the request." }, "is_permitted": { "type": "boolean", "description": "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." } } }, "CheckAutoModStatusResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "The list of messages and whether Twitch would approve them for chat.", "items": { "$ref": "#/components/schemas/AutoModStatus" } } } }, "ManageHeldAutoModMessagesBody": { "type": "object", "required": [ "user_id", "msg_id", "action" ], "properties": { "user_id": { "type": "string", "description": "The moderator who is approving or denying the held message. This ID must match the user ID in the access token." }, "msg_id": { "type": "string", "description": "The ID of the message to allow or deny." }, "action": { "type": "string", "description": "The action to take for the message. Possible values are: \n \n* ALLOW\n* DENY", "enum": [ "ALLOW", "DENY" ] } } }, "AutoModSettings": { "type": "object", "required": [ "broadcaster_id", "moderator_id", "overall_level", "disability", "aggression", "sexuality_sex_or_gender", "misogyny", "bullying", "swearing", "race_ethnicity_or_religion", "sex_based_terms" ], "properties": { "broadcaster_id": { "type": "string", "description": "The broadcaster’s ID." }, "moderator_id": { "type": "string", "description": "The moderator’s ID." }, "overall_level": { "type": "integer", "description": "The default AutoMod level for the broadcaster. This field is **null** if the broadcaster has set one or more of the individual settings.", "format": "int32", "nullable": true }, "disability": { "type": "integer", "description": "The Automod level for discrimination against disability.", "format": "int32" }, "aggression": { "type": "integer", "description": "The Automod level for hostility involving aggression.", "format": "int32" }, "sexuality_sex_or_gender": { "type": "integer", "description": "The AutoMod level for discrimination based on sexuality, sex, or gender.", "format": "int32" }, "misogyny": { "type": "integer", "description": "The Automod level for discrimination against women.", "format": "int32" }, "bullying": { "type": "integer", "description": "The Automod level for hostility involving name calling or insults.", "format": "int32" }, "swearing": { "type": "integer", "description": "The Automod level for profanity.", "format": "int32" }, "race_ethnicity_or_religion": { "type": "integer", "description": "The Automod level for racial discrimination.", "format": "int32" }, "sex_based_terms": { "type": "integer", "description": "The Automod level for sexual content.", "format": "int32" } } }, "GetAutoModSettingsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "The list of AutoMod settings. The list contains a single object that contains all the AutoMod settings.", "items": { "$ref": "#/components/schemas/AutoModSettings" } } } }, "UpdateAutoModSettingsBody": { "type": "object", "properties": { "aggression": { "type": "integer", "description": "The Automod level for hostility involving aggression.", "format": "int32" }, "bullying": { "type": "integer", "description": "The Automod level for hostility involving name calling or insults.", "format": "int32" }, "disability": { "type": "integer", "description": "The Automod level for discrimination against disability.", "format": "int32" }, "misogyny": { "type": "integer", "description": "The Automod level for discrimination against women.", "format": "int32" }, "overall_level": { "type": "integer", "description": "The default AutoMod level for the broadcaster.", "format": "int32" }, "race_ethnicity_or_religion": { "type": "integer", "description": "The Automod level for racial discrimination.", "format": "int32" }, "sex_based_terms": { "type": "integer", "description": "The Automod level for sexual content.", "format": "int32" }, "sexuality_sex_or_gender": { "type": "integer", "description": "The AutoMod level for discrimination based on sexuality, sex, or gender.", "format": "int32" }, "swearing": { "type": "integer", "description": "The Automod level for profanity.", "format": "int32" } } }, "UpdateAutoModSettingsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "The list of AutoMod settings. The list contains a single object that contains all the AutoMod settings.", "items": { "$ref": "#/components/schemas/AutoModSettings" } } } }, "BannedUser": { "type": "object", "required": [ "user_id", "user_login", "user_name", "expires_at", "created_at", "reason", "moderator_id", "moderator_login", "moderator_name" ], "properties": { "user_id": { "type": "string", "description": "The ID of the banned user." }, "user_login": { "type": "string", "description": "The banned user’s login name." }, "user_name": { "type": "string", "description": "The banned user’s display name." }, "expires_at": { "type": "string", "description": "The UTC date and time (in RFC3339 format) of when the timeout expires, or an empty string if the user is permanently banned.", "format": "date-time" }, "created_at": { "type": "string", "description": "The UTC date and time (in RFC3339 format) of when the user was banned.", "format": "date-time" }, "reason": { "type": "string", "description": "The reason the user was banned or put in a timeout if the moderator provided one." }, "moderator_id": { "type": "string", "description": "The ID of the moderator that banned the user or put them in a timeout." }, "moderator_login": { "type": "string", "description": "The moderator’s login name." }, "moderator_name": { "type": "string", "description": "The moderator’s display name." } } }, "GetBannedUsersResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "The list of users that were banned or put in a timeout.", "items": { "$ref": "#/components/schemas/BannedUser" } }, "pagination": { "description": "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](https://dev.twitch.tv/docs/api/guide#pagination)", "type": "object", "properties": { "cursor": { "type": "string", "description": "The cursor used to get the next page of results. Use the cursor to set the request’s _after_ query parameter." } } } } }, "BanUserBody": { "type": "object", "required": [ "data" ], "properties": { "data": { "description": "Identifies the user and type of ban.", "type": "object", "required": [ "user_id" ], "properties": { "user_id": { "type": "string", "description": "The ID of the user to ban or put in a timeout." }, "duration": { "type": "integer", "description": "To ban a user indefinitely, don’t include this field. \n \nTo 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). \n \nTo end a user’s timeout early, set this field to 1, or use the [Unban user](https://dev.twitch.tv/docs/api/reference#unban-user) endpoint.", "format": "int32" }, "reason": { "type": "string", "description": "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." } } } } }, "BanUserResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "A list that contains the user you successfully banned or put in a timeout.", "items": { "type": "object", "required": [ "broadcaster_id", "moderator_id", "user_id", "created_at", "end_time" ], "properties": { "broadcaster_id": { "type": "string", "description": "The broadcaster whose chat room the user was banned from chatting in." }, "moderator_id": { "type": "string", "description": "The moderator that banned or put the user in the timeout." }, "user_id": { "type": "string", "description": "The user that was banned or put in a timeout." }, "created_at": { "type": "string", "description": "The UTC date and time (in RFC3339 format) that the ban or timeout was placed.", "format": "date-time" }, "end_time": { "type": "string", "description": "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.", "format": "date-time", "nullable": true } } } } } }, "GetUnbanRequestsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "A list that contains information about the channel's unban requests.", "items": { "type": "object", "required": [ "id", "broadcaster_id", "broadcaster_name", "broadcaster_login", "moderator_id", "moderator_login", "moderator_name", "user_id", "user_login", "user_name", "text", "status", "created_at", "resolved_at", "resolution_text" ], "properties": { "id": { "type": "string", "description": "Unban request ID." }, "broadcaster_id": { "type": "string", "description": "User ID of broadcaster whose channel is receiving the unban request." }, "broadcaster_name": { "type": "string", "description": "The broadcaster's display name." }, "broadcaster_login": { "type": "string", "description": "The broadcaster's login name." }, "moderator_id": { "type": "string", "description": "User ID of moderator who approved/denied the request." }, "moderator_login": { "type": "string", "description": "The moderator's login name." }, "moderator_name": { "type": "string", "description": "The moderator's display name." }, "user_id": { "type": "string", "description": "User ID of the requestor who is asking for an unban." }, "user_login": { "type": "string", "description": "The user's login name." }, "user_name": { "type": "string", "description": "The user's display name." }, "text": { "type": "string", "description": "Text of the request from the requesting user." }, "status": { "type": "string", "description": "Status of the request. One of: \n \n* pending\n* approved\n* denied\n* acknowledged\n* canceled" }, "created_at": { "type": "string", "description": "Timestamp of when the unban request was created.", "format": "date-time" }, "resolved_at": { "type": "string", "description": "Timestamp of when moderator/broadcaster approved or denied the request.", "format": "date-time" }, "resolution_text": { "type": "string", "description": "Text input by the resolver (moderator) of the unban. request" } } } }, "pagination": { "description": "Contains information used to page through a list of results. The object is empty if there are no more pages left to page through.", "type": "object", "properties": { "cursor": { "type": "string", "description": "The cursor used to get the next page of results. Use the cursor to set the request’s after query parameter." } } } } }, "ResolveUnbanRequestsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "", "items": { "type": "object", "required": [ "id", "broadcaster_id", "broadcaster_login", "broadcaster_name", "moderator_id", "moderator_login", "moderator_name", "user_id", "user_login", "user_name", "text", "status", "created_at", "resolved_at", "resolution_text" ], "properties": { "id": { "type": "string", "description": "Unban request ID." }, "broadcaster_id": { "type": "string", "description": "User ID of broadcaster whose channel is receiving the unban request." }, "broadcaster_login": { "type": "string", "description": "The broadcaster’s login name." }, "broadcaster_name": { "type": "string", "description": "The broadcaster’s display name." }, "moderator_id": { "type": "string", "description": "User ID of moderator who approved/denied the request." }, "moderator_login": { "type": "string", "description": "The moderator’s login name." }, "moderator_name": { "type": "string", "description": "The moderator’s display name." }, "user_id": { "type": "string", "description": "User ID of the requestor who is asking for an unban." }, "user_login": { "type": "string", "description": "The user’s login name." }, "user_name": { "type": "string", "description": "The user’s display name." }, "text": { "type": "string", "description": "Text of the request from the requesting user." }, "status": { "type": "string", "description": "Status of the request. One of: \n \n* approved\n* denied" }, "created_at": { "type": "string", "description": "Timestamp of when the unban request was created.", "format": "date-time" }, "resolved_at": { "type": "string", "description": "Timestamp of when moderator/broadcaster approved or denied the request.", "format": "date-time" }, "resolution_text": { "type": "string", "description": "Text input by the resolver (moderator) of the unban request." } } } } } }, "BlockedTerm": { "type": "object", "required": [ "broadcaster_id", "moderator_id", "id", "text", "created_at", "updated_at", "expires_at" ], "properties": { "broadcaster_id": { "type": "string", "description": "The broadcaster that owns the list of blocked terms." }, "moderator_id": { "type": "string", "description": "The moderator that blocked the word or phrase from being used in the broadcaster’s chat room." }, "id": { "type": "string", "description": "An ID that identifies this blocked term." }, "text": { "type": "string", "description": "The blocked word or phrase." }, "created_at": { "type": "string", "description": "The UTC date and time (in RFC3339 format) that the term was blocked.", "format": "date-time" }, "updated_at": { "type": "string", "description": "The UTC date and time (in RFC3339 format) that the term was updated. \n \nWhen the term is added, this timestamp is the same as `created_at`. The timestamp changes as AutoMod continues to deny the term.", "format": "date-time" }, "expires_at": { "type": "string", "description": "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. \n \nThis field is **null** if the term was added manually or was permanently blocked by AutoMod.", "format": "date-time", "nullable": true } } }, "GetBlockedTermsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "The list of blocked terms. The list is in descending order of when they were created (see the `created_at` timestamp).", "items": { "$ref": "#/components/schemas/BlockedTerm" } }, "pagination": { "description": "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](https://dev.twitch.tv/docs/api/guide#pagination)", "type": "object", "properties": { "cursor": { "type": "string", "description": "The cursor used to get the next page of results. Use the cursor to set the request’s _after_ query parameter." } } } } }, "AddBlockedTermBody": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "description": "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. \n \nTerms 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\\*. \n \nIf the blocked term already exists, the response contains the existing blocked term." } } }, "AddBlockedTermResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "A list that contains the single blocked term that the broadcaster added.", "items": { "$ref": "#/components/schemas/BlockedTerm" } } } }, "GetModeratedChannelsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "The list of channels that the user has moderator privileges in.", "items": { "type": "object", "required": [ "broadcaster_id", "broadcaster_login", "broadcaster_name" ], "properties": { "broadcaster_id": { "type": "string", "description": "An ID that uniquely identifies the channel this user can moderate." }, "broadcaster_login": { "type": "string", "description": "The channel’s login name." }, "broadcaster_name": { "type": "string", "description": "The channels’ display name." } } } }, "pagination": { "description": "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.", "type": "object", "properties": { "cursor": { "type": "string", "description": "The cursor used to get the next page of results. Use the cursor to set the request’s after query parameter." } } } } }, "UserModerator": { "type": "object", "required": [ "user_id", "user_login", "user_name" ], "properties": { "user_id": { "type": "string", "description": "The ID of the user that has permission to moderate the broadcaster’s channel." }, "user_login": { "type": "string", "description": "The user’s login name." }, "user_name": { "type": "string", "description": "The user’s display name." } } }, "GetModeratorsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "The list of moderators.", "items": { "$ref": "#/components/schemas/UserModerator" } }, "pagination": { "description": "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](https://dev.twitch.tv/docs/api/guide#pagination)", "type": "object", "properties": { "cursor": { "type": "string", "description": "The cursor used to get the next page of results. Use the cursor to set the request’s _after_ query parameter." } } } } }, "UserVip": { "type": "object", "required": [ "user_id", "user_name", "user_login" ], "properties": { "user_id": { "type": "string", "description": "An ID that uniquely identifies the VIP user." }, "user_name": { "type": "string", "description": "The user’s display name." }, "user_login": { "type": "string", "description": "The user’s login name." } } }, "GetVIPsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "The list of VIPs. The list is empty if the broadcaster doesn’t have VIP users.", "items": { "$ref": "#/components/schemas/UserVip" } }, "pagination": { "description": "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](https://dev.twitch.tv/docs/api/guide#pagination)", "type": "object", "properties": { "cursor": { "type": "string", "description": "The cursor used to get the next page of results. Use the cursor to set the request’s _after_ query parameter." } } } } }, "UpdateShieldModeStatusBody": { "type": "object", "required": [ "is_active" ], "properties": { "is_active": { "type": "boolean", "description": "A Boolean value that determines whether to activate Shield Mode. Set to **true** to activate Shield Mode; otherwise, **false** to deactivate Shield Mode." } } }, "UpdateShieldModeStatusResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "A list that contains a single object with the broadcaster’s updated Shield Mode status.", "items": { "type": "object", "required": [ "is_active", "moderator_id", "moderator_login", "moderator_name", "last_activated_at" ], "properties": { "is_active": { "type": "boolean", "description": "A Boolean value that determines whether Shield Mode is active. Is **true** if Shield Mode is active; otherwise, **false**." }, "moderator_id": { "type": "string", "description": "An ID that identifies the moderator that last activated Shield Mode." }, "moderator_login": { "type": "string", "description": "The moderator’s login name." }, "moderator_name": { "type": "string", "description": "The moderator’s display name." }, "last_activated_at": { "type": "string", "description": "The UTC timestamp (in RFC3339 format) of when Shield Mode was last activated.", "format": "date-time" } } } } } }, "GetShieldModeStatusResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "A list that contains a single object with the broadcaster’s Shield Mode status.", "items": { "type": "object", "required": [ "is_active", "moderator_id", "moderator_login", "moderator_name", "last_activated_at" ], "properties": { "is_active": { "type": "boolean", "description": "A Boolean value that determines whether Shield Mode is active. Is **true** if the broadcaster activated Shield Mode; otherwise, **false**." }, "moderator_id": { "type": "string", "description": "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": { "type": "string", "description": "The moderator’s login name. Is an empty string if Shield Mode hasn’t been previously activated." }, "moderator_name": { "type": "string", "description": "The moderator’s display name. Is an empty string if Shield Mode hasn’t been previously activated." }, "last_activated_at": { "type": "string", "description": "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.", "format": "date-time" } } } } } }, "WarnChatUserBody": { "type": "object", "required": [ "data" ], "properties": { "data": { "description": "A list that contains information about the warning.", "type": "object", "required": [ "user_id", "reason" ], "properties": { "user_id": { "type": "string", "description": "The ID of the twitch user to be warned." }, "reason": { "type": "string", "description": "A custom reason for the warning. **Max 500 chars.**" } } } } }, "WarnChatUserResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "A list that contains information about the warning.", "items": { "type": "object", "required": [ "broadcaster_id", "user_id", "moderator_id", "reason" ], "properties": { "broadcaster_id": { "type": "string", "description": "The ID of the channel in which the warning will take effect." }, "user_id": { "type": "string", "description": "The ID of the warned user." }, "moderator_id": { "type": "string", "description": "The ID of the user who applied the warning." }, "reason": { "type": "string", "description": "The reason provided for warning." } } } } } }, "AddSuspiciousStatusToChatUserBody": { "type": "object", "required": [ "user_id", "status" ], "properties": { "user_id": { "type": "string", "description": "The ID of the user being given the suspicious status." }, "status": { "type": "string", "description": "The type of suspicious status. Possible values are: ACTIVE\\_MONITORING, RESTRICTED", "enum": [ "ACTIVE_MONITORING", "RESTRICTED" ] } } }, "AddSuspiciousStatusToChatUserResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "An array with one object containing information about the suspicious user action.", "items": { "type": "object", "required": [ "user_id", "broadcaster_id", "moderator_id", "updated_at", "status", "types" ], "properties": { "user_id": { "type": "string", "description": "The ID of the user being given the suspicious status." }, "broadcaster_id": { "type": "string", "description": "The user ID of the broadcaster indicating in which channel the status is being applied." }, "moderator_id": { "type": "string", "description": "The user ID of the moderator who applied the last status." }, "updated_at": { "type": "string", "description": "The timestamp of the last time this user’s status was updated.", "format": "date-time" }, "status": { "type": "string", "description": "The type of suspicious status. Possible values are: ACTIVE\\_MONITORING, RESTRICTED", "enum": [ "ACTIVE_MONITORING", "RESTRICTED" ] }, "types": { "type": "array", "description": "An array of strings representing the type(s) of suspicious user this is. Possible values are: MANUALLY\\_ADDED, DETECTED\\_BAN\\_EVADER, DETECTED\\_SUS\\_CHATTER, BANNED\\_IN\\_SHARED\\_CHANNEL", "items": { "type": "string", "enum": [ "MANUALLY_ADDED", "DETECTED_BAN_EVADER", "DETECTED_SUS_CHATTER", "BANNED_IN_SHARED_CHANNEL" ] } } } } } } }, "RemoveSuspiciousStatusFromChatUserResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "An array with one object containing information about the suspicious user action.", "items": { "type": "object", "required": [ "user_id", "broadcaster_id", "moderator_id", "updated_at", "status", "types" ], "properties": { "user_id": { "type": "string", "description": "The ID of the user having the suspicious status removed." }, "broadcaster_id": { "type": "string", "description": "The user ID of the broadcaster indicating in which channel the status is being removed." }, "moderator_id": { "type": "string", "description": "The user ID of the moderator who modified the last status." }, "updated_at": { "type": "string", "description": "The timestamp of the last time this user’s status was updated.", "format": "date-time" }, "status": { "type": "string", "description": "The type of suspicious status. Possible values are: NO\\_TREATMENT", "enum": [ "NO_TREATMENT" ] }, "types": { "type": "array", "description": "An array of strings representing the type(s) of suspicious user this is. Possible values are: MANUALLY\\_ADDED, DETECTED\\_BAN\\_EVADER, DETECTED\\_SUS\\_CHATTER, BANNED\\_IN\\_SHARED\\_CHANNEL", "items": { "type": "string", "enum": [ "MANUALLY_ADDED", "DETECTED_BAN_EVADER", "DETECTED_SUS_CHATTER", "BANNED_IN_SHARED_CHANNEL" ] } } } } } } }, "Poll": { "type": "object", "required": [ "id", "broadcaster_id", "broadcaster_name", "broadcaster_login", "title", "choices", "bits_voting_enabled", "bits_per_vote", "channel_points_voting_enabled", "channel_points_per_vote", "status", "duration", "started_at", "ended_at" ], "properties": { "id": { "type": "string", "description": "An ID that identifies the poll." }, "broadcaster_id": { "type": "string", "description": "An ID that identifies the broadcaster that created the poll." }, "broadcaster_name": { "type": "string", "description": "The broadcaster’s display name." }, "broadcaster_login": { "type": "string", "description": "The broadcaster’s login name." }, "title": { "type": "string", "description": "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": { "type": "array", "description": "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.", "items": { "type": "object", "required": [ "id", "title", "votes", "channel_points_votes", "bits_votes" ], "properties": { "id": { "type": "string", "description": "An ID that identifies this choice." }, "title": { "type": "string", "description": "The choice’s title. The title may contain a maximum of 25 characters." }, "votes": { "type": "integer", "description": "The total number of votes cast for this choice.", "format": "int32" }, "channel_points_votes": { "type": "integer", "description": "The number of votes cast using Channel Points.", "format": "int32" }, "bits_votes": { "type": "integer", "description": "Not used; will be set to 0.", "format": "int32" } } } }, "bits_voting_enabled": { "type": "boolean", "description": "Not used; will be set to **false**." }, "bits_per_vote": { "type": "integer", "description": "Not used; will be set to 0.", "format": "int32" }, "channel_points_voting_enabled": { "type": "boolean", "description": "A Boolean value that indicates whether viewers may cast additional votes using Channel Points. For information about Channel Points, see [Channel Points Guide](https://help.twitch.tv/s/article/channel-points-guide)." }, "channel_points_per_vote": { "type": "integer", "description": "The number of points the viewer must spend to cast one additional vote.", "format": "int32" }, "status": { "type": "string", "description": "The poll’s status. Valid values are: \n \n* ACTIVE — The poll is running.\n* COMPLETED — The poll ended on schedule (see the `duration` field).\n* TERMINATED — The poll was terminated before its scheduled end.\n* ARCHIVED — The poll has been archived and is no longer visible on the channel.\n* MODERATED — The poll was deleted.\n* INVALID — Something went wrong while determining the state.", "enum": [ "ACTIVE", "COMPLETED", "TERMINATED", "ARCHIVED", "MODERATED", "INVALID" ] }, "duration": { "type": "integer", "description": "The length of time (in seconds) that the poll will run for.", "format": "int32" }, "started_at": { "type": "string", "description": "The UTC date and time (in RFC3339 format) of when the poll began.", "format": "date-time" }, "ended_at": { "type": "string", "description": "The UTC date and time (in RFC3339 format) of when the poll ended. If `status` is ACTIVE, this field is set to **null**.", "format": "date-time", "nullable": true } } }, "GetPollsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "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.", "items": { "$ref": "#/components/schemas/Poll" } }, "pagination": { "description": "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](https://dev.twitch.tv/docs/api/guide#pagination)", "type": "object", "properties": { "cursor": { "type": "string", "description": "The cursor used to get the next page of results. Use the cursor to set the request's _after_ query parameter." } } } } }, "CreatePollBody": { "type": "object", "required": [ "broadcaster_id", "title", "choices", "duration" ], "properties": { "broadcaster_id": { "type": "string", "description": "The ID of the broadcaster that’s running the poll. This ID must match the user ID in the user access token." }, "title": { "type": "string", "description": "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": { "type": "array", "description": "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.", "items": { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string", "description": "One of the choices the viewer may select. The choice may contain a maximum of 25 characters." } } } }, "duration": { "type": "integer", "description": "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).", "format": "int32" }, "channel_points_voting_enabled": { "type": "boolean", "description": "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](https://help.twitch.tv/s/article/channel-points-guide)." }, "channel_points_per_vote": { "type": "integer", "description": "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**.", "format": "int32" } } }, "CreatePollResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "A list that contains the single poll that you created.", "items": { "$ref": "#/components/schemas/Poll" } } } }, "EndPollBody": { "type": "object", "required": [ "broadcaster_id", "id", "status" ], "properties": { "broadcaster_id": { "type": "string", "description": "The ID of the broadcaster that’s running the poll. This ID must match the user ID in the user access token." }, "id": { "type": "string", "description": "The ID of the poll to update." }, "status": { "type": "string", "description": "The status to set the poll to. Possible case-sensitive values are: \n \n* TERMINATED — Ends the poll before the poll is scheduled to end. The poll remains publicly visible.\n* ARCHIVED — Ends the poll before the poll is scheduled to end, and then archives it so it's no longer publicly visible.", "enum": [ "TERMINATED", "ARCHIVED" ] } } }, "EndPollResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "A list that contains the poll that you ended.", "items": { "$ref": "#/components/schemas/Poll" } } } }, "PredictionOutcome": { "type": "object", "required": [ "id", "title", "users", "channel_points", "top_predictors", "color" ], "properties": { "id": { "type": "string", "description": "An ID that identifies this outcome." }, "title": { "type": "string", "description": "The outcome’s text." }, "users": { "type": "integer", "description": "The number of unique viewers that chose this outcome.", "format": "int32" }, "channel_points": { "type": "integer", "description": "The number of Channel Points spent by viewers on this outcome.", "format": "int32" }, "top_predictors": { "type": "array", "description": "A list of viewers who were the top predictors; otherwise, **null** if none.", "items": { "type": "object", "required": [ "user_id", "user_name", "user_login", "channel_points_used", "channel_points_won" ], "properties": { "user_id": { "type": "string", "description": "An ID that identifies the viewer." }, "user_name": { "type": "string", "description": "The viewer’s display name." }, "user_login": { "type": "string", "description": "The viewer’s login name." }, "channel_points_used": { "type": "integer", "description": "The number of Channel Points the viewer spent.", "format": "int32" }, "channel_points_won": { "type": "integer", "description": "The number of Channel Points distributed to the viewer.", "format": "int32" } } }, "nullable": true }, "color": { "type": "string", "description": "The color that visually identifies this outcome in the UX. Possible values are: \n \n* BLUE\n* PINK\n \nIf 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.", "enum": [ "BLUE", "PINK" ] } } }, "Prediction": { "type": "object", "required": [ "id", "broadcaster_id", "broadcaster_name", "broadcaster_login", "title", "winning_outcome_id", "outcomes", "prediction_window", "status", "created_at", "ended_at", "locked_at" ], "properties": { "id": { "type": "string", "description": "An ID that identifies this prediction." }, "broadcaster_id": { "type": "string", "description": "An ID that identifies the broadcaster that created the prediction." }, "broadcaster_name": { "type": "string", "description": "The broadcaster’s display name." }, "broadcaster_login": { "type": "string", "description": "The broadcaster’s login name." }, "title": { "type": "string", "description": "The question that the prediction asks. For example, _Will I finish this entire pizza?_" }, "winning_outcome_id": { "type": "string", "description": "The ID of the winning outcome. Is **null** unless `status` is RESOLVED.", "nullable": true }, "outcomes": { "type": "array", "description": "The list of possible outcomes for the prediction.", "items": { "$ref": "#/components/schemas/PredictionOutcome" } }, "prediction_window": { "type": "integer", "description": "The length of time (in seconds) that the prediction will run for.", "format": "int32" }, "status": { "type": "string", "description": "The prediction’s status. Valid values are: \n \n* ACTIVE — The Prediction is running and viewers can make predictions.\n* CANCELED — The broadcaster canceled the Prediction and refunded the Channel Points to the participants.\n* LOCKED — The broadcaster locked the Prediction, which means viewers can no longer make predictions.\n* RESOLVED — The winning outcome was determined and the Channel Points were distributed to the viewers who predicted the correct outcome.", "enum": [ "ACTIVE", "CANCELED", "LOCKED", "RESOLVED" ] }, "created_at": { "type": "string", "description": "The UTC date and time of when the Prediction began.", "format": "date-time" }, "ended_at": { "type": "string", "description": "The UTC date and time of when the Prediction ended. If `status` is ACTIVE, this is set to **null**.", "format": "date-time", "nullable": true }, "locked_at": { "type": "string", "description": "The UTC date and time of when the Prediction was locked. If `status` is not LOCKED, this is set to **null**.", "format": "date-time", "nullable": true } } }, "GetPredictionsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "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.", "items": { "$ref": "#/components/schemas/Prediction" } }, "pagination": { "description": "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](https://dev.twitch.tv/docs/api/guide#pagination)", "type": "object", "properties": { "cursor": { "type": "string", "description": "The cursor used to get the next page of results. Use the cursor to set the request’s _after_ query parameter." } } } } }, "CreatePredictionBody": { "type": "object", "required": [ "broadcaster_id", "title", "outcomes", "prediction_window" ], "properties": { "broadcaster_id": { "type": "string", "description": "The ID of the broadcaster that’s running the prediction. This ID must match the user ID in the user access token." }, "title": { "type": "string", "description": "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": { "type": "array", "description": "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.", "items": { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string", "description": "The text of one of the outcomes that the viewer may select. The title is limited to a maximum of 25 characters." } } } }, "prediction_window": { "type": "integer", "description": "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).", "format": "int32" } } }, "CreatePredictionResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "A list that contains the single prediction that you created.", "items": { "$ref": "#/components/schemas/Prediction" } } } }, "EndPredictionBody": { "type": "object", "required": [ "broadcaster_id", "id", "status" ], "properties": { "broadcaster_id": { "type": "string", "description": "The ID of the broadcaster that’s running the prediction. This ID must match the user ID in the user access token." }, "id": { "type": "string", "description": "The ID of the prediction to update." }, "status": { "type": "string", "description": "The status to set the prediction to. Possible case-sensitive values are: \n \n* RESOLVED — The winning outcome is determined and the Channel Points are distributed to the viewers who predicted the correct outcome.\n* CANCELED — The broadcaster is canceling the prediction and sending refunds to the participants.\n* LOCKED — The broadcaster is locking the prediction, which means viewers may no longer make predictions.\n \nThe broadcaster can update an active prediction to LOCKED, RESOLVED, or CANCELED; and update a locked prediction to RESOLVED or CANCELED. \n \nThe 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.", "enum": [ "RESOLVED", "CANCELED", "LOCKED" ] }, "winning_outcome_id": { "type": "string", "description": "The ID of the winning outcome. You must set this parameter if you set `status` to RESOLVED." } } }, "EndPredictionResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "A list that contains the single prediction that you updated.", "items": { "$ref": "#/components/schemas/Prediction" } } } }, "StartARaidResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "A list that contains a single object with information about the pending raid.", "items": { "type": "object", "required": [ "created_at", "is_mature" ], "properties": { "created_at": { "type": "string", "description": "The UTC date and time, in RFC3339 format, of when the raid was requested.", "format": "date-time" }, "is_mature": { "type": "boolean", "description": "**IMPORTANT** This field is deprecated and returns only `false`. \n \nA Boolean value that indicates whether the channel being raided contains mature content." } } } } } }, "ChannelStreamScheduleSegment": { "type": "object", "required": [ "id", "start_time", "end_time", "title", "canceled_until", "category", "is_recurring" ], "properties": { "id": { "type": "string", "description": "An ID that identifies this broadcast segment." }, "start_time": { "type": "string", "description": "The UTC date and time (in RFC3339 format) of when the broadcast starts.", "format": "date-time" }, "end_time": { "type": "string", "description": "The UTC date and time (in RFC3339 format) of when the broadcast ends.", "format": "date-time" }, "title": { "type": "string", "description": "The broadcast segment’s title." }, "canceled_until": { "type": "string", "description": "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**.", "nullable": true }, "category": { "description": "The type of content that the broadcaster plans to stream or **null** if not specified.", "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "description": "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": { "type": "string", "description": "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": { "type": "boolean", "description": "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." } } }, "GetChannelStreamScheduleResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "description": "The broadcaster’s streaming schedule.", "type": "object", "required": [ "segments", "broadcaster_id", "broadcaster_name", "broadcaster_login", "vacation" ], "properties": { "segments": { "type": "array", "description": "The list of broadcasts in the broadcaster’s streaming schedule.", "items": { "$ref": "#/components/schemas/ChannelStreamScheduleSegment" } }, "broadcaster_id": { "type": "string", "description": "The ID of the broadcaster that owns the broadcast schedule." }, "broadcaster_name": { "type": "string", "description": "The broadcaster’s display name." }, "broadcaster_login": { "type": "string", "description": "The broadcaster’s login name." }, "vacation": { "description": "The dates when the broadcaster is on vacation and not streaming. Is set to **null** if vacation mode is not enabled.", "type": "object", "required": [ "start_time", "end_time" ], "properties": { "start_time": { "type": "string", "description": "The UTC date and time (in RFC3339 format) of when the broadcaster’s vacation starts.", "format": "date-time" }, "end_time": { "type": "string", "description": "The UTC date and time (in RFC3339 format) of when the broadcaster’s vacation ends.", "format": "date-time" } } }, "pagination": { "description": "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](https://dev.twitch.tv/docs/api/guide#pagination).", "type": "object", "properties": { "cursor": { "type": "string", "description": "The cursor used to get the next page of results. Set the request’s _after_ query parameter to this value." } } } } } } }, "CreateChannelStreamScheduleSegmentBody": { "type": "object", "required": [ "start_time", "timezone", "duration" ], "properties": { "start_time": { "type": "string", "description": "The date and time that the broadcast segment starts. Specify the date and time in RFC3339 format (for example, 2021-07-01T18:00:00Z).", "format": "date-time" }, "timezone": { "type": "string", "description": "The time zone where the broadcast takes place. Specify the time zone using [IANA time zone database](https://www.iana.org/time-zones) format (for example, America/New\\_York)." }, "duration": { "type": "string", "description": "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": { "type": "boolean", "description": "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": { "type": "string", "description": "The ID of the category that best represents the broadcast’s content. To get the category ID, use the [Search Categories](https://dev.twitch.tv/docs/api/reference#search-categories) endpoint." }, "title": { "type": "string", "description": "The broadcast’s title. The title may contain a maximum of 140 characters." } } }, "CreateChannelStreamScheduleSegmentResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "description": "The broadcaster’s streaming scheduled.", "type": "object", "required": [ "segments", "broadcaster_id", "broadcaster_name", "broadcaster_login", "vacation" ], "properties": { "segments": { "type": "array", "description": "A list that contains the single broadcast segment that you added.", "items": { "$ref": "#/components/schemas/ChannelStreamScheduleSegment" } }, "broadcaster_id": { "type": "string", "description": "The ID of the broadcaster that owns the broadcast schedule." }, "broadcaster_name": { "type": "string", "description": "The broadcaster’s display name." }, "broadcaster_login": { "type": "string", "description": "The broadcaster’s login name." }, "vacation": { "description": "The dates when the broadcaster is on vacation and not streaming. Is set to **null** if vacation mode is not enabled.", "type": "object", "required": [ "start_time", "end_time" ], "properties": { "start_time": { "type": "string", "description": "The UTC date and time (in RFC3339 format) of when the broadcaster’s vacation starts.", "format": "date-time" }, "end_time": { "type": "string", "description": "The UTC date and time (in RFC3339 format) of when the broadcaster’s vacation ends.", "format": "date-time" } } } } } } }, "UpdateChannelStreamScheduleSegmentBody": { "type": "object", "properties": { "start_time": { "type": "string", "description": "The date and time that the broadcast segment starts. Specify the date and time in RFC3339 format (for example, 2022-08-02T06:00:00Z). \n \n**NOTE**: Only partners and affiliates may update a broadcast’s start time and only for non-recurring segments.", "format": "date-time" }, "duration": { "type": "string", "description": "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": { "type": "string", "description": "The ID of the category that best represents the broadcast’s content. To get the category ID, use the [Search Categories](https://dev.twitch.tv/docs/api/reference#search-categories) endpoint." }, "title": { "type": "string", "description": "The broadcast’s title. The title may contain a maximum of 140 characters." }, "is_canceled": { "type": "boolean", "description": "A Boolean value that indicates whether the broadcast is canceled. Set to **true** to cancel the segment. \n \n**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": { "type": "string", "description": "The time zone where the broadcast takes place. Specify the time zone using [IANA time zone database](https://www.iana.org/time-zones) format (for example, America/New\\_York)." } } }, "UpdateChannelStreamScheduleSegmentResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "description": "The broadcaster’s streaming scheduled.", "type": "object", "required": [ "segments", "broadcaster_id", "broadcaster_name", "broadcaster_login", "vacation" ], "properties": { "segments": { "type": "array", "description": "A list that contains the single broadcast segment that you updated.", "items": { "$ref": "#/components/schemas/ChannelStreamScheduleSegment" } }, "broadcaster_id": { "type": "string", "description": "The ID of the broadcaster that owns the broadcast schedule." }, "broadcaster_name": { "type": "string", "description": "The broadcaster’s display name." }, "broadcaster_login": { "type": "string", "description": "The broadcaster’s login name." }, "vacation": { "description": "The dates when the broadcaster is on vacation and not streaming. Is set to **null** if vacation mode is not enabled.", "type": "object", "required": [ "start_time", "end_time" ], "properties": { "start_time": { "type": "string", "description": "The UTC date and time (in RFC3339 format) of when the broadcaster’s vacation starts.", "format": "date-time" }, "end_time": { "type": "string", "description": "The UTC date and time (in RFC3339 format) of when the broadcaster’s vacation ends.", "format": "date-time" } } } } } } }, "Category": { "type": "object", "required": [ "box_art_url", "name", "id" ], "properties": { "box_art_url": { "type": "string", "description": "A URL to an image of the game’s box art or streaming category." }, "name": { "type": "string", "description": "The name of the game or category." }, "id": { "type": "string", "description": "An ID that uniquely identifies the game or category." } } }, "SearchCategoriesResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "The list of games or categories that match the query. The list is empty if there are no matches.", "items": { "$ref": "#/components/schemas/Category" } }, "pagination": { "description": "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](https://dev.twitch.tv/docs/api/guide#pagination)", "type": "object", "properties": { "cursor": { "type": "string", "description": "The cursor used to get the next page of results. Use the cursor to set the request’s _after_ query parameter." } } } } }, "Channel": { "type": "object", "required": [ "broadcaster_language", "broadcaster_login", "display_name", "game_id", "game_name", "id", "is_live", "tag_ids", "tags", "thumbnail_url", "title", "started_at" ], "properties": { "broadcaster_language": { "type": "string", "description": "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](https://help.twitch.tv/s/article/languages-on-twitch#streamlang), the value is _other_." }, "broadcaster_login": { "type": "string", "description": "The broadcaster’s login name." }, "display_name": { "type": "string", "description": "The broadcaster’s display name." }, "game_id": { "type": "string", "description": "The ID of the game that the broadcaster is playing or last played." }, "game_name": { "type": "string", "description": "The name of the game that the broadcaster is playing or last played." }, "id": { "type": "string", "description": "An ID that uniquely identifies the channel (this is the broadcaster’s ID)." }, "is_live": { "type": "boolean", "description": "A Boolean value that determines whether the broadcaster is streaming live. Is **true** if the broadcaster is streaming live; otherwise, **false**." }, "tag_ids": { "type": "array", "description": "**IMPORTANT** As of February 28, 2023, this field is deprecated and returns only an empty array. If you use this field, please update your code to use the `tags` field. \n \nThe 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](https://www.twitch.tv/directory/all/tags). The list doesn’t include Category Tags.", "items": { "type": "string" }, "deprecated": true }, "tags": { "type": "array", "description": "The tags applied to the channel.", "items": { "type": "string" } }, "thumbnail_url": { "type": "string", "description": "A URL to a thumbnail of the broadcaster’s profile image." }, "title": { "type": "string", "description": "The stream’s title. Is an empty string if the broadcaster didn’t set it." }, "started_at": { "type": "string", "description": "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.", "format": "date-time" } } }, "SearchChannelsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "The list of channels that match the query. The list is empty if there are no matches.", "items": { "$ref": "#/components/schemas/Channel" } }, "pagination": { "description": "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](https://dev.twitch.tv/docs/api/guide#pagination)", "type": "object", "properties": { "cursor": { "type": "string", "description": "The cursor used to get the next page of results. Use the cursor to set the request’s _after_ query parameter." } } } } }, "GetStreamKeyResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "A list that contains the channel’s stream key.", "items": { "type": "object", "required": [ "stream_key" ], "properties": { "stream_key": { "type": "string", "description": "The channel’s stream key." } } } } } }, "Stream": { "type": "object", "required": [ "id", "user_id", "user_login", "user_name", "game_id", "game_name", "type", "title", "viewer_count", "started_at", "language", "thumbnail_url", "tag_ids", "tags", "is_mature" ], "properties": { "id": { "type": "string", "description": "An ID that identifies the stream. You can use this ID later to look up the video on demand (VOD)." }, "user_id": { "type": "string", "description": "The ID of the user that’s broadcasting the stream." }, "user_login": { "type": "string", "description": "The user’s login name." }, "user_name": { "type": "string", "description": "The user’s display name." }, "game_id": { "type": "string", "description": "The ID of the category or game being played." }, "game_name": { "type": "string", "description": "The ID of the category or game being played." }, "type": { "type": "string", "description": "The type of stream. Possible values are: \n \n* live\n \nIf an error occurs, this field is set to an empty string.", "enum": [ "live" ] }, "title": { "type": "string", "description": "The stream’s title. Is an empty string if not set." }, "viewer_count": { "type": "integer", "description": "The number of users watching the stream.", "format": "int32" }, "started_at": { "type": "string", "description": "The UTC date and time (in RFC3339 format) of when the broadcast began.", "format": "date-time" }, "language": { "type": "string", "description": "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](https://help.twitch.tv/s/article/languages-on-twitch#streamlang)." }, "thumbnail_url": { "type": "string", "description": "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": { "type": "array", "description": "**IMPORTANT** As of February 28, 2023, this field is deprecated and returns only an empty array. If you use this field, please update your code to use the `tags` field. \n \nThe 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](https://www.twitch.tv/directory/all/tags). The list doesn’t include Category Tags.", "items": { "type": "string" }, "deprecated": true }, "tags": { "type": "array", "description": "The tags applied to the stream.", "items": { "type": "string" } }, "is_mature": { "type": "boolean", "description": "**IMPORTANT** This field is deprecated and returns only `false`. \n \nA Boolean value that indicates whether the stream is meant for mature audiences." } } }, "GetStreamsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "The list of streams.", "items": { "$ref": "#/components/schemas/Stream" } }, "pagination": { "description": "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](https://dev.twitch.tv/docs/api/guide#pagination)", "type": "object", "properties": { "cursor": { "type": "string", "description": "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." } } } } }, "GetFollowedStreamsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "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.", "items": { "$ref": "#/components/schemas/Stream" } }, "pagination": { "description": "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](https://dev.twitch.tv/docs/api/guide#pagination)", "type": "object", "properties": { "cursor": { "type": "string", "description": "The cursor used to get the next page of results. Set the request’s _after_ query parameter to this value." } } } } }, "CreateStreamMarkerBody": { "type": "object", "required": [ "user_id" ], "properties": { "user_id": { "type": "string", "description": "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": { "type": "string", "description": "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." } } }, "StreamMarkerCreated": { "type": "object", "required": [ "id", "created_at", "position_seconds", "description" ], "properties": { "id": { "type": "string", "description": "An ID that identifies this marker." }, "created_at": { "type": "string", "description": "The UTC date and time (in RFC3339 format) of when the user created the marker.", "format": "date-time" }, "position_seconds": { "type": "integer", "description": "The relative offset (in seconds) of the marker from the beginning of the stream.", "format": "int32" }, "description": { "type": "string", "description": "A description that the user gave the marker to help them remember why they marked the location." } } }, "CreateStreamMarkerResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "A list that contains the single marker that you added.", "items": { "$ref": "#/components/schemas/StreamMarkerCreated" } } } }, "StreamMarkers": { "type": "object", "required": [ "user_id", "user_name", "user_login", "videos" ], "properties": { "user_id": { "type": "string", "description": "The ID of the user that created the marker." }, "user_name": { "type": "string", "description": "The user’s display name." }, "user_login": { "type": "string", "description": "The user’s login name." }, "videos": { "type": "array", "description": "A list of videos that contain markers. The list contains a single video.", "items": { "type": "object", "required": [ "video_id", "markers" ], "properties": { "video_id": { "type": "string", "description": "An ID that identifies this video." }, "markers": { "type": "array", "description": "The list of markers in this video. The list in ascending order by when the marker was created.", "items": { "type": "object", "required": [ "id", "created_at", "description", "position_seconds", "url" ], "properties": { "id": { "type": "string", "description": "An ID that identifies this marker." }, "created_at": { "type": "string", "description": "The UTC date and time (in RFC3339 format) of when the user created the marker.", "format": "date-time" }, "description": { "type": "string", "description": "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": { "type": "integer", "description": "The relative offset (in seconds) of the marker from the beginning of the stream.", "format": "int32" }, "url": { "type": "string", "description": "A URL that opens the video in Twitch Highlighter." } } } } } } } } }, "GetStreamMarkersResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "The list of markers grouped by the user that created the marks.", "items": { "$ref": "#/components/schemas/StreamMarkers" } }, "pagination": { "description": "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](https://dev.twitch.tv/docs/api/guide#pagination)", "type": "object", "properties": { "cursor": { "type": "string", "description": "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." } } } } }, "BroadcasterSubscription": { "type": "object", "required": [ "broadcaster_id", "broadcaster_login", "broadcaster_name", "gifter_id", "gifter_login", "gifter_name", "is_gift", "plan_name", "tier", "user_id", "user_name", "user_login" ], "properties": { "broadcaster_id": { "type": "string", "description": "An ID that identifies the broadcaster." }, "broadcaster_login": { "type": "string", "description": "The broadcaster’s login name." }, "broadcaster_name": { "type": "string", "description": "The broadcaster’s display name." }, "gifter_id": { "type": "string", "description": "The ID of the user that gifted the subscription to the user. Is an empty string if `is_gift` is **false**." }, "gifter_login": { "type": "string", "description": "The gifter’s login name. Is an empty string if `is_gift` is **false**." }, "gifter_name": { "type": "string", "description": "The gifter’s display name. Is an empty string if `is_gift` is **false**." }, "is_gift": { "type": "boolean", "description": "A Boolean value that determines whether the subscription is a gift subscription. Is **true** if the subscription was gifted." }, "plan_name": { "type": "string", "description": "The name of the subscription." }, "tier": { "type": "string", "description": "The type of subscription. Possible values are: \n \n* 1000 — Tier 1\n* 2000 — Tier 2\n* 3000 — Tier 3", "enum": [ "1000", "2000", "3000" ] }, "user_id": { "type": "string", "description": "An ID that identifies the subscribing user." }, "user_name": { "type": "string", "description": "The user’s display name." }, "user_login": { "type": "string", "description": "The user’s login name." } } }, "GetBroadcasterSubscriptionsResponse": { "type": "object", "required": [ "data", "points", "total" ], "properties": { "data": { "type": "array", "description": "The list of users that subscribe to the broadcaster. The list is empty if the broadcaster has no subscribers.", "items": { "$ref": "#/components/schemas/BroadcasterSubscription" } }, "pagination": { "description": "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](https://dev.twitch.tv/docs/api/guide#pagination)", "type": "object", "properties": { "cursor": { "type": "string", "description": "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": { "type": "integer", "description": "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](https://help.twitch.tv/s/article/subscriber-emote-guide#emoteslots)).", "format": "int32" }, "total": { "type": "integer", "description": "The total number of users that subscribe to this broadcaster.", "format": "int32" } } }, "UserSubscription": { "type": "object", "required": [ "broadcaster_id", "broadcaster_login", "broadcaster_name", "is_gift", "tier" ], "properties": { "broadcaster_id": { "type": "string", "description": "An ID that identifies the broadcaster." }, "broadcaster_login": { "type": "string", "description": "The broadcaster’s login name." }, "broadcaster_name": { "type": "string", "description": "The broadcaster’s display name." }, "gifter_id": { "type": "string", "description": "The ID of the user that gifted the subscription. The object includes this field only if `is_gift` is **true**." }, "gifter_login": { "type": "string", "description": "The gifter’s login name. The object includes this field only if `is_gift` is **true**." }, "gifter_name": { "type": "string", "description": "The gifter’s display name. The object includes this field only if `is_gift` is **true**." }, "is_gift": { "type": "boolean", "description": "A Boolean value that determines whether the subscription is a gift subscription. Is **true** if the subscription was gifted." }, "tier": { "type": "string", "description": "The type of subscription. Possible values are: \n \n* 1000 — Tier 1\n* 2000 — Tier 2\n* 3000 — Tier 3", "enum": [ "1000", "2000", "3000" ] } } }, "CheckUserSubscriptionResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "A list that contains a single object with information about the user’s subscription.", "items": { "$ref": "#/components/schemas/UserSubscription" } } } }, "StreamTag": { "type": "object", "required": [ "tag_id", "is_auto", "localization_names", "localization_descriptions" ], "properties": { "tag_id": { "type": "string", "description": "An ID that identifies this tag." }, "is_auto": { "type": "boolean", "description": "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": { "type": "object", "description": "A dictionary that contains the localized names of the tag. The key is in the form, -. For example, en-us. The value is the localized name.", "additionalProperties": { "type": "string" } }, "localization_descriptions": { "type": "object", "description": "A dictionary that contains the localized descriptions of the tag. The key is in the form, -. For example, en-us. The value is the localized description.", "additionalProperties": { "type": "string" } } } }, "GetAllStreamTagsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "The list of stream tags that the broadcaster can apply to their channel.", "items": { "$ref": "#/components/schemas/StreamTag" } }, "pagination": { "description": "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](https://dev.twitch.tv/docs/api/guide#pagination)", "type": "object", "properties": { "cursor": { "type": "string", "description": "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." } } } }, "deprecated": true }, "GetStreamTagsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "The list of stream tags. The list is empty if the broadcaster or Twitch hasn’t added tags to the broadcaster’s channel.", "items": { "$ref": "#/components/schemas/StreamTag" } } }, "deprecated": true }, "ChannelTeam": { "type": "object", "required": [ "broadcaster_id", "broadcaster_login", "broadcaster_name", "background_image_url", "banner", "created_at", "updated_at", "info", "thumbnail_url", "team_name", "team_display_name", "id" ], "properties": { "broadcaster_id": { "type": "string", "description": "An ID that identifies the broadcaster." }, "broadcaster_login": { "type": "string", "description": "The broadcaster’s login name." }, "broadcaster_name": { "type": "string", "description": "The broadcaster’s display name." }, "background_image_url": { "type": "string", "description": "A URL to the team’s background image." }, "banner": { "type": "string", "description": "A URL to the team’s banner." }, "created_at": { "type": "string", "description": "The UTC date and time (in RFC3339 format) of when the team was created.", "format": "date-time" }, "updated_at": { "type": "string", "description": "The UTC date and time (in RFC3339 format) of the last time the team was updated.", "format": "date-time" }, "info": { "type": "string", "description": "The team’s description. The description may contain formatting such as Markdown, HTML, newline (\\\\n) characters, etc." }, "thumbnail_url": { "type": "string", "description": "A URL to a thumbnail image of the team’s logo." }, "team_name": { "type": "string", "description": "The team’s name." }, "team_display_name": { "type": "string", "description": "The team’s display name." }, "id": { "type": "string", "description": "An ID that identifies the team." } } }, "GetChannelTeamsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "The list of teams that the broadcaster is a member of. Returns an empty array if the broadcaster is not a member of a team.", "items": { "$ref": "#/components/schemas/ChannelTeam" } } } }, "Team": { "type": "object", "required": [ "users", "background_image_url", "banner", "created_at", "updated_at", "info", "thumbnail_url", "team_name", "team_display_name", "id" ], "properties": { "users": { "type": "array", "description": "The list of team members.", "items": { "type": "object", "required": [ "user_id", "user_login", "user_name" ], "properties": { "user_id": { "type": "string", "description": "An ID that identifies the team member." }, "user_login": { "type": "string", "description": "The team member’s login name." }, "user_name": { "type": "string", "description": "The team member’s display name." } } } }, "background_image_url": { "type": "string", "description": "A URL to the team’s background image." }, "banner": { "type": "string", "description": "A URL to the team’s banner." }, "created_at": { "type": "string", "description": "The UTC date and time (in RFC3339 format) of when the team was created.", "format": "date-time" }, "updated_at": { "type": "string", "description": "The UTC date and time (in RFC3339 format) of the last time the team was updated.", "format": "date-time" }, "info": { "type": "string", "description": "The team’s description. The description may contain formatting such as Markdown, HTML, newline (\\\\n) characters, etc." }, "thumbnail_url": { "type": "string", "description": "A URL to a thumbnail image of the team’s logo." }, "team_name": { "type": "string", "description": "The team’s name." }, "team_display_name": { "type": "string", "description": "The team’s display name." }, "id": { "type": "string", "description": "An ID that identifies the team." } } }, "GetTeamsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "A list that contains the single team that you requested.", "items": { "$ref": "#/components/schemas/Team" } } } }, "User": { "type": "object", "required": [ "id", "login", "display_name", "type", "broadcaster_type", "description", "profile_image_url", "offline_image_url", "view_count", "created_at" ], "properties": { "id": { "type": "string", "description": "An ID that identifies the user." }, "login": { "type": "string", "description": "The user's login name." }, "display_name": { "type": "string", "description": "The user's display name." }, "type": { "type": "string", "description": "The type of user. Possible values are: \n \n* admin — Twitch administrator\n* global\\_mod\n* staff — Twitch staff\n* \"\" — Normal user", "enum": [ "admin", "global_mod", "staff", "" ] }, "broadcaster_type": { "type": "string", "description": "The type of broadcaster. Possible values are: \n \n* affiliate — An [affiliate broadcaster](https://help.twitch.tv/s/article/joining-the-affiliate-program)\n* partner — A [partner broadcaster](https://help.twitch.tv/s/article/partner-program-overview)\n* \"\" — A normal broadcaster", "enum": [ "affiliate", "partner", "" ] }, "description": { "type": "string", "description": "The user's description of their channel." }, "profile_image_url": { "type": "string", "description": "A URL to the user's profile image." }, "offline_image_url": { "type": "string", "description": "A URL to the user's offline image." }, "view_count": { "type": "integer", "description": "The number of times the user's channel has been viewed. \n \n**NOTE**: This field has been deprecated (see [Get Users API endpoint – \"view\\_count\" deprecation](https://discuss.dev.twitch.tv/t/get-users-api-endpoint-view-count-deprecation/37777)). Any data in this field is not valid and should not be used.", "format": "int32", "deprecated": true }, "email": { "type": "string", "description": "The user's verified email address. The object includes this field only if the user access token includes the **user:read:email** scope. \n \nIf 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": { "type": "string", "description": "The UTC date and time that the user's account was created. The timestamp is in RFC3339 format.", "format": "date-time" } } }, "GetUsersResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "The list of users.", "items": { "$ref": "#/components/schemas/User" } } } }, "UpdateUserResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "A list contains the single user that you updated.", "items": { "$ref": "#/components/schemas/User" } } } }, "GetAuthorizationByUserResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "List of users and their authorized scopes.", "items": { "type": "object", "required": [ "user_id", "user_name", "user_login", "scopes" ], "properties": { "user_id": { "type": "string", "description": "The user’s ID." }, "user_name": { "type": "string", "description": "The user’s display name." }, "user_login": { "type": "string", "description": "The user’s login name." }, "scopes": { "type": "array", "description": "An array of all the scopes the user has granted to the client ID.", "items": { "type": "string", "enum": [ "analytics:read:extensions", "analytics:read:games", "bits:read", "channel:bot", "channel:manage:ads", "channel:read:ads", "channel:manage:broadcast", "channel:read:charity", "channel:manage:clips", "channel:edit:commercial", "channel:read:editors", "channel:manage:extensions", "channel:read:goals", "channel:read:guest_star", "channel:manage:guest_star", "channel:read:hype_train", "channel:manage:moderators", "channel:read:polls", "channel:manage:polls", "channel:read:predictions", "channel:manage:predictions", "channel:manage:raids", "channel:read:redemptions", "channel:manage:redemptions", "channel:manage:schedule", "channel:read:stream_key", "channel:read:subscriptions", "channel:manage:videos", "channel:read:vips", "channel:manage:vips", "channel:moderate", "clips:edit", "editor:manage:clips", "moderation:read", "moderator:manage:announcements", "moderator:manage:automod", "moderator:read:automod_settings", "moderator:manage:automod_settings", "moderator:read:banned_users", "moderator:manage:banned_users", "moderator:read:blocked_terms", "moderator:read:chat_messages", "moderator:manage:blocked_terms", "moderator:manage:chat_messages", "moderator:read:chat_settings", "moderator:manage:chat_settings", "moderator:read:chatters", "moderator:read:followers", "moderator:read:guest_star", "moderator:manage:guest_star", "moderator:read:moderators", "moderator:read:shield_mode", "moderator:manage:shield_mode", "moderator:read:shoutouts", "moderator:manage:shoutouts", "moderator:read:suspicious_users", "moderator:manage:suspicious_users", "moderator:read:unban_requests", "moderator:manage:unban_requests", "moderator:read:vips", "moderator:read:warnings", "moderator:manage:warnings", "user:bot", "user:edit", "user:edit:broadcast", "user:read:blocked_users", "user:manage:blocked_users", "user:read:broadcast", "user:read:chat", "user:manage:chat_color", "user:read:email", "user:read:emotes", "user:read:follows", "user:read:moderated_channels", "user:read:subscriptions", "user:read:whispers", "user:manage:whispers", "user:write:chat", "chat:edit", "chat:read", "whispers:read" ] } } } } } } }, "UserBlockList": { "type": "object", "required": [ "user_id", "user_login", "display_name" ], "properties": { "user_id": { "type": "string", "description": "An ID that identifies the blocked user." }, "user_login": { "type": "string", "description": "The blocked user’s login name." }, "display_name": { "type": "string", "description": "The blocked user’s display name." } } }, "GetUserBlockListResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "The list of blocked users. The list is in descending order by when the user was blocked.", "items": { "$ref": "#/components/schemas/UserBlockList" } }, "pagination": { "description": "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](https://dev.twitch.tv/docs/api/guide#pagination)", "type": "object", "properties": { "cursor": { "type": "string", "description": "The cursor used to get the next page of results. Use the cursor to set the request’s _after_ query parameter." } } } } }, "UserExtension": { "type": "object", "required": [ "id", "version", "name", "can_activate", "type" ], "properties": { "id": { "type": "string", "description": "An ID that identifies the extension." }, "version": { "type": "string", "description": "The extension's version." }, "name": { "type": "string", "description": "The extension's name." }, "can_activate": { "type": "boolean", "description": "A Boolean value that determines whether the extension is configured and can be activated. Is **true** if the extension is configured and can be activated." }, "type": { "type": "array", "description": "The extension types that you can activate for this extension. Possible values are: \n \n* component\n* mobile\n* overlay\n* panel", "items": { "type": "string", "enum": [ "component", "mobile", "overlay", "panel" ] } } } }, "GetUserExtensionsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "The list of extensions that the user has installed.", "items": { "$ref": "#/components/schemas/UserExtension" } } } }, "UserExtensionPanel": { "type": "object", "required": [ "active" ], "properties": { "active": { "type": "boolean", "description": "A Boolean value that determines the extension’s activation state. If **false**, the user has not configured a panel extension." }, "id": { "type": "string", "description": "An ID that identifies the extension." }, "version": { "type": "string", "description": "The extension’s version." }, "name": { "type": "string", "description": "The extension’s name." } } }, "UserExtensionPanelUpdate": { "type": "object", "required": [ "active" ], "properties": { "active": { "type": "boolean", "description": "A Boolean value that determines the extension’s activation state. If **false**, the user has not configured a panel extension." }, "id": { "type": "string", "description": "An ID that identifies the extension." }, "version": { "type": "string", "description": "The extension’s version." } } }, "UserExtensionOverlay": { "type": "object", "required": [ "active" ], "properties": { "active": { "type": "boolean", "description": "A Boolean value that determines the extension’s activation state. If **false**, the user has not configured an overlay extension." }, "id": { "type": "string", "description": "An ID that identifies the extension." }, "version": { "type": "string", "description": "The extension’s version." }, "name": { "type": "string", "description": "The extension’s name." } } }, "UserExtensionOverlayUpdate": { "type": "object", "required": [ "active" ], "properties": { "active": { "type": "boolean", "description": "A Boolean value that determines the extension’s activation state. If **false**, the user has not configured an overlay extension." }, "id": { "type": "string", "description": "An ID that identifies the extension." }, "version": { "type": "string", "description": "The extension’s version." } } }, "UserExtensionComponent": { "type": "object", "required": [ "active" ], "properties": { "active": { "type": "boolean", "description": "A Boolean value that determines the extension’s activation state. If **false**, the user has not configured a component extension." }, "id": { "type": "string", "description": "An ID that identifies the extension." }, "version": { "type": "string", "description": "The extension’s version." }, "name": { "type": "string", "description": "The extension’s name." }, "x": { "type": "integer", "description": "The x-coordinate where the extension is placed.", "format": "int32" }, "y": { "type": "integer", "description": "The y-coordinate where the extension is placed.", "format": "int32" } } }, "UserExtensionComponentUpdate": { "type": "object", "required": [ "active" ], "properties": { "active": { "type": "boolean", "description": "A Boolean value that determines the extension’s activation state. If **false**, the user has not configured a component extension." }, "id": { "type": "string", "description": "An ID that identifies the extension." }, "version": { "type": "string", "description": "The extension’s version." }, "x": { "type": "integer", "description": "The x-coordinate where the extension is placed.", "format": "int32" }, "y": { "type": "integer", "description": "The y-coordinate where the extension is placed.", "format": "int32" } } }, "GetUserActiveExtensionsResponse": { "type": "object", "properties": { "data": { "description": "The active extensions that the broadcaster has installed.", "type": "object", "properties": { "panel": { "type": "object", "description": "A dictionary that contains the data for a panel extension. The dictionary’s key is a sequential number beginning with 1\\. The following fields contain the panel’s data for each key.", "additionalProperties": { "$ref": "#/components/schemas/UserExtensionPanel" } }, "overlay": { "type": "object", "description": "A dictionary that contains the data for a video-overlay extension. The dictionary’s key is a sequential number beginning with 1\\. The following fields contain the overlay’s data for each key.", "additionalProperties": { "$ref": "#/components/schemas/UserExtensionOverlay" } }, "component": { "type": "object", "description": "A dictionary that contains the data for a video-component extension. The dictionary’s key is a sequential number beginning with 1\\. The following fields contain the component’s data for each key.", "additionalProperties": { "$ref": "#/components/schemas/UserExtensionComponent" } } } } } }, "UpdateUserExtensionsBody": { "type": "object", "required": [ "data" ], "properties": { "data": { "description": "The extensions to update. The `data` field is a dictionary of extension types. The dictionary’s possible keys are: panel, overlay, or component. The key’s value is a dictionary of extensions. \n \nFor the extension’s dictionary, the key is a sequential number beginning with 1\\. For panel and overlay extensions, the key’s value is an object that contains the following fields: `active` (true/false), `id` (the extension’s ID), and `version` (the extension’s version). \n \nFor component extensions, the key’s value includes the above fields plus the `x` and `y` fields, which identify the coordinate where the extension is placed.", "properties": { "panel": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/UserExtensionPanelUpdate" } }, "overlay": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/UserExtensionOverlayUpdate" } }, "component": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/UserExtensionComponentUpdate" } } } } } }, "UpdateUserExtensionsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "description": "The extensions that the broadcaster updated.", "type": "object", "required": [ "panel", "overlay", "component" ], "properties": { "panel": { "type": "object", "description": "A dictionary that contains the data for a panel extension. The dictionary’s key is a sequential number beginning with 1\\. The following fields contain the panel’s data for each key.", "additionalProperties": { "$ref": "#/components/schemas/UserExtensionPanel" } }, "overlay": { "type": "object", "description": "A dictionary that contains the data for a video-overlay extension. The dictionary’s key is a sequential number beginning with 1\\. The following fields contain the overlay’s data for each key.", "additionalProperties": { "$ref": "#/components/schemas/UserExtensionOverlay" } }, "component": { "type": "object", "description": "A dictionary that contains the data for a video-component extension. The dictionary’s key is a sequential number beginning with 1\\. The following fields contain the component’s data for each key.", "additionalProperties": { "$ref": "#/components/schemas/UserExtensionComponent" } } } } } }, "Video": { "type": "object", "required": [ "id", "stream_id", "user_id", "user_login", "user_name", "title", "description", "created_at", "published_at", "url", "thumbnail_url", "viewable", "view_count", "language", "type", "duration", "muted_segments" ], "properties": { "id": { "type": "string", "description": "An ID that identifies the video." }, "stream_id": { "type": "string", "description": "The ID of the stream that the video originated from if the video's type is \"archive;\" otherwise, **null**.", "nullable": true }, "user_id": { "type": "string", "description": "The ID of the broadcaster that owns the video." }, "user_login": { "type": "string", "description": "The broadcaster's login name." }, "user_name": { "type": "string", "description": "The broadcaster's display name." }, "title": { "type": "string", "description": "The video's title." }, "description": { "type": "string", "description": "The video's description." }, "created_at": { "type": "string", "description": "The date and time, in UTC, of when the video was created. The timestamp is in RFC3339 format.", "format": "date-time" }, "published_at": { "type": "string", "description": "The date and time, in UTC, of when the video was published. The timestamp is in RFC3339 format.", "format": "date-time" }, "url": { "type": "string", "description": "The video's URL." }, "thumbnail_url": { "type": "string", "description": "A URL to a thumbnail image of the video. Before using the URL, you must replace the `%{width}` and `%{height}` placeholders with the width and height of the thumbnail you want returned. Due to current limitations, `${width}` must be 320 and `${height}` must be 180." }, "viewable": { "type": "string", "description": "The video's viewable state. Always set to **public**." }, "view_count": { "type": "integer", "description": "The number of times that users have watched the video.", "format": "int32" }, "language": { "type": "string", "description": "The ISO 639-1 two-letter language code that the video was broadcast in. For example, the language code is DE if the video was broadcast in German. For a list of supported languages, see [Supported Stream Language](https://help.twitch.tv/s/article/languages-on-twitch#streamlang). The language value is \"other\" if the video was broadcast in a language not in the list of supported languages." }, "type": { "type": "string", "description": "The video's type. Possible values are: \n \n* archive — An on-demand video (VOD) of one of the broadcaster's past streams.\n* highlight — A highlight reel of one of the broadcaster's past streams. See [Creating Highlights](https://help.twitch.tv/s/article/creating-highlights-and-stream-markers).\n* upload — A video that the broadcaster uploaded to their video library. See Upload under [Video Producer](https://help.twitch.tv/s/article/video-on-demand?language=en%5FUS#videoproducer).", "enum": [ "archive", "highlight", "upload" ] }, "duration": { "type": "string", "description": "The video's length in ISO 8601 duration format. For example, 3m21s represents 3 minutes, 21 seconds." }, "muted_segments": { "type": "array", "description": "The segments that Twitch Audio Recognition muted; otherwise, **null**.", "items": { "type": "object", "required": [ "duration", "offset" ], "properties": { "duration": { "type": "integer", "description": "The duration of the muted segment, in seconds.", "format": "int32" }, "offset": { "type": "integer", "description": "The offset, in seconds, from the beginning of the video to where the muted segment begins.", "format": "int32" } } }, "nullable": true } } }, "GetVideosResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "The list of published videos that match the filter criteria.", "items": { "$ref": "#/components/schemas/Video" } }, "pagination": { "description": "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](https://dev.twitch.tv/docs/api/guide#pagination)", "type": "object", "properties": { "cursor": { "type": "string", "description": "The cursor used to get the next 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 through the results." } } } } }, "DeleteVideosResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "The list of IDs of the videos that were deleted.", "items": { "type": "string" } } } }, "SendWhisperBody": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "The whisper message to send. The message must not be empty. \n \nThe maximum message lengths are: \n \n* 500 characters if the user you're sending the message to hasn't whispered you before.\n* 10,000 characters if the user you're sending the message to has whispered you before.\n \nMessages that exceed the maximum length are truncated." } } } }, "securitySchemes": { "twitch_auth": { "type": "oauth2", "flows": { "implicit": { "authorizationUrl": "https://id.twitch.tv/oauth2/authorize", "refreshUrl": "https://id.twitch.tv/oauth2/token", "scopes": { "analytics:read:extensions": "View analytics data for the Twitch Extensions owned by the authenticated account.", "analytics:read:games": "View analytics data for the games owned by the authenticated account.", "bits:read": "View Bits information for a channel.", "channel:bot": "Joins your channel’s chatroom as a bot user, and perform chat-related actions as that user.", "channel:manage:ads": "Manage ads schedule on a channel.", "channel:read:ads": "Read the ads schedule and details on your channel.", "channel:manage:broadcast": "Manage a channel’s broadcast configuration, including updating channel configuration and managing stream markers and stream tags.", "channel:read:charity": "Read charity campaign details and user donations on your channel.", "channel:manage:clips": "Manage Clips for a channel.", "channel:edit:commercial": "Run commercials on a channel.", "channel:read:editors": "View a list of users with the editor role for a channel.", "channel:manage:extensions": "Manage a channel’s Extension configuration, including activating Extensions.", "channel:read:goals": "View Creator Goals for a channel.", "channel:read:guest_star": "Read Guest Star details for your channel.", "channel:manage:guest_star": "Manage Guest Star for your channel.", "channel:read:hype_train": "View Hype Train information for a channel.", "channel:manage:moderators": "Add or remove the moderator role from users in your channel.", "channel:read:polls": "View a channel’s polls.", "channel:manage:polls": "Manage a channel’s polls.", "channel:read:predictions": "View a channel’s Channel Points Predictions.", "channel:manage:predictions": "Manage of channel’s Channel Points Predictions", "channel:manage:raids": "Manage a channel raiding another channel.", "channel:read:redemptions": "View Channel Points custom rewards and their redemptions on a channel.", "channel:manage:redemptions": "Manage Channel Points custom rewards and their redemptions on a channel.", "channel:manage:schedule": "Manage a channel’s stream schedule.", "channel:read:stream_key": "View an authorized user’s stream key.", "channel:read:subscriptions": "View a list of all subscribers to a channel and check if a user is subscribed to a channel.", "channel:manage:videos": "Manage a channel’s videos, including deleting videos.", "channel:read:vips": "Read the list of VIPs in your channel.", "channel:manage:vips": "Add or remove the VIP role from users in your channel.", "channel:moderate": "Perform moderation actions in a channel.", "clips:edit": "Manage Clips for a channel.", "editor:manage:clips": "Manage Clips as an editor.", "moderation:read": "View a channel’s moderation data including Moderators, Bans, Timeouts, and Automod settings.", "moderator:manage:announcements": "Send announcements in channels where you have the moderator role.", "moderator:manage:automod": "Manage messages held for review by AutoMod in channels where you are a moderator.", "moderator:read:automod_settings": "View a broadcaster’s AutoMod settings.", "moderator:manage:automod_settings": "Manage a broadcaster’s AutoMod settings.", "moderator:read:banned_users": "Read the list of bans or unbans in channels where you have the moderator role.", "moderator:manage:banned_users": "Ban and unban users.", "moderator:read:blocked_terms": "View a broadcaster’s list of blocked terms.", "moderator:read:chat_messages": "Read deleted chat messages in channels where you have the moderator role.", "moderator:manage:blocked_terms": "Manage a broadcaster’s list of blocked terms.", "moderator:manage:chat_messages": "Delete chat messages in channels where you have the moderator role", "moderator:read:chat_settings": "View a broadcaster’s chat room settings.", "moderator:manage:chat_settings": "Manage a broadcaster’s chat room settings.", "moderator:read:chatters": "View the chatters in a broadcaster’s chat room.", "moderator:read:followers": "Read the followers of a broadcaster.", "moderator:read:guest_star": "Read Guest Star details for channels where you are a Guest Star moderator.", "moderator:manage:guest_star": "Manage Guest Star for channels where you are a Guest Star moderator.", "moderator:read:moderators": "Read the list of moderators in channels where you have the moderator role.", "moderator:read:shield_mode": "View a broadcaster’s Shield Mode status.", "moderator:manage:shield_mode": "Manage a broadcaster’s Shield Mode status.", "moderator:read:shoutouts": "View a broadcaster’s shoutouts.", "moderator:manage:shoutouts": "Manage a broadcaster’s shoutouts.", "moderator:read:suspicious_users": "Read chat messages from suspicious users and see users flagged as suspicious in channels where the user has the moderator role.", "moderator:manage:suspicious_users": "Manage suspicious user statuses in channels where the user has the moderator role.", "moderator:read:unban_requests": "View a broadcaster’s unban requests.", "moderator:manage:unban_requests": "Manage a broadcaster’s unban requests.", "moderator:read:vips": "Read the list of VIPs in channels where you have the moderator role.", "moderator:read:warnings": "Read warnings in channels where you have the moderator role.", "moderator:manage:warnings": "Warn users in channels where you have the moderator role.", "user:bot": "Join a specified chat channel as your user and appear as a bot, and perform chat-related actions as your user.", "user:edit": "Manage a user object.", "user:edit:broadcast": "View and edit a user’s broadcasting configuration, including Extension configurations.", "user:read:blocked_users": "View the block list of a user.", "user:manage:blocked_users": "Manage the block list of a user.", "user:read:broadcast": "View a user’s broadcasting configuration, including Extension configurations.", "user:read:chat": "Receive chatroom messages and informational notifications relating to a channel’s chatroom.", "user:manage:chat_color": "Update the color used for the user’s name in chat.", "user:read:email": "View a user’s email address.", "user:read:emotes": "View emotes available to a user", "user:read:follows": "View the list of channels a user follows.", "user:read:moderated_channels": "Read the list of channels you have moderator privileges in.", "user:read:subscriptions": "View if an authorized user is subscribed to specific channels.", "user:read:whispers": "Receive whispers sent to your user.", "user:manage:whispers": "Receive whispers sent to your user, and send whispers on your user’s behalf.", "user:write:chat": "Send chat messages to a chatroom.", "chat:edit": "Send chat messages to a chatroom using an IRC connection.", "chat:read": "View chat messages sent in a chatroom using an IRC connection.", "whispers:read": "Receive whisper messages for your user using PubSub." } } } } } } }