Introducing the Tags API

Late last year we introduced Tags, a new discovery tool that lets streamers describe their content in more detail and viewers more easily filter through categories, channels, etc. Today, we are pleased to announce that a new Tags API is now available to enable third party application developers to fully integrate Tags into their apps!

With the new Tags API, it is possible to do the following:

Fetch the list of available stream tags

A third party application developer can retrieve a paginated list of available stream tags through a GET endpoint. By default, this endpoint will return all stream tags, but it’s also possible to filter this list down to a specific set of tags.

Fetch the list of tags applied to a stream

A third party application developer can retrieve the set of all stream tags applied to a specific stream through a GET endpoint.

Replace stream tags

A third party application developer can specify a channel and a set of stream tags to replace the set of stream tags that are already applied to that channel through a PUT endpoint. This API requires user authentication, as only the creator or an editor of a channel may replace tags on that channel.

Use an updated Get Streams API

We’ve also updated the existing Get Streams GET endpoint to return the set of all stream tags applied to the specified stream.

To get started

3 Likes

Awww yiss! This is great.

Now please allow extensions to have a tag that can be approved by Twitch so users can find streams that are tagged with that extension tag.

1 Like

Is the number of tag_ids limited like with user IDs on streams/user endpoints? Or can you specify as many as the URL length will allow and then paginate?

We support a maximum of 100 tag_ids (though because we use 36 character long UUIDs the practical limit is lower), and we do not support pagination when tag_ids are provided.

Anything over 5 makes it harder to see on the Twitch Website anyway.

Streamers probably should be going for quality over quantity when it comes to tags…

deposits two cents on the table

1 Like

Agreed! We actually enforce an upper limit of 5 stream tags on any given stream–it’s possible for there to be more due to tags that we automatically apply, but no one can apply more than 5 to a stream on their own :slight_smile:

So since there doesn’t seem to be an endpoint to filter tags by name, I assume the intended way to let users select tags is to fetch the entire list?

Yes, that’s correct! We are considering opening up an endpoint that will enable search by name in the future, but we do not have a timeline for this now.

I was primarily asking because this is clearly documented for other parameters but not for tag_ids. So my suggestion would be to include this information in the documentation.

Good catch, I’ll chat with the tech writer. Thanks for the feedback!

What would be quite useful as well is a way to only request is_auto=false tags, for example as an extra optional parameter for the /tags/streams endpoint. This would reduce the amount of requests needed to get a list of all tags that a user can set on their stream.

Thanks for the feedback! This is definitely something that we are considering for a future update.

I’ve updated the documentation to reflect that we support a maximum of 100 tag_ids, and we do not support pagination when tag_id is provided.

Thank you for the input!

1 Like

The streams API desperately needs filtering by tag_id, just as you can filter by game_id and user_id. I’m trying to sort through categories like Art and Music, and it takes far too many requests to find just a couple streams. I’m actually hitting the limit of my cloud host trying to scan through these categories. I don’t even dare try to check Just Chatting.

I mean, you can actually do this on the website, but not the API.

Please create a uservoice for this request https://twitch.uservoice.com/forums/310213-developers