Collections (of Videos) 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 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/

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//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//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:`	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//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/

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//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/

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//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//items/

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//items/

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