A home for details about our API

README.md

Twitch API v3

Analytics

Terms of Use

By accessing or using Twitch API, you are indicating that you have read and agree to Twitch's Terms of Service, Privacy Policy, and API Terms of Service.

Overview

The Twitch API enables you to develop your own applications using the rich feature set that we provide. Features include retrieving data about what streams are live, changing information about specific channels, and doing an SSO integration with Twitch. The following pages list the resources that the Twitch API provides. If you have any questions or need help in using this API, please visit the Twitch Developer Forums. We also have an IRC channel over on freenode: chat.freenode.net:6667/#twitch-api. Bugs can be reported on our Github Issues.

The Twitch API is comprised of two parts: the REST API and a JavaScript SDK that allows for easy integration of the Twitch features into any website. Most users will only need to use the JS SDK, but if you want a deeper integration (for example, for use with Python or PHP scripts), you may access the REST API directly. The RESTful Integration Guide provides additional information for using REST API.

API Versions and MIME Types

The current stable API version is v3. We allow clients to use any version of our API. Versioning is per-method so for example you can have v2 of /channels and v3 of /users.

We strongly recommend specifying a version, otherwise version updates might break your application if you've defaulted your requests to use the latest version.

When specifying a version for a request to the Twitch API, set the Accept HTTP header to the API version you prefer. This is done by appending a version specifier to our vendor specific MIME type. Responses will have an x-api-version header that will indicate which version you received.

You should specify the following MIME type:

application/vnd.twitchtv[.version]+json

The default returned MIME type for requests is always

application/json

In situations where headers cannot be set, you can also specify a version as a querystring parameter: api_version=3

#### Example Requests

Specify a specific version (v2):

curl -i -H 'Accept: application/vnd.twitchtv.v2+json'\
-H 'Client-ID: axjhfp777tflhy0yjb5sftsil'\
'https://api.twitch.tv/kraken/channels/hebo'

HTTP/1.1 200 OK
...
x-api-version: 2
...
Front-End-Https: on

{ ...

Formats

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

All data is sent and received as JSON. Blank fields are included as null instead of being omitted.

JSON-P

All API methods 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 always

application/javascript

Self-Describing API

The API is self-describing and can be explored from the base URL:

curl -i https://api.twitch.tv/kraken

Every JSON response includes a _links object which allows you to navigate the API without having to hardcode any of our URLs.

{
    "_links": {
        "teams": "https://api.twitch.tv/kraken/teams",
        "channel": "https://api.twitch.tv/kraken/channel",
        "user": "https://api.twitch.tv/kraken/user",
        "ingests": "https://api.twitch.tv/kraken/ingests",
        "streams": "https://api.twitch.tv/kraken/streams",
        "search": "https://api.twitch.tv/kraken/search"
    },
    ...
}

Errors

All error responses are in the following format, delivered with the corresponding status code:

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

When using JSON-P, the status code will always be 200 to allow browsers to parse it. Check the body of the response for the actual error data.

Rate Limits

We require you to send your application's client_id with every request you make to ensure that your application is not rate limited. You should do so by sending the following HTTP header:

Client-ID: <client_id>

In situations where headers cannot be set, you can also specify a client ID as a querystring parameter: client_id=<client_id>

## Authentication

We use an OAuth 2.0, an authentication protocol designed to make accessing user accounts from third party clients easy and secure. Read our authentication guide to see how to connect with Twitch users from your own service.

Index

Blocks

Endpoint Description
GET /users/:user/blocks Get user's block list
PUT /users/:user/blocks/:target Add target to user's block list
DELETE /users/:user/blocks/:target Delete target from user's block list

Channels

Endpoint Description
GET /channels/:channel Get channel object
GET /channel Get channel object
GET /channels/:channel/videos Get channel's list of videos
GET /channels/:channel/follows Get channel's list of following users
GET /channels/:channel/editors Get channel's list of editors
PUT /channels/:channel Update channel object
DELETE /channels/:channel/stream_key Reset channel's stream key
POST /channels/:channel/commercial Start a commercial on channel
GET /channels/:channel/teams Get list of teams channel belongs to

Channel Feed

Endpoint Description
GET /feed/:channel/posts Get channel feed posts
POST /feed/:channel/posts Create post
GET /feed/:channel/posts/:id Get post
DELETE /feed/:channel/posts/:id Delete post
POST /feed/:channel/posts/:id/reactions Create reaction to post
DELETE /feed/:channel/posts/:id/reactions Delete reaction

Chat

Endpoint Description
GET /chat/:channel Get links object to other chat endpoints
GET /chat/:channel/badges Get chat badges for channel
GET /chat/emoticons Get list of every emoticon object
GET /chat/emoticon_images Get list of emoticons

Follows

Endpoint Description
GET /channels/:channel/follows Get channel's list of following users
GET /users/:user/follows/channels Get a user's list of followed channels
GET /users/:user/follows/channels/:target Get status of follow relationship between user and target channel
PUT /users/:user/follows/channels/:target Follow a channel
DELETE /users/:user/follows/channels/:target Unfollow a channel
GET /streams/followed Get a list of streams user is following

Games

Endpoint Description
GET /games/top Get games by number of viewers

Ingests

Endpoint Description
GET /ingests Get list of ingests

Root

Endpoint Description
GET / Get top level links object and authorization status

Search

Endpoint Description
GET /search/channels Find channels
GET /search/streams Find streams
GET /search/games Find games

Streams

Endpoint Description
GET /streams/:channel/ Get stream object
GET /streams Get stream object
GET /streams/featured Get a list of featured streams
GET /streams/summary Get a summary of streams
GET /streams/followed Get a list of streams user is following

Subscriptions

Endpoint Description
GET /channels/:channel/subscriptions Get list of users subscribed to channel
GET /channels/:channel/subscriptions/:user Check if channel has user subscribed
GET /users/:user/subscriptions/:channel Check if user subscribes to channel

Teams

Endpoint Description
GET /teams Get list of active team objects
GET /teams/:team Get team object

Users

Endpoint Description
GET /users/:user Get user object
GET /users/:user/emotes Get list of user's emotes
GET /user Get user object
GET /streams/followed Get list of streams user is following
GET /videos/followed Get list of videos belonging to channels user is following

Videos

Endpoint Description
GET /videos/:id Get video object
GET /videos/top Get top videos by number of views
GET /channels/:channel/videos Get list of video objects belonging to channel
GET /videos/followed Get list of videos belonging to channels user is following