ACTION REQUIRED: Twitch API Version Update

TL;DR: Read all of this. It’s important and will break your integrations. We’re changing how the Twitch API works and old versions of our API will be deprecated and removed.

Today, we’re delivering a change that you’ve requested for quite some time! Twitch API v5 is available now and uses IDs to reference users instead of usernames. This new API version puts us in a better position to add new functionality and features to both the API and the Twitch website.

You can start using v5 and upgrading your integrations today. You simply pass the application/vnd.twitchtv.v5+json header on your requests. We’re working hard to deliver reference documentation on the affected endpoints by mid-December. EDIT: We’ve delivered the v5 documentation on the Twitch Developer website. An example to tide you over:

Retrieving a user in v3:

{% raw %}
curl -H 'Client-ID: xxxxxxxxxxxxxxxx' \
-H 'Accept: application/vnd.twitchtv.v3+json' \
https://api.twitch.tv/kraken/users/dallas
{% endraw %}

Retrieving a user in v5:

{% raw %}
curl -H 'Client-ID: xxxxxxxxxxxxxxxx' \
-H 'Accept: application/vnd.twitchtv.v5+json' \
https://api.twitch.tv/kraken/users/44322889
{% endraw %}

There are other changes to note with this version:

• The _links object is removed from all responses. As a developer, you will be responsible for handling the paging offsets when polling the API.

• Added sub-second precision to time fields.

• Removed /games/featured endpoint.

• Removed delay, background, and banner from the channels response object.

• Replaced q and type parameters on the search endpoint. The q parameter is now called query. The type parameter is always set to suggest.

• Removed paywalled field from the video response object.

• Removed /kraken/chat.

• EDIT: All ID fields should be treated as strings instead of integers. Note: this is an ongoing change, so there might be some outliers.

What does this mean for me as a developer?

You need to migrate your code to use v5. On February 14, 2017, we will be removing v1 and v2 of the API and transition v3 into a deprecated state. In one year (February 14, 2018), v3 will be removed from the API. We hope that this gives enough transition time for your integrations.

If your integration relies on username now, please use the /users endpoint to translate from a username to an ID as shown below.

{% raw %}
curl -H 'Client-ID: XXXXX' -H 'Accept: application/vnd.twitchtv.v3+json' [https://api.twitch.tv/kraken/users/dallas](https://api.twitch.tv/kraken/users/dallas)
{% endraw %}

UPDATE: We heard loud and clear feedback that an API to translate from login name to ID was needed. We delivered it at the URL below! We’re still iterating on this particular API so stay tuned for updates!

{% raw %}
https://api.twitch.tv/kraken/users?login=dallas&api_version=5
{% endraw %}

For questions regarding this transition, please ask on the developer forum thread. We know this is a big transition and want to help in any way that we can.

Thank you for being a part of the Twitch Developer community!