Contents

Collections (of Videos) Reference

Endpoint Description
Get Collection Metadata

Gets summary information about a specified collection. This does not return the collection items (videos).

Get Collection

Gets all items (videos) in a specified collection. For each video in the collection, this returns a collection item ID and other information. Collection item IDs are unique (only) within the collection.

Get Collections by Channel

Gets all collections owned by a specified channel. Collections are sorted by update date, with the most recently updated first.

Create Collection

Creates a new collection owned by a specified channel. The user identified by the OAuth token must be the owner or an editor of the specified channel. The collection’s title is provided as a required parameter in the request body, in JSON format.

A collection is directly related to a channel: broadcasters can create a collection of videos only from their channels.

A user can own at most 100 collections.

Update Collection

Updates the title of a specified collection. The new title is provided as a required parameter in the request body, in JSON format.

Create Collection Thumbnail

Adds the thumbnail of a specified collection item as the thumbnail for the specified collection. The collection item – a video which must already be in the collection – is specified in a required parameter in the request body, in JSON format. The collection item is specified with a collection item ID returned by Get Collection.

Delete Collection

Deletes a specified collection.

Add Item to Collection

Adds a specified video to a specified collection. The video ID and type are specified as required parameters in the request body, in JSON format. The item ID is a video ID (not a collection item ID), and the type must be “video.”

Delete Item from Collection

Deletes a specified collection item from a specified collection, if it exists. The collection item is specified with a collection item ID returned by Get Collection.

Move Item within Collection

Moves a specified collection item to a different position within a collection. The collection item is specified with a collection item ID returned by Get Collection. The position is specified by a required parameter in the request body, in JSON format.

Get Collection Metadata

Gets summary information about a specified collection. This does not return the collection items (videos).

Authentication

None

URL

GET https://api.twitch.tv/kraken/collections/<collection ID>

Optional Query String Parameters

None

Example Request

This gets metadata about collection myIbIFkZphQSbQ.

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

Example Response

The total_duration value is the total duration (in seconds) of all videos in the collection.

{
  "_id": "myIbIFkZphQSbQ",
  "created_at": "2017-02-24T02:49:57.473Z",
  "items_count": 3,
  "owner": {
    "_id": "12826",
    "bio": "Twitch is the world's leading social video service and community for gamers. Each day, millions of community members gather to watch, talk, and chat about shared interests. Twitch's video service is the backbone of both live and on-demand distribution for all types of content, including the entire video game ecosystem, the creative arts, vlogging (IRL), and more. Twitch also runs TwitchCon, the annual convention for celebrating the Twitch community. For more information about Twitch, visit our Press Center, Twitter feed (#Twitch), and Blog.",
    "created_at": "2007-05-22T10:39:54.238271Z",
    "display_name": "Twitch",
    "logo": "https://static-cdn.jtvnw.net/jtv_user_pictures/twitch-profile_image-bd6df6672afc7497-300x300.png",
    "name": "twitch",
    "type": "user",
    "updated_at": "2017-03-07T21:32:16.72967Z"
  },
  "thumbnails": {
    "large": "https://static-cdn.jtvnw.net/s3_vods/1c3bca8ef3_twitch_24656853040_609723817//thumb/thumb125475622-640x360.jpg",
    "medium": "https://static-cdn.jtvnw.net/s3_vods/1c3bca8ef3_twitch_24656853040_609723817//thumb/thumb125475622-320x180.jpg",
    "small": "https://static-cdn.jtvnw.net/s3_vods/1c3bca8ef3_twitch_24656853040_609723817//thumb/thumb125475622-80x45.jpg",
    "template": "https://static-cdn.jtvnw.net/s3_vods/1c3bca8ef3_twitch_24656853040_609723817//thumb/thumb125475622-{width}x{height}.jpg"
  },
  "title": "Fanboys - LIVE every Tuesday at 1 pm PT ",
  "total_duration": 16307,
  "updated_at": "2017-03-06T18:40:51.855Z",
  "views": 0
}

Get Collection

Gets all items (videos) in a specified collection. For each video in the collection, this returns a collection item ID and other information. Collection item IDs are unique (only) within the collection.

Authentication

None

URL

GET https://api.twitch.tv/kraken/collections/<collection ID>/items

Optional Query String Parameter

Name Type Description
include_all_items boolean If true, unwatchable VODs (private and/or in-process) are included in the response. Default: false.

Example Request

This gets all videos in collection myIbIFkZphQSbQ.

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

Example Response

{
  "_id": "myIbIFkZphQSbQ",
  "items": [
    {
      "_id": "eyJ0eXBlIjoidmlkZW8iLCJpZCI6IjEyMjEzODk0OSJ9",
      "description_html": "",
      "duration": 4676,
      "game": "Talk Shows",
      "item_id": "122138949",
      "item_type": "video",
      "owner": {
        "_id": "12826",
        "bio": "Twitch is the world's leading social video service and community for gamers. Each day, millions of community members gather to watch, talk, and chat about shared interests. Twitch's video service is the backbone of both live and on-demand distribution for all types of content, including the entire video game ecosystem, the creative arts, vlogging (IRL), and more. Twitch also runs TwitchCon, the annual convention for celebrating the Twitch community. For more information about Twitch, visit our Press Center, Twitter feed (#Twitch), and Blog.",
        "created_at": "2007-05-22T10:39:54.238271Z",
        "display_name": "Twitch",
        "logo": "https://static-cdn.jtvnw.net/jtv_user_pictures/twitch-profile_image-bd6df6672afc7497-300x300.png",
        "name": "twitch",
        "type": "user",
        "updated_at": "2017-03-07T21:32:16.72967Z"
      },
      "published_at": "2017-02-14T22:27:54Z",
      "thumbnails": {
        "large": "https://static-cdn.jtvnw.net/s3_vods/71a4eda892_twitch_24529261280_601749333//thumb/thumb122138949-640x360.jpg",
        "medium": "https://static-cdn.jtvnw.net/s3_vods/71a4eda892_twitch_24529261280_601749333//thumb/thumb122138949-320x180.jpg",
        "small": "https://static-cdn.jtvnw.net/s3_vods/71a4eda892_twitch_24529261280_601749333//thumb/thumb122138949-80x45.jpg",
        "template": "https://static-cdn.jtvnw.net/s3_vods/71a4eda892_twitch_24529261280_601749333//thumb/thumb122138949-{width}x{height}.jpg"
      },
      "title": "Fanboys Episode 1 w/ Gassy Mexican",
      "views": 3142
    },
    {
      "_id": "eyJ0eXBlIjoidmlkZW8iLCJpZCI6IjEyMzgwMjczNSJ9",
      "description_html": "",
      "duration": 5537,
      "game": "Talk Shows",
      "item_id": "123802735",
      "item_type": "video",
      "owner": {
        "_id": "12826",
        "bio": "Twitch is the world's leading social video service and community for gamers. Each day, millions of community members gather to watch, talk, and chat about shared interests. Twitch's video service is the backbone of both live and on-demand distribution for all types of content, including the entire video game ecosystem, the creative arts, vlogging (IRL), and more. Twitch also runs TwitchCon, the annual convention for celebrating the Twitch community. For more information about Twitch, visit our Press Center, Twitter feed (#Twitch), and Blog.",
        "created_at": "2007-05-22T10:39:54.238271Z",
        "display_name": "Twitch",
        "logo": "https://static-cdn.jtvnw.net/jtv_user_pictures/twitch-profile_image-bd6df6672afc7497-300x300.png",
        "name": "twitch",
        "type": "user",
        "updated_at": "2017-03-07T21:32:16.72967Z"
      },
      "published_at": "2017-02-21T23:13:30Z",
      "thumbnails": {
        "large": "https://static-cdn.jtvnw.net/s3_vods/3826bd9c33_twitch_24593374112_605756384//thumb/thumb123802735-640x360.jpg",
        "medium": "https://static-cdn.jtvnw.net/s3_vods/3826bd9c33_twitch_24593374112_605756384//thumb/thumb123802735-320x180.jpg",
        "small": "https://static-cdn.jtvnw.net/s3_vods/3826bd9c33_twitch_24593374112_605756384//thumb/thumb123802735-80x45.jpg",
        "template": "https://static-cdn.jtvnw.net/s3_vods/3826bd9c33_twitch_24593374112_605756384//thumb/thumb123802735-{width}x{height}.jpg"
      },
      "title": "Fanboys Episode 2 w/ Reece Robbins",
      "views": 2130
    },
    {
      "_id": "eyJ0eXBlIjoidmlkZW8iLCJpZCI6IjEyNTQ3NTYyMiJ9",
      "description_html": "",
      "duration": 6094,
      "game": "Talk Shows",
      "item_id": "125475622",
      "item_type": "video",
      "owner": {
        "_id": "12826",
        "bio": "Twitch is the world's leading social video service and community for gamers. Each day, millions of community members gather to watch, talk, and chat about shared interests. Twitch's video service is the backbone of both live and on-demand distribution for all types of content, including the entire video game ecosystem, the creative arts, vlogging (IRL), and more. Twitch also runs TwitchCon, the annual convention for celebrating the Twitch community. For more information about Twitch, visit our Press Center, Twitter feed (#Twitch), and Blog.",
        "created_at": "2007-05-22T10:39:54.238271Z",
        "display_name": "Twitch",
        "logo": "https://static-cdn.jtvnw.net/jtv_user_pictures/twitch-profile_image-bd6df6672afc7497-300x300.png",
        "name": "twitch",
        "type": "user",
        "updated_at": "2017-03-07T21:32:16.72967Z"
      },
      "published_at": "2017-02-28T22:47:30Z",
      "thumbnails": {
        "large": "https://static-cdn.jtvnw.net/s3_vods/1c3bca8ef3_twitch_24656853040_609723817//thumb/thumb125475622-640x360.jpg",
        "medium": "https://static-cdn.jtvnw.net/s3_vods/1c3bca8ef3_twitch_24656853040_609723817//thumb/thumb125475622-320x180.jpg",
        "small": "https://static-cdn.jtvnw.net/s3_vods/1c3bca8ef3_twitch_24656853040_609723817//thumb/thumb125475622-80x45.jpg",
        "template": "https://static-cdn.jtvnw.net/s3_vods/1c3bca8ef3_twitch_24656853040_609723817//thumb/thumb125475622-{width}x{height}.jpg"
      },
      "title": "Fanboys Episode 3 w/ Ludi Lin and Ellohime",
      "views": 827
    }
  ]
}

Get Collections by Channel

Gets all collections owned by a specified channel. Collections are sorted by update date, with the most recently updated first.

Authentication

None

URL

GET https://api.twitch.tv/kraken/channels/<channel ID>/collections

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.
containing_item video:<video ID> Returns only collections containing the specified video. Note this uses a video ID, not a collection item ID. Example: video:89917098.

Example Request

This gets all collections owned by channel 12868.

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

Example Response

{
  "_cursor": null,
  "collections": [
    {
      "_id": "myIbIFkZphQSbQ",
      "created_at": "2017-02-24T02:49:57.473Z",
      "items_count": 3,
      "owner": {
        "_id": "12826",
        "bio": "Twitch is the world's leading social video service and community for gamers. Each day, millions of community members gather to watch, talk, and chat about shared interests. Twitch's video service is the backbone of both live and on-demand distribution for all types of content, including the entire video game ecosystem, the creative arts, vlogging (IRL), and more. Twitch also runs TwitchCon, the annual convention for celebrating the Twitch community. For more information about Twitch, visit our Press Center, Twitter feed (#Twitch), and Blog.",
        "created_at": "2007-05-22T10:39:54.238271Z",
        "display_name": "Twitch",
        "logo": "https://static-cdn.jtvnw.net/jtv_user_pictures/twitch-profile_image-bd6df6672afc7497-300x300.png",
        "name": "twitch",
        "type": "user",
        "updated_at": "2017-03-07T21:05:28.166073Z"
      },
      "thumbnails": {
        "large": "https://static-cdn.jtvnw.net/s3_vods/1c3bca8ef3_twitch_24656853040_609723817//thumb/thumb125475622-640x360.jpg",
        "medium": "https://static-cdn.jtvnw.net/s3_vods/1c3bca8ef3_twitch_24656853040_609723817//thumb/thumb125475622-320x180.jpg",
        "small": "https://static-cdn.jtvnw.net/s3_vods/1c3bca8ef3_twitch_24656853040_609723817//thumb/thumb125475622-80x45.jpg",
        "template": "https://static-cdn.jtvnw.net/s3_vods/1c3bca8ef3_twitch_24656853040_609723817//thumb/thumb125475622-{width}x{height}.jpg"
      },
      "title": "Fanboys - LIVE every Tuesday at 1 pm PT ",
      "total_duration": 16307,
      "updated_at": "2017-03-06T18:40:51.855Z",
      "views": 0
    }
  ]
}

Create Collection

Creates a new collection owned by a specified channel. The user identified by the OAuth token must be the owner or an editor of the specified channel. The collection’s title is provided as a required parameter in the request body, in JSON format.

A collection is directly related to a channel: broadcasters can create a collection of videos only from their channels.

A user can own at most 100 collections.

Authentication

Required scope: collections_edit

URL

POST https://api.twitch.tv/kraken/channels/<channel ID>/collections

Optional Query String Parameters

None

Example Request

This creates a collection, entitled “Dallas Tester Collection,” owned by channel 44322889.

curl -H 'Accept: application/vnd.twitchtv.v5+json' \
-H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Authorization: OAuth cfabdegwdoklmawdzdo98xt2fo512y' \
-d '{"title": "Dallas Tester Collection"}' \
-X POST 'https://api.twitch.tv/kraken/channels/44322889/collections'

Example Response

{
  "_id": "zj0GejG3qRSydQ",
  "created_at": "2017-03-07T21:36:14.951167895Z",
  "items_count": 0,
  "owner": {
  "_id": "44322889",
    "bio": "Just a gamer playing games and chatting. :)",
    "created_at": "2013-06-03T19:12:02.580593Z",
    "display_name": "dallas",
    "logo": "https://static-cdn.jtvnw.net/jtv_user_pictures/dallas-profile_image-1a2c906ee2c35f12-300x300.png",
    "name": "dallas",
    "type": "staff",
    "updated_at": "2017-03-07T20:32:19.5209Z"
  },
  "title": "Dallas Tester Collection",
  "total_duration": 0,
  "updated_at": "2017-03-07T21:36:14.951167895Z",
  "views": 0
}

Update Collection

Updates the title of a specified collection. The new title is provided as a required parameter in the request body, in JSON format.

Authentication

Required scope: collections_edit

URL

PUT https://api.twitch.tv/kraken/collections/<collection ID>

Optional Query String Parameters

None

Example Request

This changes the title of collection myIbIFkZphQSbQ.

curl -H 'Accept: application/vnd.twitchtv.v5+json' \
-H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Authorization: OAuth cfabdegwdoklmawdzdo98xt2fo512y' \
-d '{"title": "New Title for Dallas Tester Collection"}' \
-X PUT 'https://api.twitch.tv/kraken/collections/myIbIFkZphQSbQ'

Example Response

204 No Content

Create Collection Thumbnail

Adds the thumbnail of a specified collection item as the thumbnail for the specified collection. The collection item – a video which must already be in the collection – is specified in a required parameter in the request body, in JSON format. The collection item is specified with a collection item ID returned by Get Collection.

Authentication

Required scope: collections_edit

URL

PUT https://api.twitch.tv/kraken/collections/<collection ID>/thumbnail

Optional Query String Parameters

None

Example Request

This assigns the thumbnail for collection item eyJ0eXBlIjoidmlkZW8iLCJpZCI6IjEyMjEzODk0OSJ9 as the thumbnail for collection myIbIFkZphQSbQ.

curl -H 'Accept: application/vnd.twitchtv.v5+json' \
-H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Authorization: OAuth cfabdegwdoklmawdzdo98xt2fo512y' \
-d '{"item_id": "eyJ0eXBlIjoidmlkZW8iLCJpZCI6IjEyMjEzODk0OSJ9"}' \
-X PUT 'https://api.twitch.tv/kraken/collections/myIbIFkZphQSbQ/thumbnail'

Example Response

204 No Content

Delete Collection

Deletes a specified collection.

Authentication

Required scope: collections_edit

URL

DELETE https://api.twitch.tv/kraken/collections/<collection ID>

Optional Query String Parameters

None

Example Request

This deletes collection myIbIFkZphQSbQ.

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

Example Response

204 No Content

Add Item to Collection

Adds a specified video to a specified collection. The video ID and type are specified as required parameters in the request body, in JSON format. The item ID is a video ID (not a collection item ID), and the type must be “video.”

Authentication

Required scope: collections_edit

URL

POST https://api.twitch.tv/kraken/collections/<collection ID>/items

Optional Query String Parameters

None

Example Request

This adds video 122138949 to collection myIbIFkZphQSbQ.

curl -H 'Accept: application/vnd.twitchtv.v5+json' \
-H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Authorization: OAuth cfabdegwdoklmawdzdo98xt2fo512y' \
-d '{"id": "122138949", "type": "video"}' \
-X POST 'https://api.twitch.tv/kraken/collections/myIbIFkZphQSbQ/items'

Example Response

{
  "_id": "eyJ0eXBlIjoidmlkZW8iLCJpZCI6IjEyMjEzODk0OSJ9",
  "item_type": "video",
  "item_id": "122138949",
  "owner": {
    "display_name": "Twitch",
    "_id": "12826",
    "name": "twitch",
    "type": "user",
    "bio": "Twitch is the world's leading social video service and community for gamers. Each day, millions of community members gather to watch, talk, and chat about shared interests. Twitch's video service is the backbone of both live and on-demand distribution for all types of content, including the entire video game ecosystem, the creative arts, vlogging (IRL), and more. Twitch also runs TwitchCon, the annual convention for celebrating the Twitch community. For more information about Twitch, visit our Press Center, Twitter feed (#Twitch), and Blog.",
    "created_at": "2007-05-22T10:39:54.238271Z",
    "updated_at": "2017-03-07T21:35:39.905484Z",
    "logo": "https://static-cdn.jtvnw.net/jtv_user_pictures/twitch-profile_image-bd6df6672afc7497-300x300.png"
  },
  "title": "Fanboys Episode 1 w/ Gassy Mexican","description_html":"",
  "duration": 4676,
  "views": 3142,
  "thumbnails": {
    "small": "https://static-cdn.jtvnw.net/s3_vods/71a4eda892_twitch_24529261280_601749333//thumb/thumb122138949-80x45.jpg",
    "medium": "https://static-cdn.jtvnw.net/s3_vods/71a4eda892_twitch_24529261280_601749333//thumb/thumb122138949-320x180.jpg",
     "large":"https://static-cdn.jtvnw.net/s3_vods/71a4eda892_twitch_24529261280_601749333//thumb/thumb122138949-640x360.jpg",
     "template":"https://static-cdn.jtvnw.net/s3_vods/71a4eda892_twitch_24529261280_601749333//thumb/thumb122138949-{width}x{height}.jpg"
  },
  "game":"Talk Shows",
  "published_at":"2017-02-14T22:27:54Z"
}

Delete Item from Collection

Deletes a specified collection item from a specified collection, if it exists. The collection item is specified with a collection item ID returned by Get Collection.

Authentication

Required scope: collections_edit

URL

DELETE https://api.twitch.tv/kraken/collections/<collection ID>/items/<collection item ID>

Optional Query String Parameters

None

Example Request

This deletes collection item eyJ0eXBlIjoidmlkZW8iLCJpZCI6IjEyMjEzODk0OSJ9 from collection myIbIFkZphQSbQ.

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

Example Response

204 No Content

Move Item within Collection

Moves a specified collection item to a different position within a collection. The collection item is specified with a collection item ID returned by Get Collection. The position is specified by a required parameter in the request body, in JSON format.

Authentication

Required scope: collections_edit

URL

PUT https://api.twitch.tv/kraken/collections/<collection ID>/items/<collection item ID>

Optional Query String Parameters

None

Example Request

This moves collection item eyJ0eXBlIjoidmlkZW8iLCJpZCI6IjEyMjEzODk0OSJ9 to position 3 in collection myIbIFkZphQSbQ.

curl -H 'Accept: application/vnd.twitchtv.v5+json' \
-H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Authorization: OAuth cfabdegwdoklmawdzdo98xt2fo512y' \
-d '{"position": "3"}' \
-X PUT 'https://api.twitch.tv/kraken/collections/myIbIFkZphQSbQ/items/eyJ0eXBlIjoidmlkZW8iLCJpZCI6IjEyMjEzODk0OSJ9'

Example Response

204 No Content
+