Contents

Using the Twitch API v5

Introduction

This guide includes information about getting client IDs, translating from v3 user names to v5 user IDs, paging through results, requests, responses, and error codes. It ends with a brief overview of broadcasting URLs and stream keys.

Which API Version Can You Use?

VersionStatus
v3Deprecated 2/14/17. Third-party support to be removed 12/31/18.
v5Deprecated. No scheduled removal date.
New Twitch APISupported.

Note: The default version of the API is v3 until 12/31/18. Starting in 2019, the default version will be v5. The default version applies to the API using kraken URLs.

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 dev portal. Once you have your client ID, you can send it via:

Translating from User Names to User IDs

To translate from a v3 user name to a v5 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"
      }
   ]
}

Requests

To upgrade your integrations to v5, use the application/vnd.twitchtv.v5+json header on your requests.

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.

API Versions and MIME Types

We allow clients to use any version of our API. Versioning is per-method; for example, you can use v3 of the Get Channel endpoint and v5 of the Get User endpoint.

We strongly recommend you specify a version in your requests. Otherwise — if you default your requests to use the latest version — version updates might break your application.

When specifying a version in a request to the Twitch API, set the Accept HTTP header to the API version you prefer. You do this by appending a version specifier to our vendor-specific MIME type. Responses will have an x-api-version header that indicates which version you received.

Specify the following MIME type:

application/vnd.twitchtv.v<version>+json

The default returned MIME type for requests is:

application/jsonp

Where headers cannot be set, specify the version as a query-string parameter:

api_version=5

For example, this request specifies version 5:

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

And this is the response:

HTTP/1.1 200 OK
...
x-api-version: 5
...

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 String 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 vs 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, you 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 this 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