Contents

v5 to Twitch API Migration Guide

Overview

We are providing the following guide with information and resources to help migrate existing v5 integrations to the Twitch API that uses the Helix namespace.

This guide may not be exhaustive, however it should cover the most common differences between the APIs that you’ll need to know when using the latest endpoints.

Authentication Tokens and Headers

OAuth tokens are required when requesting Twitch API endpoints. This differs from v5 where most endpoints only required the Client ID header. You will also need to use the word “Bearer” in the Authorization header instead of “OAuth.” Here is a curl example that demonstrates how to send your Client ID and OAuth token for endpoints in the Helix namespace.

curl -H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-X GET 'https://api.twitch.tv/helix/channels?broadcaster_id=12826'

Many endpoints can be requested using an app access token which will let you access non-user specific public information. Although you cannot request most scopes with this type of token, it is useful for making calls to the search endpoints, stream status endpoints, or other similar endpoints that do not require user authorization to provide privileged information (such as the subscribers endpoints which require the broadcaster to approve of third-party access). In these cases, or to scale your application for more users, consider user access tokens.

You can find some examples showing how to generate and use access tokens for the Twitch API in our Community Code resource.

Rate Limits

The Twitch API has introduced rate limits not present in v5. As such, you may need to consider some changes to your application for the information you are requesting. For example, instead of relying on an app access token that has a set rate limit, consider using a user access token in which case each user of your application is given a rate limit allowing your development to scale as your users increase. You may also need to consider timing requests to fit within the limits if an app access token must be used.

The Twitch API has a rate limit of 800 points per minute and you can use the response headers of API requests to monitor your usage to adjust as needed. For more information, please see our rate limit documentation.

Two common API use cases involve requesting streams for live streaming status and requesting users to get their username or user id. As such, we want to remind you that up to 100 streams or users can be requested in a single request, which can help an application operate within the rate limits.

Authentication Scopes

As is the case for many developers, you may already have broadcasters or users who have authorized your application to access information about their accounts. Since we want to minimize the disruption for your users, we are allowing some v5 authentication scopes to be used for requests to the latest version of the API. This means you will not have to prompt broadcasters or users to re-authenticate when switching your development from v5 endpoints to the latest endpoints.

When implementing one our our latest endpoints for the first time, for example, adding functionality that you did not provide with v5 endpoints, it is preferable to use the Helix scope instead of one of the v5 scopes that have been added as a migration convenience. You can find more information about scopes in our authentication documentation. As the following table indicates, each v5 scope maps to one or more Helix scopes; we will treat the v5 scope as an equivalent when making calls to endpoints in the Helix namespace.

v5 Scope Helix Scope
channel_subscriptions channel:read:subscriptions
channel_commercial channel:edit:commercial
channel_editor channel:manage:broadcast
user_follows_edit user:edit:follows
channel_read channel:read:stream_key
user:read:email
user_read user:read:email

Endpoint Equivalence

Each v5 endpoint that has an equivalent endpoint in our latest version of the API is listed in the following table to help update your application during the migration period.

v5 Endpoint Newest Endpoint Description/Notes
Bits    
Get Cheermotes Get Cheermotes Retrieves information about the available cheermotes.
Channels    
Get Channel Get Channel Information Retrieve information about a Twitch channel specified by the broadcaster_id. The user associated with a user access token is not assumed.
Get Channel by ID Get Channel Information Retrieve information about a Twitch channel. Channel ID is synonymous with broadcaster_id.
Update Channel Modify Channel Information Modify the title or game of a Twitch channel.
Get Channel Followers Get Users Follows Get a list of users who follow a Twitch channel. The to_id query parameter must be used.
Get Channel Subscribers Get Broadcaster Subscriptions The broadcaster_id in the newest endpoint must match the user in the OAuth token.
Get Channel Videos Get Videos  
Start Commercial Start Commercial  
Clips    
Get Clip Get Clips id in the new endpoint is equivalent to slug in the v5 endpoint.
Get Top Clips Get Clips broadcast_id must be used in the new endpoint rather than the channel name used by the v5 endpoint.
Get Followed Clips Get Clips While not an exact equivalent, the latest “Get Clips” endpoint has an optional game_id parameter to get top Clips for a specific game.
Games    
Get Top Games Get Top Games  
Search    
Search Channels Search Channels  
Search Games Search Categories “Categories” are synonymous with “Games” from the older endpoint.
Search Streams Search Channels OR Search Categories The v5 endpoint searched for the channel title and category. Use “Search Channels” to match channel name or title. Use “Search Categories” to match a category.
Streams    
Get Stream by User Get Streams user_id is synonymous with channel ID. To get the game name, call “Get Games” with the returned game_id
Get Live Streams Get Streams Filters differ slightly. Uses game_id, user_id, and user_login. stream_type not available.
Get Followed Streams Get Users Follows + Get Streams Use “Get Users Follows” to get the user_ids followed, then provide this list as a query parameter for “Get Streams.”
Users    
Get User Get Users Omit id and login to lookup a user by the Bearer token.
Get User by ID Get Users id is synonymous with user ID.
Get Users Get Users  
Get User Follows Get Users Follows Include only the from_id parameter.
Check User Follows by Channel Get Users Follows Include the from_id and to_id parameters.
Follow Channel Create User Follows from_id is synonymous with user ID. channel ID is synonymous with to_id.
Unfollow Channel Delete User Follows from_id is synonymous with user ID. channel ID is synonymous with to_id.
Create User Connection to Viewer Heartbeat Service (VHS) Deprecated as of August 18, 2020. Use the latest version of Drops.
Check User Connection to Viewer Heartbeat Service (VHS) Deprecated as of August 18, 2020. Use the latest version of Drops.
Delete User Connection to Viewer Heartbeat Service (VHS) Deprecated as of August 18, 2020. Use the latest version of Drops.
Videos    
Get Video Get Videos id is synonymous with video ID.
Get Top Videos Get Videos Uses game_id instead of game name.
Get Followed Videos Get Users Follows + Get Videos Use “Get Users Follows” to get the user_ids followed, then call “Get Videos” for each user_id you would like to retrieve videos for.