Introducing the Tags API


#1

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


#2

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.


#3

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?


#4

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.


#5

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


#6

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:


#7

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?


#8

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.


#9

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.


#10

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


#11

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.


#12

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


#13

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!