Using the Twitch API

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 a developer application on the connections page of your Twitch account. 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)

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:

1
2
3
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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
{
   "_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:

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

Gets this response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
   "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:

1
2
3
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:

1
2
3
4
HTTP/1.1 200 OK
...
x-api-version: 5
...

JSON and JSON-P

All data is sent and received as JSON.

All API endpoints support JSON-P 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:

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

1
2
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:

1
2
3
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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
   "_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:

1
2
3
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.

1
2
3
4
5
{
    "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 JSON-P, 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:

  • Streaming encoder, normally a software implementation like OBS (Open Broadcaster Software), Xsplit, FMLE (Flash Media Live Encoder), or Elemental
  • Console, like PS4
  • Hardware video encoder

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:

  • <ingest-server> identifies a specific Twitch server that receives this broadcast stream; e.g., live.twitch.tv.

  • <stream-key> (also known as authorization key) uniquely identifies this stream. Stream keys are assigned by Twitch. Broadcasters can retrieve the keys from the broadcaster dashboard on www.twitch.tv.

  • <bandwidth_test=true> is an optional query-string parameter that disables live viewing of the stream. It is used to verify bandwidth health.

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