Using the Legacy Twitch API v5
Twitch API v5 is deprecated. Please 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:
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.