Contents

Channels Reference

While you can migrate from v3 to v5, know that v5 is deprecated and will be shutdown in the future. We prefer that you migrated directly to the new Twitch API.

Endpoint Description
Get Channel

Gets a channel object based on the OAuth token provided.

Get Channel returns more data than Get Channel by ID because Get Channel is privileged.
Get Channel by ID

Gets a specified channel object.
Update Channel

Updates specified properties of a specified channel.

In the request, the new properties can be specified as a JSON object or a form-encoded representation.
Get Channel Editors

Gets a list of users who are editors for a specified channel.
Get Channel Followers

Gets a list of users who follow a specified channel, sorted by the date when they started following the channel (newest first, unless specified otherwise).
Get Channel Teams

Gets a list of teams to which a specified channel belongs.
Get Channel Subscribers

Gets a list of users subscribed to a specified channel, sorted by the date when they subscribed.
Check Channel Subscription by User

Checks if a specified channel has a specified user subscribed to it. Intended for use by channel owners.

Returns a subscription object which includes the user if that user is subscribed. Requires authentication for the channel.
Get Channel Videos

Gets a list of VODs (Video on Demand) from a specified channel.
Start Channel Commercial

Starts a commercial (advertisement) on a specified channel. This is valid only for channels that are Twitch partners. You cannot start a commercial more often than once every 8 minutes.

There is an error response (422 Unprocessable Entity) if an invalid length is specified, an attempt is made to start a commercial less than 8 minutes after the previous commercial, or the specified channel is not a Twitch partner.
Reset Channel Stream Key

Deletes the stream key for a specified channel. Once it is deleted, the stream key is automatically reset.

A stream key (also known as authorization key) uniquely identifies a stream. Each broadcast uses an RTMP URL that includes the stream key. Stream keys are assigned by Twitch.
Get Channel Communities

Gets the communities for a specified channel.

Note: This replaces the deprecated endpoint Get Channel Community.
Set Channel Communities

Sets a specified channel to be in up to three specified communities.

Note: This replaces the deprecated endpoint Set Channel Community.
Delete Channel from Communities

Deletes a specified channel from its communities.

Note: This replaces the deprecated Delete Channel from Community.

Get Channel

✎

Gets a channel object based on a specified OAuth token.

Get Channel returns more data than Get Channel by ID because Get Channel is privileged.

Authentication

Required scope: channel_read

URL

GET https://api.twitch.tv/kraken/channel

Optional Query String Parameters

None

Example Request

This returns the channel object associated with OAuth token cfabdegwdoklmawdzdo98xt2fo512y.

curl -H 'Accept: application/vnd.twitchtv.v5+json' \ -H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \ -H 'Authorization: OAuth cfabdegwdoklmawdzdo98xt2fo512y' \ -X GET 'https://api.twitch.tv/kraken/channel'

Example Response

{
    "mature": true,
    "status": "Struggle Bus 5: The Fight to Stay Alive",
    "broadcaster_language": "en",
    "display_name": "dallas",
    "game": "Nioh",
    "language": "en",
    "_id": "44322889",
    "name": "dallas",
    "created_at": "2013-06-03T19:12:02Z",
    "updated_at": "2017-04-24T10:03:34Z",
    "partner": false,
    "logo": "https://static-cdn.jtvnw.net/jtv_user_pictures/dallas-profile_image-1a2c906ee2c35f12-300x300.png",
    "video_banner": "https://static-cdn.jtvnw.net/jtv_user_pictures/dallas-channel_offline_image-2e82c1df2a464df7-1920x1080.jpeg",
    "profile_banner": null,
    "profile_banner_background_color": null,
    "url": "https://www.twitch.tv/dallas",
    "views": 2000,
    "followers": 79,
    "broadcaster_type": "affiliate",
    "stream_key": "live_44322889_a34ub37c8ajv98a0",
    "email": "email@provider.com"
}

Get Channel by ID

✎

Gets a specified channel object.

Authentication

None

URL

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

Optional Query String Parameters

None

Example Request

This returns the object for channel 44322889.

curl -H 'Accept: application/vnd.twitchtv.v5+json' \
-H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-X GET 'https://api.twitch.tv/kraken/channels/44322889'

Example Response

{
    "_id": 44322889,
    "broadcaster_language": "en",
    "created_at": "2013-06-03T19:12:02Z",
    "display_name": "dallas",
    "followers": 40,
    "game": "Final Fantasy XV",
    "language": "en",
    "logo": "https://static-cdn.jtvnw.net/jtv_user_pictures/dallas-profile_image-1a2c906ee2c35f12-300x300.png",
    "mature": true,
    "name": "dallas",
    "partner": false,
    "profile_banner": null,
    "profile_banner_background_color": null,
    "status": "The Finalest of Fantasies",
    "updated_at": "2016-12-06T22:02:05Z",
    "url": "https://www.twitch.tv/dallas",
    "video_banner": null,
    "views": 232
}

Update Channel

✎

Updates specified properties of a specified channel.

In the request, the new properties are specified as a JSON object or a form-encoded representation.

Authentication

Required scope:

  • To update delay or channel_feed_enabled parameter: a channel_editor token from the channel owner
  • To update other parameters: channel_editor

URL

PUT https://api.twitch.tv/kraken/channels/

Parameters

At least one parameter must be specified:

Name Type Description
status string Description of the broadcaster’s status, displayed as a title on the channel page.
game string Name of game.
delay string Channel delay, in seconds. This inserts a delay in the live feed. Requires the channel owner’s OAuth token.
channel_feed_enabled boolean If true, the channel’s feed is turned on. Requires the channel owner’s OAuth token. Default: false.

Example Request with a JSON Object

This sets the status, game, and enables the channel feed of channel 44322889.

curl -H 'Accept: application/vnd.twitchtv.v5+json' \
-H 'Authorization: OAuth cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Content-Type: application/json' \
-d '{"channel": {"status": "The Finalest of Fantasies", "game": "Final Fantasy XV", "channel_feed_enabled": true}}' \
-X PUT 'https://api.twitch.tv/v5/channels/44322889'

Example Request with a Form-Encoded Body

This sets the status, game, and enables the channel feed of channel 44322889.

curl -H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \ -H 'Accept: application/vnd.twitchtv.v5+json' \ -H 'Authorization: OAuth cfabdegwdoklmawdzdo98xt2fo512y' \ -d 'channel[status]=The+Finalest+of+Fantasies&channel[game]=Final+Fantasy+XV&channel[channel_feed_enabled]=false' \ -X PUT 'https://api.twitch.tv/kraken/channels/44322889'

Example Response

{
   "_id": 44322889,
   "broadcaster_language": "en",
   "created_at": "2013-06-03T19:12:02Z",
   "display_name": "dallas",
   "followers": 40,
   "game": "Final Fantasy XV",
   "language": "en",
   "logo": "https://static-cdn.jtvnw.net/jtv_user_pictures/dallas-profile_image-1a2c906ee2c35f12-300x300.png",
   "mature": true,
   "name": "dallas",
   "partner": false,
   "profile_banner": null,
   "profile_banner_background_color": null,
   "status": "The Finalest of Fantasies",
   "updated_at": "2016-12-08T15:57:55Z",
   "url": "https://www.twitch.tv/dallas",
   "video_banner": null,
   "views": 248
}

Get Channel Editors

✎

Gets a list of users who are editors for a specified channel.

Authentication

Required scope: channel_read

URL

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

Optional Query String Parameters

None

Example Request

This gets a list of the users who are editors of channel 44322889.

curl -H 'Accept: application/vnd.twitchtv.v5+json' \
-H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Authorization: OAuth cfabdegwdoklmawdzdo98xt2fo512y' \
-X GET 'https://api.twitch.tv/kraken/channels/44322889/editors'

Example Response

{
    "users": [
        {
            "_id": 129454141,
            "bio": null,
            "created_at": "2016-07-13T14:40:42Z",
            "display_name": "dallasnchains",
            "logo": null,
            "name": "dallasnchains",
            "type": "user",
            "updated_at": "2016-12-09T22:02:56Z"
        }
    ]
}

Get Channel Followers

✎

Gets a list of users who follow a specified channel, sorted by the date when they started following the channel (newest first, unless specified otherwise).

Authentication

None

URL

GET https://api.twitch.tv/kraken/channels//follows

Optional Query String Parameters

Name Type Description
limit integer Maximum number of objects to return. Default: 25. Maximum: 100.
offset integer Object offset for pagination of results. Default: 0.
cursor string Tells the server where to start fetching the next set of results, in a multi-page response.
direction string Direction of sorting. Valid values: asc, desc (newest first). Default: desc.

Example Request

This gets a list of up to 25 users who have followed channel 44322889 most recently.

```bash curl -H ‘Accept: application/vnd.twitchtv.v5+json’ \ -H ‘Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2’ \ -X GET ‘https://api.twitch.tv/kraken/channels/44322889/follows’


### Example Response

```json
{
   "_cursor": "1481675542963907000",
   "_total": 41,
   "follows": [{
      "created_at": "2016-12-14T00:32:22.963907Z",
      "notifications": false,
      "user": {
            "_id": "129454141",
            "bio": null,
            "created_at": "2016-07-13T14:40:42.398257Z",
            "display_name": "dallasnchains",
            "logo": null,
            "name": "dallasnchains",
            "type": "user",
            "updated_at": "2016-12-14T00:32:16.263122Z"
      }
   },
   ...
   ]
}

Get Channel Teams

✎

Gets a list of teams to which a specified channel belongs.

Authentication

None

URL

GET https://api.twitch.tv/kraken/channels//teams

Optional Query String Parameters

None

Example Request

This gets a list of all teams to which channel 44322889 belongs.

curl -H 'Accept: application/vnd.twitchtv.v5+json' \
-H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-X GET 'https://api.twitch.tv/kraken/channels/44322889/teams'

Example Response

{
   "teams": [{
      "_id": 10,
      "background": null,
      "banner": "https://static-cdn.jtvnw.net/jtv_user_pictures/team-staff-banner_image-606ff5977f7dc36e-640x125.png",
      "created_at": "2011-10-25T23:55:47Z",
      "display_name": "Twitch Staff",
      "info": "Twitch staff stream here. Drop in and say \"hi\" sometime :)",
      "logo": "https://static-cdn.jtvnw.net/jtv_user_pictures/team-staff-team_logo_image-76418c0c93a9d48b-300x300.png",
      "name": "staff",
      "updated_at": "2014-10-16T00:44:11Z"
   }]
}

Get Channel Subscribers

✎

Gets a list of users subscribed to a specified channel, sorted by the date when they subscribed.

Authentication

Required scope: channel_subscriptions

URL

GET https://api.twitch.tv/kraken/channels//subscriptions

Optional Query String Parameters

Name Type Description
limit integer Maximum number of objects to return. Default: 25. Maximum: 100.
offset integer Object offset for pagination of results. Default: 0.
direction string Sorting direction. Valid values: asc, desc. Default: asc (oldest first).

Example Request

This gets a list of up to 25 users who subscribed to channel 129454141 most recently.

curl -H 'Accept: application/vnd.twitchtv.v5+json' \ -H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \ -H 'Authorization: OAuth cfabdegwdoklmawdzdo98xt2fo512y' \ -X GET 'https://api.twitch.tv/kraken/channels/129454141/subscriptions'

Example Response

{
    "_total": 4,
    "subscriptions": [
        {
            "_id": "e5e2ddc37e74aa9636625e8d2cc2e54648a30418",
            "created_at": "2016-04-06T04:44:31Z",
            "sub_plan": "1000",
            "sub_plan_name": "Channel Subscription (mr_woodchuck)",
            "user": {
                "_id": "89614178",
                "bio": "Twitch staff member who is a heimerdinger main on the road to diamond.",
                "created_at": "2015-04-26T18:45:34Z",
                "display_name": "Mr_Woodchuck",
                "logo": "https://static-cdn.jtvnw.net/jtv_user_pictures/mr_woodchuck-profile_image-a8b10154f47942bc-300x300.jpeg",
                "name": "mr_woodchuck",
                "type": "staff",
                "updated_at": "2017-04-06T00:14:13Z"
            }
        },
    . . .
   ]
}

Check Channel Subscription by User

✎

Checks if a specified channel has a specified user subscribed to it. Intended for use by channel owners.

Returns a subscription object which includes the user if that user is subscribed. Requires authentication for the channel.

Authentication

Required scope: channel_check_subscription

URL

GET https://api.twitch.tv/kraken/channels//subscriptions/

Optional Query String Parameters

None

Example Request

This checks whether user 129454141 is subscribed to channel 13405587.

curl -H 'Accept: application/vnd.twitchtv.v5+json' \ -H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \ -H 'Authorization: OAuth cfabdegwdoklmawdzdo98xt2fo512y' \ -X GET 'https://api.twitch.tv/kraken/channels/129454141/subscriptions/13405587'

Example Response if the User is Subscribed to the Channel

{
    "_id": "8bded3af51046d2d365279fe92a976b6a4ceb006",
    "created_at": "2017-04-08T19:15:39Z",
    "sub_plan": "3000",
    "sub_plan_name": "Channel Subscription (mr_woodchuck) - $24.99 Sub",
    "user": {
        "_id": "13405587",
        "bio": "Software Engineer at Twitch and casual speedrunner. I play video games!",
        "created_at": "2010-06-27T05:33:45Z",
        "display_name": "TWW2",
        "logo": "https://static-cdn.jtvnw.net/jtv_user_pictures/tww2-profile_image-6af5324eddee1468-300x300.png",
        "name": "tww2",
        "type": "staff",
        "updated_at": "2017-04-06T03:31:55Z"
    }
}

Example Response if the User is Not Subscribed to the Channel

{
    "error": "Not Found",
    "message": "dallas has no subscriptions to dallasnchains",
    "status": 404
}

Get Channel Videos

✎

Gets a list of VODs (Video on Demand) from a specified channel.

Authentication

None

URL

GET https://api.twitch.tv/kraken/channels//videos

Optional Query String Parameters

Name Type Description
limit integer Maximum number of objects to return. Default: 10. Maximum: 100.
offset integer Object offset for pagination of results. Default: 0.
broadcast_type comma-separated list Constrains the type of videos returned. Valid values: (any combination of) archive, highlight, upload. Default: all types (no filter).
language comma-separated list Constrains the language of the videos that are returned; for example, en,es. Default: all languages.
sort string Sorting order of the returned objects. Valid values: views, time. Default: time (most recent first).

Example Request

This gets the 10 most recent videos (of any broadcast type) from channel 44322889.

curl -H 'Accept: application/vnd.twitchtv.v5+json' \ -H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \ -X GET 'https://api.twitch.tv/kraken/channels/44322889/videos'

Example Response

{
   "_total": 583,
   "videos": [{
      "_id": "v102381501",
      "broadcast_id": 23711574096,
      "broadcast_type": "highlight",
      "channel": {
            "_id": "20694610",
            "display_name": "Towelliee",
            "name": "towelliee"
      },
      "created_at": "2016-11-20T23:46:06Z",
      "description": "Last minutes of stream",
      "description_html": "Last minutes of stream
",
      "fps": {
         "chunked": 59.9997939597903,
         "high": 30.2491085172346,
         "low": 30.249192959941,
         "medium": 30.2491085172346,
         "mobile": 30.249192959941
      },
      "game": "World of Warcraft",
      "language": "en",
      "length": 201,
      "preview": {
         "large": "https://static-cdn.jtvnw.net/s3_vods/664fa5856b_towelliee_23711574096_550644271//thumb/thumb102381501-640x360.jpg",
         "medium": "https://static-cdn.jtvnw.net/s3_vods/664fa5856b_towelliee_23711574096_550644271//thumb/thumb102381501-320x180.jpg",
         "small": "https://static-cdn.jtvnw.net/s3_vods/664fa5856b_towelliee_23711574096_550644271//thumb/thumb102381501-80x45.jpg",
         "template": "https://static-cdn.jtvnw.net/s3_vods/664fa5856b_towelliee_23711574096_550644271//thumb/thumb102381501-{width}x{height}.jpg"
      },
      "published_at": "2016-11-20T23:46:06Z",
      "resolutions": {
         "chunked": "1920x1080",
         "high": "1280x720",
         "low": "640x360",
         "medium": "852x480",
         "mobile": "400x226"
      },
      "status": "recorded",
      "tag_list": "",
      "thumbnails": {
            "large": [{
               "type": "generated",
               "url": "https://static-cdn.jtvnw.net/s3_vods/664fa5856b_towelliee_23711574096_550644271//thumb/thumb102381501-640x360.jpg"
            }],
            "medium": [{
               "type": "generated",
               "url": "https://static-cdn.jtvnw.net/s3_vods/664fa5856b_towelliee_23711574096_550644271//thumb/thumb102381501-320x180.jpg"
            }],
            "small": [{
               "type": "generated",
               "url": "https://static-cdn.jtvnw.net/s3_vods/664fa5856b_towelliee_23711574096_550644271//thumb/thumb102381501-80x45.jpg"
            }],
            "template": [{
               "type": "generated",
               "url": "https://static-cdn.jtvnw.net/s3_vods/664fa5856b_towelliee_23711574096_550644271//thumb/thumb102381501-{width}x{height}.jpg"
            }]
      },
      "title": "Last minutes of stream",
      "url": "https://www.twitch.tv/towelliee/v/102381501",
      "viewable": "public",
      "viewable_at": null,
      "views": 1761
   },
   ...
   ]
}

Start Channel Commercial

✎

Starts a commercial (advertisement) on a specified channel. This is valid only for channels that are Twitch partners. You cannot start a commercial more often than once every 8 minutes.

The length of the commercial (in seconds) is specified in the request body, with a required length parameter. Valid values are 30, 60, 90, 120, 150, and 180.

There is an error response (422 Unprocessable Entity) if an invalid length is specified, an attempt is made to start a commercial less than 8 minutes after the previous commercial, or the specified channel is not a Twitch partner.

Authentication

Required scope: channel_commercial

URL

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

Optional Query String Parameters

None

Example Request

This starts a 30-second commercial on channel 44322889.

curl -H 'Accept: application/vnd.twitchtv.v5+json' \
-H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Authorization: OAuth cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Content-Type: application/json' \
-d '{"length": 30}' \
-X POST 'https://api.twitch.tv/kraken/channels/44322889/commercial'

Example Response

{
   "Length": 30,
   "Message": "",
   "RetryAfter": 480
}

Reset Channel Stream Key

✎

Deletes the stream key for a specified channel. Once it is deleted, the stream key is automatically reset.

A stream key (also known as authorization key) uniquely identifies a stream. Each broadcast uses an RTMP URL that includes the stream key. Stream keys are assigned by Twitch.

Authentication

Required scope: channel_stream

URL

DELETE https://api.twitch.tv/kraken/channels//stream_key

Optional Query String Parameters

None

Example Request

This deletes (resets) the stream key for channel 44322889.

curl -H 'Accept: application/vnd.twitchtv.v5+json' \
-H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Authorization: OAuth cfabdegwdoklmawdzdo98xt2fo512y' \
-X DELETE 'https://api.twitch.tv/kraken/channels/44322889/stream_key'

Example Response

{
   "_id": 44322889,
   "broadcaster_language": "en",
   "created_at": "2013-06-03T19:12:02Z",
   "display_name": "dallas",
   "email": "dttester@twitch.tv",
   "followers": 42,
   "game": "Final Fantasy XV",
   "language": "en",
   "logo": "https://static-cdn.jtvnw.net/jtv_user_pictures/dallas-profile_image-1a2c906ee2c35f12-300x300.png",
   "mature": true,
   "name": "dallas",
   "partner": false,
   "profile_banner": null,
   "profile_banner_background_color": null,
   "status": "The Finalest of Fantasies",
   "stream_key": "live_44322889_nCGwsCl38pt21oj4UJJZbFQ9nrVIU5",
   "updated_at": "2016-12-14T18:32:07Z",
   "url": "https://www.twitch.tv/dallas",
   "video_banner": null,
   "views": 315
}

Get Channel Communities

✎

Gets the communities for a specified channel.

Note: This replaces the deprecated endpoint Get Channel Community.

Authentication

None

URL

GET https://api.twitch.tv/kraken/channels//communities

Optional Query String Parameters

None

Example Request

This gets the communities for channel 44322889.

curl -H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-X GET 'https://api.twitch.tv/v5/channels/44322889/communities'

Example Response

{
   "communities": [
      {
         "_id": "e9f17055-810f-4736-ba40-fba4ac541caa",
         "owner_id": "44322889",
         "name": "DallasTesterCommunity",
         "display_name": "Dallas Tester Community",
         "avatar_image_url": "",
         "cover_image_url": "",
	   "description": "# A Dedicated Tester Community.",
         "description_html": "
A Dedicated Tester Community.
\n",
         "rules": "1. Follow the Twitch Rules of Conduct to the letter. 2. Be kind! 3. Respect other humans. 4. Include everyone.",
         "rules_html": "
    \n
  1. Follow the Twitch Rules of Conduct to the letter. 2. Be kind! 3. Respect other humans. 4. Include everyone.
    2. \n
\n",
         "language": "EN",
         "summary": "A community for Dallas Tester or a tester community in Dallas?"
      },
      {
         "_id": "de0e756b-0ac0-4437-a800-d883546d82ec",
         "owner_id": "6316121",
         "name": "seventoes-test-community",
         "display_name": "Seventoes-Test-Community",
         "summary": "hi lol?",
         "description": "suh dude",
         "description_html": "suh dude
",
         "rules": "- suuuh dude",
         "rules_html": "
    \n
  • suuuh dude
    • \n
\n",
         "language": "EN",
         "avatar_image_url": "",
         "cover_image_url":    "https://static-cdn.jtvnw.net/community-images/de0e756b-0ac0-4437-a800-d883546d82ec/690e3c36-ef1c-47d4-89eb-92a11f8e3f89-1200x180.png"
      }
   ]
}

Set Channel Communities

✎

Sets a specified channel to be in up to three specified communities. The list of community IDs is specified in the body of the request.

Note: This replaces the deprecated endpoint Set Channel Community.

Authentication

Required scope: channel_editor

URL

PUT https://api.twitch.tv/kraken/channels//communities

Optional Query String Parameters

None

Example Request

This sets channel 44322889 to be in communities e9f17055-810f-4736-ba40-fba4ac541caa and de0e756b-0ac0-4437-a800-d883546d82ec.

curl -H 'Authorization: OAuth cfabdegwdoklmawdzdo98xt2fo512y' \ -H 'Accept: application/vnd.twitchtv.v5+json' \ -H 'Content-Type: application/json' \ -X PUT 'https://api.twitch.tv/kraken/channels/44322889/communities' \ -d '{"community_ids":["e9f17055-810f-4736-ba40-fba4ac541caa", "de0e756b-0ac0-4437-a800-d883546d82ec"]}

Example Response

204 No Content

Delete Channel from Communities

✎

Deletes a specified channel from its communities.

Note: This replaces the deprecated Delete Channel from Community.

Authentication

None

URL

DELETE https://api.twitch.tv/kraken/channels//community

Optional Query String Parameters

None

Example Request

This deletes channel 44322889 from its communities.

curl -H 'Authorization: OAuth cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Accept: application/vnd.twitchtv.v5+json' \
-X DELETE 'https://api.twitch.tv/kraken/channels/44322889/community'

Example Response

204 No Content
+
Docs Status Support Showcase Blog