Using the Legacy Twitch API v5

Legacy Twitch API v5 is deprecated and scheduled to be decommissioned on February 28, 2022. For more information, refer to the timeline announcement and the v5 migration guide to use the latest version of the Twitch API.

Introduction

This guide covers:

• Getting a client ID
• Requests
• Translating from user names to user IDs
• Responses
• Errors
• Broadcasting overview and stream keys

Getting a client ID

To identify your application to the API, every request must include your application’s client ID, either explicitly or implicitly by including an OAuth token. If you use an OAuth token in your request, the API figures out the client ID for you.

Requests can include both a client ID and an OAuth token. Requests without either one fail with an HTTP 400 error.

To get a client ID, register your application on the Twitch developer portal. Once you have your client ID, you can send it via:

• Request header (Client-ID: XXXXX)
• Query-string parameter
  (https://api.twitch.tv/kraken/users/44322889?client_id=XXXXX)

Requests

For client IDs created on or after May 31, 2019, the only available version of the Legacy Twitch API is v5.  For client IDs created prior to May 31, 2019, use the Accept: application/vnd.twitchtv.v5+json header on your requests to access v5 of the Legacy Twitch API API.

Translating from user names to user IDs

Legacy Twitch API v5 APIs use user IDs, whereas older versions of the APIs used user names. To translate from a user name to a user ID, use the Get Users endpoint with up to 100 logins:

curl -H 'Accept: application/vnd.twitchtv.v5+json' \
-H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-X GET https://api.twitch.tv/kraken/users?login=dallas,dallasnchains

The response is a JSON blob that contains the user objects for the specified users:

{
   "_total": 2,
   "users": [
      {
         "_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-02-09T16:32:06.784398Z"
      },
      {
         "_id": "129454141",
         "bio": null,
         "created_at": "2016-07-13T14:40:42.398257Z",
         "display_name": "dallasnchains",
         "logo": null,
         "name": "dallasnchains",
         "type": "user",
         "updated_at": "2017-02-04T14:32:38.626459Z"
      }
   ]
}

Root URL

The root for all API resources is https://api.twitch.tv/kraken.

If you submit a request to the root URL and you are authenticated, the response includes the status of your token. For example, this request:

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

Gets this response:

{
   "token": {
      "authorization": {
         "created_at": "2016-12-14T15:51:16Z",
         "scopes": [
            "user_read"
         ],
         "updated_at": "2016-12-14T15:51:16Z"
      },
      "client_id": "uo6dggojyb8d6soh92zknwmi5ej1q2",
      "user_id": "44322889",
      "user_name": "dallas",
      "valid": true
   }
}

Blank fields

Blank fields are included as null.

JSON and JSONP

All data is sent and received as JSON.

All API endpoints support JSONP by providing a callback parameter with the request:

curl -i https://api.twitch.tv/kraken?callback=foo

The returned MIME type for JSONP requests is:

application/javascript

Query Parameters

In the reference documentation for endpoints, query string parameters are listed where they apply to an endpoint. The syntax for using query string parameters is as follows:

<URL for the endpoint, with required params>?<query param 1>=<value 1>&<query param 2>=<value 2>...

For example, the Get Feed Posts endpoint has three optional query string parameters, limit, cursor, and comments. If all three query string parameters are used, the URL is:

https://api.twitch.tv/kraken/feed/<feed user ID>/posts?limit=<limit value>&cursor=<cursor value>
&comments=<comments value>

Responses

All responses are JSON objects.

Paging through results: cursor v. offset

When fetching multiple items, there are two different mechanisms to page through results, offset and cursor.

For some endpoints, you set a limit, set offset to 0, and add the limit value to the offset value each time you want to see the next page.

For other endpoints, offset is deprecated; instead, a cursor is returned. This is used to tell the server where to start fetching the next set of results. For example:

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

might return something like this:

{
   "_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"
      }
   },
   ...
   ]
}

For the next page of results, construct your query as follows:

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

You would get the next set of results, as well as the next cursor.

When there are no more items to be returned, the cursor in the response is blank.

The correct parameter to use (offset or cursor) is noted in the reference documentation for each endpoint.

Errors

All error responses have the following format, delivered with a standard HTTP status code. The error message varies depending on the endpoint.

{
  "message":"Invalid Token",
  "status":401,
  "error":"Unauthorized"
}

Common response codes are:

When using JSONP, the status code is always 200, to allow browsers to parse it. Check the body of the response for the error data.