Wrexial / Twitch-API

A home for details about our API

Twitch API

Overview

The Twitch API allows websites to develop your own applications based on the rich feature set that we provide. This includes getting information about what streams are live, changing information about specific channels, or doing a SSO integration with Twitch itself. This documents lists the resources that the Twitch API provides. If you have any questions or need any help in using this API, please visit the API Developers Group or Github Issues

The Twitch API is comprised of two parts: the REST API itself and the JavaScript SDK that allows for easy integration 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 should help you if that describes your needs.

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 https://api.twitch.tv/kraken?callback=foo

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.

MIME Types and API Versions

The returned MIME type from requests follows the format:

application/vnd.twitchtv[.version][+json]

Clients may specify the following MIME types:

application/json
application/vnd.twitchtv+json
application/vnd.twitchtv[.version]+json

This allows clients to get either the latest version of the API or a specific version. The current version of the API is application/vnd.twitchtv.v1+json

### Making Requests

When performing requests to the Twitch API, set the Accept HTTP header to the API version you prefer.

Example

For the latest version of the API:

curl -i -H 'Accept: application/vnd.twitchtv+json' 'https://api.twitch.tv/kraken/channels/hebo?client_id=axjhfp777tflhy0yjb5sftsil' 

Specify a specific version (v1):

curl -i -H 'Accept: application/vnd.twitchtv.v1+json' 'https://api.twitch.tv/kraken/channels/hebo?client_id=axjhfp777tflhy0yjb5sftsil' 

## Authentication

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

Resources

Root

/

Basic information about the API and authentication status. If you are authenticated, the response includes the status of your token and links to other related resources.

Response

{
  "token": {
    "authorization": {
      "scopes": ["user_read", "channel_read", "channel_commercial", "user_read"],
      "created_at": "2012-05-08T21:55:12Z",
      "updated_at": "2012-05-17T21:32:13Z"
    },
    "user_name": "hebo",
    "valid": true
  },
  "_links": {
    "channel": "https://api.twitch.tv/kraken/channel",
    "users": "https://api.twitch.tv/kraken/users/hebo",
    "user": "https://api.twitch.tv/kraken/user",
    "channels": "https://api.twitch.tv/kraken/channels/hebo",
    "chat": "https://api.twitch.tv/kraken/chat/hebo",
    "streams": "https://api.twitch.tv/kraken/streams",
    "ingests":"https://api.twitch.tv/kraken/ingests"
  }
}

Users

Channels

Videos

Streams

Games

Search

Teams

Chat

Ingests