Labels in the API

Labels are a resource of their own, with one endpoint for label-to-screen links and another for label-to-playlist links.

Endpoints

A label carries id, name, human_name, and type.

type uses the API’s own names for the three kinds of label: manual is a Custom label, screen is the automatic per-screen one, and all-screens is the All Screens system label.

human_name is the one to read when displaying a label: for a screen label it resolves to the screen’s current name, while name is the stored value.

Attaching is a POST to the relevant join table with a label_id and either a screen_id or a playlist_id.

See Get started and the v4.1 API reference.

MCP tools

Eight of the MCP tools are label tools, more than for any other resource:

label_list           label_create        label_update        label_delete
label_link_screen    label_unlink_screen
label_link_playlist  label_unlink_playlist

That weighting is not an accident. Screens are read-only through MCP, so linking a label is how an assistant changes what plays where. “Find every screen labelled warehouse and assign the safety rotation to them” is label_list then label_link_playlist.

See Tool reference.

Scripting a fleet change

The pattern that makes labels worth the trouble at scale:

1. List screens matching whatever condition you care about.
2. Attach a label to each.
3. Point one playlist at that label.

Step three is one call however many screens step two touched. That is the same property the dashboard gives you, available to a script.