Communities

Endpoint Description
Get Community by Name Gets a specified community.

The name of the community is specified in a required query-string parameter. It must be 3-25 characters.
Get Community by ID Gets a specified community.
Update Community Updates a specified community.
Get Top Communities Gets the top communities by viewer count.
Get Community Banned Users Gets a list of banned users for a specified community.
Ban Community User Adds a specified user to the ban list of a specified community.
Un-Ban Community User Deletes a specified user from the ban list of a specified community.
Create Community Avatar Image Adds a specified image as the avatar of a specified community.
Delete Community Avatar Image Deletes the avatar image of a specified community.
Create Community Cover Image Adds a specified image as the cover image of a specified community.
Delete Community Cover Image Deletes the cover image of a specified community.
Get Community Moderators Gets a list of moderators of a specified community.
Add Community Moderator Adds a specified user to the list of moderators of a specified community.
Delete Community Moderator Deletes a specified user from the list of moderators of a specified community.
Get Community Permissions Gets a list of actions users can perform in a specified community.
Report Community Violation Reports a specified channel for violating the rules of a specified community.
Get Community Timed-Out Users Gets a list of users who are timed out in a specified community.
Add Community Timed-Out User Adds a specified user to the timeout list of a specified community.
Delete Community Timed-Out User Deletes a specified user from the timeout list of a specified community.

Get Community by Name

Gets a specified community.

The name of the community is specified in a required query-string parameter. It must be 3-25 characters.

Authentication

None

URL

GET https://api.twitch.tv/kraken/communities?name=<community name>

Optional Query String Parameters

None

Example Request

This gets the DallasTesterCommunity community.

1
2
3
curl -H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Accept: application/vnd.twitchtv.v5+json' \
-X GET 'https://api.twitch.tv/kraken/communities?name=DallasTesterCommunity'

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
{
   "_id": "e9f17055-810f-4736-ba40-fba4ac541caa",
   "avatar_image_url": "",
   "cover_image_url": "",
   "description": "# A Dedicated Tester Community.",
   "description_html": "<h3>A Dedicated Tester Community.</h3>\n",
   "language": "EN",
   "name": "DallasTesterCommunity",
   "owner_id": "44322889",
   "rules": "1. Follow the Twitch Rules of Conduct to the letter. 2. Be kind! 3. Respect other humans. 4. Include everyone.",
   "rules_html": "<ol>\n<li>Follow the Twitch Rules of Conduct to the letter. 2. Be kind! 3. Respect other humans. 4. Include everyone.<br></li>\n</ol>\n",
   "summary": "A community for Dallas Tester or a tester community in Dallas?"
}

Get Community by ID

Gets a specified community.

Authentication

None

URL

GET https://api.twitch.tv/kraken/communities/<community ID>

Optional Query String Parameters

None

Example Request

This gets community e9f17055-810f-4736-ba40-fba4ac541caa.

1
2
3
curl -H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Accept: application/vnd.twitchtv.v5+json' \
-X GET 'https://api.twitch.tv/kraken/communities/e9f17055-810f-4736-ba40-fba4ac541caa'

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
{
   "_id": "e9f17055-810f-4736-ba40-fba4ac541caa",
   "owner_id": "44322889",
   "name": "DallasTesterCommunity",
   "summary": "A community for Dallas Tester or a tester community in Dallas?",
   "description": "# A Dedicated Tester Community.",
   "description_html": "\u003ch3\u003eA Dedicated Tester Community.\u003c/h3\u003e\n",
   "rules": "1. Follow the Twitch Rules of Conduct to the letter. 2. Be kind! 3. Respect other humans. 4. Include everyone.",
   "rules_html": "\u003col\u003e\n\u003cli\u003eFollow the Twitch Rules of Conduct to the letter. 2. Be kind! 3. Respect other humans. 4. Include everyone.\u003cbr\u003e\u003c/li\u003e\n\u003c/ol\u003e\n",
   "language": "EN",
   "avatar_image_url": "",
   "cover_image_url": ""
}

Update Community

Updates a specified community.

Authentication

Required scope: communities_edit

URL

PUT https://api.twitch.tv/kraken/communities/<community ID>

Optional Parameters in the Request Body

Name Type Description
summary string Short description of the community, shown in search results. Maximum: 160 characters.
description string Long description of the community, shown in the “about this community” box. Markdown syntax allowed. Maximum 1,572,864 characters (1.5 MB).
rules string Rules displayed when viewing a community page or searching for a community from the broadcaster dashboard. Markdown syntax allowed. Maximum 1,572,864 characters (1.5 MB)
email string Email address of the community owner.

Example Request

This updates the summary for community e9f17055-810f-4736-ba40-fba4ac541caa.

1
2
3
4
5
curl -H 'Authorization: OAuth cfabdegwdoklmawdzdo98xt2fo512y'\
-H 'Accept: application/vnd.twitchtv.v5+json' \
-H 'Content-Type: application/json' \
-d '{"summary": "A community for Dallas Tester or a tester community in Dallas?"}' \
-X PUT 'https://api.twitch.tv/kraken/communities/e9f17055-810f-4736-ba40-fba4ac541caa'

Example Response

1
204 No Content

Get Top Communities

Gets the top communities by viewer count.

Authentication

None

URL

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

Optional Query String Parameters

Name Type Description
limit long Maximum number of most-recent objects to return. Default: 10. Maximum: 100.
cursor string Tells the server where to start fetching the next set of results in a multi-page response.

Example Request

1
2
3
curl -H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Accept: application/vnd.twitchtv.v5+json' \
-X GET 'https://api.twitch.tv/kraken/communities/top'

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
   "_cursor": "MTA=",
   "_total": 100,
   "communities": [
      {
         "avatar_image_url": "https://static-cdn.jtvnw.net/twitch-community-images-production/defaults/avatar.png",
         "channels": 1,
         "id": "e9f17055-810f-4736-ba40-fba4ac541caa",
         "name": "DallasTesterCommunity",
         "viewers": 1
      },
      ...
   ]
}

Get Community Banned Users

Gets a list of banned users for a specified community.

Authentication

Required scope: communities_moderate

URL

GET https://api.twitch.tv/kraken/communities/<community ID>/bans

Optional Query String Parameters

Name Type Description
limit long Maximum number of most-recent objects to return. Default: 10. Maximum: 100.
cursor string Tells the server where to start fetching the next set of results in a multi-page response.

Example Request

This gets a list of banned users for community e9f17055-810f-4736-ba40-fba4ac541caa.

1
2
3
curl -H 'Authorization: OAuth cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Accept: application/vnd.twitchtv.v5+json' \
-X GET 'https://api.twitch.tv/kraken/communities/e9f17055-810f-4736-ba40-fba4ac541caa/bans'

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
{
   "_cursor": "",
   "banned_users": [
      {
         "user_id": "129454141",
         "display_name": "dallasnchains",
         "name": "dallasnchains",
         "bio": null,
         "avatar_image_url": null,
         "start_timestamp": 1486508223551
      }
   ]
}

Ban Community User

Adds a specified user to the ban list of a specified community.

Authentication

Required scope: communities_moderate

URL

PUT https://api.twitch.tv/kraken/communities/<community ID>/bans/<user ID>

Optional Query String Parameters

None

Example Request

This bans user 129454141 from community e9f17055-810f-4736-ba40-fba4ac541caa.

1
2
3
curl -H 'Authorization: OAuth cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Accept: application/vnd.twitchtv.v5+json' \
-X PUT 'https://api.twitch.tv/kraken/communities/e9f17055-810f-4736-ba40-fba4ac541caa/bans/129454141'

Example Response

1
204 No Content

Un-Ban Community User

Deletes a specified user from the ban list of a specified community.

Authentication

Required scope: communities_moderate

URL

DELETE https://api.twitch.tv/kraken/communities/<community ID>/bans/<user ID>

Optional Query String Parameters

None

Example Request

This un-bans user 129454141 from community e9f17055-810f-4736-ba40-fba4ac541caa.

1
2
3
curl -H 'Authorization: OAuth cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Accept: application/vnd.twitchtv.v5+json' \
-X DELETE 'https://api.twitch.tv/kraken/communities/e9f17055-810f-4736-ba40-fba4ac541caa/bans/129454141'

Example Response

1
204 No Content

Create Community Avatar Image

Adds a specified image as the avatar of a specified community.

Authentication

Required scope: communities_edit

URL

POST https://api.twitch.tv/kraken/communities/<community ID>/images/avatar

Required Parameter in the Request Body

Name Type Description
avatar_image string A base-64 encoded representation of the avatar image. Avatar images must be 600x800 pixels.

Example Request

This adds an avatar image for community e9f17055-810f-4736-ba40-fba4ac541caa. For readability, the avatar_image value is truncated here.

1
2
3
4
5
curl -H 'Authorization: OAuth cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Accept: application/vnd.twitchtv.v5+json' \
-H 'Content-Type: application/json' \
-d '{"avatar_image": "/9j/4AAQSkZJRgABAQEASABIAAD//gATQ3JlYXRlZCB3aXRoIEdJTVD/2wBDAP//////////////////////////////////////////////////////////////////////////////////////2wBDAf//////////////////////////////////////////////////////////////////////////////////////wgARCAMgAlgDAREAAhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAAAAL/xAAUAQEAAAAAAAAAAAAAAAAAAAAA/9oADAMBAAIQAxAAAAGgAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA..."}' \
-X POST 'https://api.twitch.tv/kraken/communities/e9f17055-810f-4736-ba40-fba4ac541caa/images/avatar'

Example Response

1
204 No Content

Delete Community Avatar Image

Deletes the avatar image of a specified community.

Authentication

Required scope: communities_edit

URL

DELETE https://api.twitch.tv/kraken/communities/<community ID>/images/avatar

Optional Query String Parameters

None

Example Request

This deletes the avatar image of community e9f17055-810f-4736-ba40-fba4ac541caa.

1
2
3
curl -H 'Authorization: OAuth cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Accept: application/vnd.twitchtv.v5+json' \
-X DELETE 'https://api.twitch.tv/kraken/communities/e9f17055-810f-4736-ba40-fba4ac541caa/images/avatar'

Example Response

1
204 No Content

Create Community Cover Image

Adds a specified image as the cover image of a specified community.

Authentication

Required scope: communities_edit

URL

POST https://api.twitch.tv/kraken/communities/<community ID>/images/cover

Required Parameter in the Request Body

Name Type Description
cover_image string A base-64 encoded representation of the cover image. Cover images must be 1200x180 pixels.

Example Request

This adds a cover image for community e9f17055-810f-4736-ba40-fba4ac541caa. For readability, the cover_image value is truncated here.

1
2
3
4
5
curl -H 'Authorization: OAuth cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Accept: application/vnd.twitchtv.v5+json' \
-H 'Content-Type: application/json' \
-d '{"cover_image": "/9j/4AAQSkZJRgABAQEASABIAAD//gATQ3JlYXRlZCB3aXRoIEdJTVD/2wBDAP//////////////////////////////////////////////////////////////////////////////////////2wBDAf//////////////////////////////////////////////////////////////////////////////////////wgARCAC0BLADAREAAhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAAAAL/xAAUAQEAAAAAAAAAAAAAAAAAAAAA/9oADAMBAAIQAxAAAAGgAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA..."}' \
-X POST 'https://api.twitch.tv/kraken/communities/e9f17055-810f-4736-ba40-fba4ac541caa/images/cover'

Example Response

1
204 No Content

Delete Community Cover Image

Deletes the cover image of a specified community.

Authentication

Required scope: communities_edit

URL

DELETE https://api.twitch.tv/kraken/communities/<community ID>/images/cover

Optional Query String Parameters

None

Example Request

This deletes the cover image of community e9f17055-810f-4736-ba40-fba4ac541caa.

1
2
3
curl -H 'Authorization: OAuth cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Accept: application/vnd.twitchtv.v5+json' \
-X DELETE 'https://api.twitch.tv/kraken/communities/e9f17055-810f-4736-ba40-fba4ac541caa/images/cover'

Example Response

1
204 No Content

Get Community Moderators

Gets a list of moderators of a specified community.

Authentication

Required scope: communities_edit

URL

GET https://api.twitch.tv/kraken/communities/<community ID>/moderators

Optional Query String Parameters

None

Example Request

This gets a list of moderators of community e9f17055-810f-4736-ba40-fba4ac541caa.

1
2
3
curl -H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Accept: application/vnd.twitchtv.v5+json' \
-X GET 'https://api.twitch.tv/kraken/communities/e9f17055-810f-4736-ba40-fba4ac541caa/moderators'

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
   "moderators": [
      {
         "display_name": "dallasnchains",
         "_id": "129454141",
         "name": "dallasnchains",
         "type": "user",
         "bio": null,
         "created_at": "2016-07-13T14:40:42.398257Z",
         "updated_at": "2017-02-04T14:32:38.626459Z",
         "logo": null
      }
   ]
}

Add Community Moderator

Adds a specified user to the list of moderators of a specified community.

Authentication

Required scope: communities_edit

URL

PUT https://api.twitch.tv/kraken/communities/<community ID>/moderators/<user ID>

Optional Query String Parameters

None

Example Request

This adds user 129454141 to the list of moderators of community e9f17055-810f-4736-ba40-fba4ac541caa.

1
2
3
curl -H 'Authorization: OAuth cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Accept: application/vnd.twitchtv.v5+json' \
-X PUT 'https://api.twitch.tv/kraken/communities/e9f17055-810f-4736-ba40-fba4ac541caa/moderators/129454141'

Example Response

1
204 No Content

Delete Community Moderator

Deletes a specified user from the list of moderators of a specified community.

Authentication

Required scope: communities_edit

URL

DELETE https://api.twitch.tv/kraken/communities/<community ID>/moderators/<user ID>

Optional Query String Parameters

None

Example Request

This deletes user 129454141 from the lists of moderators of community e9f17055-810f-4736-ba40-fba4ac541caa.

1
2
3
curl -H 'Authorization: OAuth cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Accept: application/vnd.twitchtv.v5+json' \
-X DELETE 'https://api.twitch.tv/kraken/communities/e9f17055-810f-4736-ba40-fba4ac541caa/moderators/129454141'

Example Response

1
204 No Content

Get Community Permissions

Gets a list of actions users can perform in a specified community.

Authentication

Required scope: any (an OAuth token for a Twitch user is required)

URL

GET https://api.twitch.tv/kraken/communities/<community ID>/permissions

Optional Query String Parameters

None

Example Request

This gets a list of the actions users can perform in community e9f17055-810f-4736-ba40-fba4ac541caa.

1
2
3
curl -H 'Authorization: OAuth cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Accept: application/vnd.twitchtv.v5+json' \
-X GET 'https://api.twitch.tv/kraken/communities/e9f17055-810f-4736-ba40-fba4ac541caa/permissions'

Example Response

1
2
3
4
5
{
   "ban": true,
   "timeout": true,
   "edit": true
}

Report Community Violation

Reports a specified channel for violating the rules of a specified community.

Authentication

None

URL

POST https://api.twitch.tv/kraken/communities/<community ID>/report_channel

Required Parameter in the Request Body

Name Type Description
channel_id string ID of the channel being reported.

Optional Query String Parameters

None

Example Request

This reports channel 44322889 for violating the rules of community e9f17055-810f-4736-ba40-fba4ac541caa.

1
2
3
4
5
curl -H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2'' \
-H 'Accept: application/vnd.twitchtv.v5+json' \
-H 'Content-Type: application/json' \
-d '{"channel_id": "44322889"}' \
-X POST 'https://api.twitch.tv/kraken/communities/e9f17055-810f-4736-ba40-fba4ac541caa/report_channel'

Example Response

1
204 No Content

Get Community Timed-Out Users

Gets a list of users who are timed out in a specified community.

Authentication

Required scope: communities_moderate

URL

GET https://api.twitch.tv/kraken/communities/<community ID>/timeouts

Optional Query String Parameters

Name Type Description
limit long Maximum number of most-recent objects to return. Default: 10. Maximum: 100.
cursor string Tells the server where to start fetching the next set of results in a multi-page response.

Example Request

This gets a list of timed-out users in community e9f17055-810f-4736-ba40-fba4ac541caa.

1
2
3
curl -H 'Authorization: OAuth cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Accept: application/vnd.twitchtv.v5+json' \
-X GET 'https://api.twitch.tv/kraken/communities/e9f17055-810f-4736-ba40-fba4ac541caa/timeouts'

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
   "_cursor": "",
   "timed_out_users": [
      {
         "user_id": "129454141",
         "display_name": "dallasnchains",
         "name": "dallasnchains",
         "bio": null,
         "avatar_image_url": null,
         "start_timestamp": 1486507986046,
         "end_timestamp": 1486515186000
      }
   ]
}

Add Community Timed-Out User

Adds a specified user to the timeout list of a specified community.

Authentication

Required scope: communities_moderate

URL

PUT https://api.twitch.tv/kraken/communities/<community ID>/timeouts/<user ID>

Required Parameter in the Request Body

Name Type Description
duration integer Length of the timeout, in hours.

Optional Parameter in the Request Body

Name Type Description
reason string Reason for the timeout.

Optional Query String Parameters

None

Example Request

This adds user 129454141 to the timeout list of community e9f17055-810f-4736-ba40-fba4ac541caa.

1
2
3
4
curl -H 'Authorization: OAuth cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Accept: application/vnd.twitchtv.v5+json' \
-d '{"duration": "1"}' \
-X PUT 'https://api.twitch.tv/kraken/communities/e9f17055-810f-4736-ba40-fba4ac541caa/timeouts/129454141'

Example Response

1
204 No Content

Delete Community Timed-Out User

Deletes a specified user from the timeout list of a specified community.

Authentication

Required scope: communities_moderate

URL

DELETE https://api.twitch.tv/kraken/communities/<community ID>/timeouts/<user ID>

Optional Query String Parameters

None

Example Request

This deletes user 129454141 from the timeout list of community e9f17055-810f-4736-ba40-fba4ac541caa.

1
2
3
curl -H 'Authorization: OAuth cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Accept: application/vnd.twitchtv.v5+json' \
-X DELETE 'https://api.twitch.tv/kraken/communities/e9f17055-810f-4736-ba40-fba4ac541caa/timeouts/129454141'

Example Response

1
204 No Content