subscriptions.md

Subscriptions

Users can subscribe to channels.

Endpoint	Description
GET /channels/:channel/subscriptions	Get list of users subscribed to channel
GET /channels/:channel/subscriptions/:user	Check if channel has user subscribed
GET /users/:user/subscriptions/:channel	Check if user subscribes to channel

GET /channels/:channel/subscriptions

Returns a list of subscription objects sorted by subscription relationship creation date which contain users subscribed to :channel.

Authenticated, required scope: channel_subscriptions

Parameters

Name	Required?	Type	Description
limit	optional	integer	Maximum number of objects in array. Default is 25. Maximum is 100.
offset	optional	integer	Object offset for pagination. Default is 0.
direction	optional	string	Creation date sorting direction. Default is asc. Valid values are asc and desc.

Example Request

curl -H 'Accept: application/vnd.twitchtv.v3+json' -H 'Authorization: OAuth <access_token>' \
-X GET https://api.twitch.tv/kraken/channels/test_channel/subscriptions

Example Response

{
  "_total": 3,
  "_links": {
    "next": "https://api.twitch.tv/kraken/channels/test_channel/subscriptions?limit=25&offset=25",
    "self": "https://api.twitch.tv/kraken/channels/test_channel/subscriptions?limit=25&offset=0"
  },
  "subscriptions": [
    {
      "_id": "88d4621871b7274c34d5c3eb5dad6780c8533318",
      "user": {
        "_id": 38248673,
        "logo": null,
        "type": "user",
        "bio": "I'm testuser",
        "created_at": "2012-12-06T00:32:36Z",
        "name": "testuser",
        "updated_at": "2013-02-06T21:27:46Z",
        "display_name": "testuser",
        "_links": {
          "self": "https://api.twitch.tv/kraken/users/testuser"
        }
      },
      "created_at": "2013-02-06T21:33:33Z",
      "_links": {
        "self": "https://api.twitch.tv/kraken/channels/test_channel/subscriptions/testuser"
      }
    },
    ...
  ]
}

GET /channels/:channel/subscriptions/:user

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

Authenticated, required scope: channel_check_subscription

Example Request

curl -H 'Accept: application/vnd.twitchtv.v3+json' -H 'Authorization: OAuth <access_token>' \
-X GET https://api.twitch.tv/kraken/channels/test_channel/subscriptions/testuser

Example Response

If user is subscribed:

{
  "_id": "88d4621871b7274c34d5c3eb5dad6780c8533318",
  "user": {
    "_id": 38248673,
    "logo": null,
    "type": "user",
    "bio": "I'm testuser",
    "created_at": "2012-12-06T00:32:36Z",
    "name": "testuser",
    "updated_at": "2013-02-06T21:27:46Z",
    "display_name": "testuser",
    "_links": {
      "self": "https://api.twitch.tv/kraken/users/testuser"
    }
  },
  "created_at": "2013-02-06T21:33:33Z",
  "_links": {
    "self": "https://api.twitch.tv/kraken/channels/test_channel/subscriptions/testuser"
  }
}

404 Not Found if user is not subscribed.

GET /users/:user/subscriptions/:channel

Returns a channel object that user subscribes to. Requires authentication for :user.

Authenticated, required scope: user_subscriptions

Example Request

curl -H 'Accept: application/vnd.twitchtv.v3+json' -H 'Authorization: OAuth <access_token>' \
-X GET https://api.twitch.tv/kraken/users/test_user/subscriptions/test_channel

Example Response

If user is subscribed:

{
"_links": {
  "self": "https://api.twitch.tv/kraken/users/test_user/subscriptions/test_channel"
},
  "channel": {
    "mature": false,
    "status": "test status",
    "broadcaster_language": "en",
    "display_name": "test_channel",
    "game": "Gaming Talk Shows",
    "delay": 0,
    "language": "en",
    "_id": 12345,
    "name": "test_channel",
    "created_at": "2007-05-22T10:39:54Z",
    "updated_at": "2015-02-12T04:15:49Z",
    "logo": "http://static-cdn.jtvnw.net/jtv_user_pictures/test_channel-profile_image-94a42b3a13c31c02-300x300.jpeg",
    "banner": "http://static-cdn.jtvnw.net/jtv_user_pictures/test_channel-channel_header_image-08dd874c17f39837-640x125.png",
    "video_banner": "http://static-cdn.jtvnw.net/jtv_user_pictures/test_channel-channel_offline_image-b314c834d210dc1a-640x360.png",
    "background": null,
    "profile_banner": "http://static-cdn.jtvnw.net/jtv_user_pictures/test_channel-profile_banner-6936c61353e4aeed-480.png",
    "profile_banner_background_color": "null",
    "partner": true,
    "url": "http://www.twitch.tv/test_channel",
    "views": 49144894,
    "followers": 215780,
    "_links": {
      "self": "https://api.twitch.tv/kraken/channels/test_channel",
      "follows": "https://api.twitch.tv/kraken/channels/test_channel/follows",
      "commercial": "https://api.twitch.tv/kraken/channels/test_channel/commercial",
      "stream_key": "https://api.twitch.tv/kraken/channels/test_channel/stream_key",
      "chat": "https://api.twitch.tv/kraken/chat/test_channel",
      "features": "https://api.twitch.tv/kraken/channels/test_channel/features",
      "subscriptions": "https://api.twitch.tv/kraken/channels/test_channel/subscriptions",
      "editors": "https://api.twitch.tv/kraken/channels/test_channel/editors",
      "teams": "https://api.twitch.tv/kraken/channels/test_channel/teams",
      "videos": "https://api.twitch.tv/kraken/channels/test_channel/videos"
    }
  },
  "_id": "ba93ea2a1046081cf8621e3811b435c403479aa2",
  "created_at": "2013-07-16T21:46:27Z"
}

404 Not Found if user is not subscribed.

422 Unprocessable Entity if channel has no subscription program.