v5 to Twitch API Migration Guide
The following guide provides information and resources to help migrate legacy v5 integrations to the Twitch API that uses the Helix namespace. v5 was the previous version of the Twitch API and was decommissioned on February 28, 2022.
This guide may not be exhaustive, however it should cover the most common differences between the API versions to assist with updating older applications that are no longer functioning properly.
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.
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.
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|
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||Latest Endpoint||Description/Notes|
|Get Cheermotes||Get Cheermotes||Retrieves information about the available cheermotes.|
|Get Channel||Get Channel Information||Retrieve information about a Twitch channel specified by the
|Get Channel by ID||Get Channel Information||Retrieve information about a Twitch channel.
|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
|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
|Check Channel Subscription by User||Get Broadcaster Subscriptions||Provide one or more
|Get Channel Videos||Get Videos|
|Start Commercial||Start Commercial|
|Reset Channel Stream Key||No longer supported via the API.|
|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
|Get Clip||Get Clips||
|Get Top Clips||Get Clips||
|Get Followed Clips||Get Clips||While not an exact equivalent, the latest “Get Clips” endpoint has an optional
|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.|
|Get Top Games||Get Top Games|
|Get Ingest Server List||Refer to the Video Broadcast Guide.|
|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.|
|Get Stream by User||Get Streams||
|Get Live Streams||Get Streams||Filters differ slightly. Uses
|Get Streams Summary||No longer supported via the API.|
|Get Featured Streams||No longer supported via the API.|
|Get Followed Streams||Get Followed Streams|
|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
|Get User||Get Users||Omit id and login to lookup a user by the Bearer token.|
|Get User by ID||Get Users||
|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
|Check User Follows by Channel||Get Users Follows||Include the
|See Deprecation of Create and Delete Follows API Endpoints.|
|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|
|Get Video||Get Videos||
|Get Top Videos||Get Videos||Uses
|Get Followed Videos||Get Users Follows + Get Videos||Use “Get Users Follows” to get the
|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|
The endpoints defined within the original Extension reference rely on the same underlying infrastructure as v5 and are included in the decommission. Equivalent endpoints have been added to the latest API infrastructure and reference, and are detailed below. An easy way to confirm if you are using the latest endpoints is to make sure your HTTP requests include “api.twitch.tv/helix/extensions” rather than “api.twitch.tv/extensions”.
|Deprecated Endpoint||Latest Endpoint|
|Create Extension Secret||Create Extension Secret|
|Get Extension Secret||Get Extension Secrets|
|Revoke Extension Secrets||Use Create Extension Secret to rotate any current secrets out of service.|
|Get Live Channels with Extension Activated||Get Extension Live Channels|
|Set Extension Required Configuration||Set Extension Required Configuration|
|Set Extension Configuration Segment||Set Extension Configuration Segment|
|Get Extension Channel Configuration||Use Get Extension Configuration Segment and specify multiple
|Get Extension Configuration Segment||Get Extension Configuration Segment|
|Send Extension PubSub Message||Send Extension PubSub Message|
|Send Extension Chat Message||Send Extension Chat Message|
|N/A||Get Released Extensions|
|N/A||Get Extension Bits Products|
|N/A||Update Extension Bits Product|