# Labels in the API


> Labels are first-class in the API and the MCP tools, which makes them the lever for scripted fleet changes.
Labels are a resource of their own, with one endpoint for label-to-screen links and another for label-to-playlist links.

## Endpoints

| Path | What it holds |
| --- | --- |
| `/v4.1/labels` | The labels themselves |
| `/v4.1/labels/screens` | Which labels are on which screens |
| `/v4.1/labels/playlists` | Which labels target which playlists |

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

`type` uses the API's own names for the three [kinds of label](/docs/labels/reference/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](/docs/developers/api/overview/get-started/) and the [v4.1 API reference](https://developer.screenly.io/api_v4_1/).

## MCP tools

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

```text
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](/docs/developers/mcp/reference/tools/).

## 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.