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 Twitch API 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 Twitch API scopes; we will treat the v5 scope as an equivalent when making calls to endpoints in the Helix namespace.

v5 Scope Twitch API Scope
channel_subscriptions channel:read:subscriptions
channel_commercial channel:edit:commercial
channel_editor channel:manage:broadcast
channel:manage:videos
user_follows_edit user:edit:follows
channel_read channel:read:editors
channel:read:stream_key
user:read:email
user_read user:read:email
user_blocks_read user:read:blocked_users
user_blocks_edit user:manage:blocked_users
user_subscriptions user:read:subscriptions

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 Editors Get Channel Editors  
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 Teams Get Channel Teams Get a list of Twitch Teams of which the specified channel/broadcaster is a member.
Get Channel Subscribers Get Broadcaster Subscriptions The broadcaster_id in the newest endpoint must match the user in the OAuth token.
Check Channel Subscription by User Get Broadcaster Subscriptions Provide one or more user_ids to check subscriptions for specific users.
Get Channel Videos Get Videos  
Start Commercial Start Commercial  
Reset Channel Stream Key   No longer supported via the API.
Chat    
Get Chat Badges by Channel Get Channel Chat Badges The returned data is slightly different in that the Twitch API intensionally returns only the custom chat badges created for the channel. Use Get Global Chat Badges for those that can be used in any channel.
Get Chat Emoticons by Set Get Emote Sets At least one emote_set_id is required in the Twitch API.
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.
Collections    
Get Collection Metadata   No longer supported via the API.
Get Collection   No longer supported via the API.
Get Collections by Channel   No longer supported via the API.
Create Collection   No longer supported via the API.
Update Collection   No longer supported via the API.
Create Collection Thumbnail   No longer supported via the API.
Delete Collection   No longer supported via the API.
Add Item to Collection   No longer supported via the API.
Delete Item from Collection   No longer supported via the API.
Move Item within Collection   No longer supported via the API.
Games    
Get Top Games Get Top Games  
Ingests    
Get Ingest Server List   Refer to the Video Broadcast Guide.
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 Streams Summary   No longer supported via the API.
Get Featured Streams   No longer supported via the API.
Get Followed Streams Get Followed Streams  
Teams    
Get All Teams   No longer supported via the API to retrieve all Teams. Use Get Channel Teams to retrieve the Teams for a specific broadcaster.
Get Team Get Teams Team name or id can be provided.
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 Emotes   No longer supported via the API.
Check User Subscription by Channel Check User Subscription  
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 See Deprecation of Create and Delete Follows API Endpoints.
Unfollow Channel Delete User Follows See Deprecation of Create and Delete Follows API Endpoints.
Get User Block List Get User Block List  
Block User Block User  
Unblock User Unblock User  
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.
Create Video   No longer supported via the API.
Upload Video Part   No longer supported via the API.
Complete Video Upload   No longer supported via the API.
Update Video   No longer supported via the API.
Delete Video Delete Videos