Contents

Get Started with the Twitch API

Introduction

The Twitch API provides a way for developers to request information in order to build creative integrations for the broader Twitch community. It applies common API concepts for retrieving data such as OAuth, JSON responses, and standard HTTP codes.

As an example to get started, let’s make an API request to retrieve information about a Twitch channel.

Step 1: Create an Application

To make API requests, you will need to register a Twitch application using the following steps:

  1. Log into the developer console using your Twitch account.
  2. From this page, select the Applications tab and click Register Your Application.
  3. Enter a unique application name, an OAuth redirect URL to return to after authentication (you can use “http://localhost” to get started in this example), select an application category of your choice, and confirm you’re not a robot. Click the Create button.
  4. You will be directed back to your list of applications. Click the Manage button next to the application we just created. You will notice there is now a section for “Client ID” which we will use momentarily.

Step 2: Authentication Using the Twitch CLI

Authentication can sound daughting. While the authentication guide contains a lot of information when building and automating a larger application, it’s not the easiest place to begin. To get started with authentication, Twitch provides a tool known as the Twitch CLI (or Command Line Interface) with a number of features including a way to quickly create an authentication token which is needed to make our API request in this example.

Visit the Twitch CLI repository and follow the instructions in the README to install the CLI manually or via command line installers like Homebrew for Macs and Scoop for Windows. Once installed, you should be able to run twitch in your command line program of choice and see details on how to use the tool.

$ twitch
A simple CLI tool for the New Twitch API and Webhook products.

Usage:
  twitch [command]

Available Commands:
  api         Used to interface with the Twitch API
  configure   Configures your Twitch CLI with your Client ID and Secret
  event       Used to interface with Event services, such as Eventsub and Websub.
  help        Help about any command
  mock-api    Used to interface with the mock Twitch API.
  token       Logs into Twitch and returns an access token according to your client id/secret in the configuration.
  version     Returns the current version of the CLI.

Flags:
      --config string   config file (default is $HOME/.twitch-cli/.twitch-cli.env)
  -h, --help            help for twitch

Use "twitch [command] --help" for more information about a command.

If you have trouble installing or running the CLI, feel free to ask for help in the #cli-help channel of the TwitchDev Discord server.

When the Twitch CLI is installed, run twitch token on your command line. Assuming this is your first time using the CLI, it’ll ask you to configure the tool. At the first prompt for “Client ID,” enter (or copy/paste) the client ID we mentioned at the end of step 1 in the developer console. This will be a long series of letters and numbers. The CLI will then ask you for a “Client Secret.” Back on the same webpage with the Client ID, click the “New Secret” button and confirm your action. Then copy/paste the Client Secret that is now available into the prompt for the CLI. The results will look something like this:

$ twitch token
No Client ID or Secret found in configuration. Triggering configuration now.
Client ID: wbmytr93xzw8zbg0p1izqyzzc5mbiz
Client Secret: 5ykf41lduut2lvbcnu7zg1wjdhroiw
Updated configuration.
2021/07/30 20:20:06 App Access Token: 2gbdx6oar67tqtcmt49t3wpcgycthx

Step 3: Making a Request to the Twitch API

Now that we have a client ID and an authentication token (the app access token that was created in the last line of the configuration), we can make a request to the Twitch API! In fact, we can even use the Twitch CLI to make an API request since it now has the client ID and authentication token. Our goal in this example is to get information about a Twitch channel. To get information about the TwitchDev channel, type in the following command.

twitch api get users -q login=twitchdev

This example is using specific notation unique to the Twitch CLI. You can find more information about how to call other endpoints with examples in the API usage documentation for the CLI.

To make the same request without the CLI, you can use a command line tool like cURL and supply the authentication information via headers like the following example (changing the values below for Authorization and Client-id to your own values).

curl --location --request \
GET 'https://api.twitch.tv/helix/users?login=twitchdev' \
--header 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
--header 'Client-id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'

With either approach, you should receive the following response.

{
  "data": [
    {
      "broadcaster_type": "partner",
      "created_at": "2016-12-14T20:32:28.894263Z",
      "description": "Supporting third-party developers building Twitch integrations from chatbots to game integrations.",
      "display_name": "TwitchDev",
      "id": "141981764",
      "login": "twitchdev",
      "offline_image_url": "https://static-cdn.jtvnw.net/jtv_user_pictures/3f13ab61-ec78-4fe6-8481-8682cb3b0ac2-channel_offline_image-1920x1080.png",
      "profile_image_url": "https://static-cdn.jtvnw.net/jtv_user_pictures/8a6381c7-d0c0-4576-b179-38bd5ce1d6af-profile_image-300x300.png",
      "type": "",
      "view_count": 6652509
    }
  ]
}

What’s Next

Take a look at the API usage documentation for the CLI and try out a few different endpoints with different options.

Refer to the Twitch API Reference for the definitions of all available endpoints and try making requests to some that seem interesting via the Twitch CLI or cURL.

For more information and concepts about the Twitch API, go the Twitch API Guide next.

For a more in-depth look at Twitch authentication options, see the Authentication guide. This will provide more information to enable your application to take actions on behalf of a Twitch account or access specific data about a user’s account.

Lastly, stop by our Developer Forums to join our community of Twitch developers, and explore developer support to find others ways to connect with the community.