Contents

Using the Twitch API v5

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.

Introduction

This guide covers:

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:

Requests

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

Translating from user names to user IDs

Kraken 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:

HTTP Status Code Explanation
400 Request Not Valid. Something is wrong with the request.
401 Unauthorized. The OAuth token does not have the correct scope or does not have the required permission on behalf of the specified user.
403 Forbidden. This usually indicates that authentication was provided, but the authenticated user is not permitted to perform the requested operation. For example, a user who is not a partner might have tried to start a commercial.
404 Not Found. For example, the channel, user, or relationship could not be found.
422 Unprocessable Entity. For example, for a user subscription endpoint, the specified channel does not have a subscription program.
429 Too Many Requests
500 Internal Server Error
503 Service Unavailable. For example, the status of a game or ingest server cannot be retrieved.

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.

Broadcasting Overview and Stream Keys

There are thousands of Twitch broadcasters. A broadcaster sends a video stream to Twitch using any of several tools:

The tool sends a video signal captured from the broadcaster’s game and cameras, through the open Internet, into Twitch (live.twitch.tv), using Real-Time Messaging Protocol (RTMP).

The first stop for a broadcast stream is the Twitch ingesting subsystem, where streams enter Twitch and are authorized and registered, then prepared for viewers. You select an ingest server to receive your stream. There are many ingest servers, each living in a PoP (Point of Presence, a small-to-medium deployment of servers in a co-location facility, normally at a major internet exchange point).

Broadcast URLs and stream keys

Each broadcast uses an RTMP URL with this format:

rtmp://<ingest-server>/app/<stream-key>[?bandwidth_test=true]

Where:

Example: rtmp://live.twitch.tv/app/live_user_123456789?bandwidth_test=true

Docs Status Support Showcase Blog