# Screens

A screen is a display running Mestra Player.

A screen is a display running Mestra Player.

A key's Screens permission has three levels. Read: see screens, their schedule, health and proof of play, and screenshots and log bundles. Takedown: also stop screens and sites and pull ads, but can't start them again. Write: also pair, rename, remove and start screens, enrol them, change their settings, restart or reboot them, and switch their panels (power, hours, brightness and sound). A key can be limited to some sites and screen groups when it is made; see the [Player API overview](https://withmestra.com/docs/player/api/).

## The Screen object

A Mestra Player screen: a display that shows the organisation's published artwork, with its size, whether it is online and whether it is stopped.

- `id` (string (uuid), optional):
- `name` (string, optional):
- `width` (integer, optional): The screen's pixels; 0 until known.
- `height` (integer, optional):
- `timezone` (string, optional):
- `appVersion` (string, optional):
- `online` (boolean, optional):
- `lastSeenAt` (string (date-time), optional, nullable):
- `stopped` (boolean, optional):
- `stopShow` (string, optional): This screen's own choice of what it shows while stopped; `same` follows the organisation's. One of: `same`, `black`, `logo`, `image`, `video`.
- `siteStopShow` (string, optional): The choice of the screen's site (`same` follows the choice for all screens); empty when the screen has no site. One of: \`\`, `same`, `black`, `logo`, `image`.
- `stopShowFrom` (string, optional): Where what the screen shows while stopped comes from: its own choice (`screen`), its site's (`site`) or the choice for all screens (`org`). One of: `screen`, `site`, `org`.
- `unassigned` (boolean, optional): True for a screen that joined with an install key and no owner has named yet.
- `window` (object, optional, nullable): The window the screen plays in; null is the whole screen, and always null on a group and on an unassigned screen.
  - `profile` (object, optional): The panel profile the window comes from.
    - `id` (string, optional):
    - `name` (string, optional):
  - `x` (integer, optional):
  - `y` (integer, optional):
  - `w` (integer, optional):
  - `h` (integer, optional):
  - `rotation` (integer, optional):  One of: `0`, `90`, `180`, `270`.
  - `placeW` (integer, optional):
  - `placeH` (integer, optional):
- `frames` (object, optional): A screen's frames, always present: an empty list on a plain screen, version 0 on a group and on an unassigned screen. A booking can name a frame as it names a screen.
  - `version` (integer, optional): Send it back to change the frames.
  - `frames` (array of objects, optional):
    - `id` (string (uuid), optional):
    - `name` (string, optional):
    - `x` (integer, optional):
    - `y` (integer, optional):
    - `w` (integer, optional):
    - `h` (integer, optional):
    - `layer` (integer, optional):
    - `sound` (boolean, optional):
- `orgStopped` (boolean, optional): True while every screen is stopped: the organisation's own stop is on, or the organisation is halted (`orgHalt`).
- `transition` (string, optional): This screen's own change between ads; `same` follows the organisation's. One of: `same`, `cut`, `fade`.
- `h265` (boolean, optional): The screen reported it plays H.265.
- `html5` (boolean, optional): The screen reported it plays HTML5 packages.
- `decodeAt` (string (date-time), optional, nullable): When the screen's reported decoders last changed; null until it has reported.
- `decode` (array of objects, optional, nullable): What the screen says it decodes, as the server kept it: for each codec and frame rate, the largest picture it plays smoothly. `null` until it has reported; an empty list is a screen that reported and decodes none (H.264 still plays where the list holds no H.264). The screen's report is untrusted: entries outside the bounds are dropped.
  - `codec` (string, optional):  One of: `h264`, `h265`, `vp9`, `av1`.
  - `maxSide` (integer, optional): The longest side, in pixels.
  - `maxPixels` (integer (int64), optional): Width times height, in pixels.
  - `fps` (integer, optional): The frame-rate tier this entry covers. One of: `30`, `60`.
- `cantPlay` (array of objects, optional): The files of this screen's live bookings that it can't play, and why. Empty when it plays them all. `reason` is `no_codec` (`codec` is the one it lacks), `too_big` (`maxWidth` and `maxHeight` are the largest picture it decodes for the codec), `too_fast` (`maxFps` is its highest frame rate), `no_html5` (`detail` is why HTML5 is off) or `no_report` (the screen hasn't said what it plays).
  - `name` (string, optional): The booking's name.
  - `reason` (string, optional):  One of: `no_codec`, `too_big`, `too_fast`, `no_html5`, `no_report`.
  - `codec` (string, optional):  One of: `h264`, `h265`, `vp9`, `av1`.
  - `detail` (string, optional):
  - `maxWidth` (integer, optional):
  - `maxHeight` (integer, optional):
  - `maxFps` (integer, optional):
- `stopVideoCantPlay` (object, optional): Present when this screen is meant to show a stop video it can't play: it shows black instead. `name` is `stop video`; `reason` and the rest are as in `cantPlay`.
  - `name` (string, optional):
  - `reason` (string, optional):  One of: `no_codec`, `too_big`, `too_fast`, `no_html5`, `no_report`.
  - `codec` (string, optional):  One of: `h264`, `h265`, `vp9`, `av1`.
  - `detail` (string, optional):
  - `maxWidth` (integer, optional):
  - `maxHeight` (integer, optional):
  - `maxFps` (integer, optional):
- `html5Off` (string, optional): Why HTML5 is off on this screen, when it said: the player is starting (`starting`), the player hasn't started it (`shell_not_ready`), the network lock isn't confirmed (`net_jail`) or sound can't be kept off (`mute_unconfirmed`). Empty when HTML5 is on or no cause was given. One of: \`\`, `starting`, `shell_not_ready`, `net_jail`, `mute_unconfirmed`.
- `orgHalt` (string, optional): Why the organisation's screens are halted and black: `read_only` (the account is read-only; they start again when it is active) or `disabled` (disabled, or scheduled for deletion). Empty when they are not. One of: \`\`, `read_only`, `disabled`.
- `hardware` (object, optional): What the screen says it is (its own claim, never proof). `tpm` is true when it reported a TPM endorsement key; the key itself is never shown.
  - `manufacturer` (string, optional):
  - `model` (string, optional):
  - `serial` (string, optional):
  - `tpm` (boolean, optional):
  - `serialShared` (boolean, optional): True when many PCs report this serial (a placeholder this organisation's own screens show, or one staff confirmed). It identifies none of them, so the screen gets no "looks like" by serial. Omitted when false.
- `enrolledVia` (object, optional, nullable): The install key the screen joined with; null for a screen added with a code. `name` is shown only to a caller with the Screens write permission, and never to staff acting as the organisation.
  - `id` (string (uuid), optional):
  - `name` (string, optional):
- `enrolledAt` (string (date-time), optional): When the screen joined (paired or enrolled). It never changes; the unassigned pool is listed in this order.
- `opencrsRef` (string, optional, nullable): The OpenCRS screen this screen is the face of, or null.
- `looksLikeCount` (integer, optional): How many of the organisation's other screens (inside the caller's scope) may be this same machine: the same serial and maker, or the same TPM key. Only an unassigned screen and a set-up one are ever paired: two unassigned screens never count each other. Lists carry the count; one screen's own view also carries `looksLike`.
- `looksLike` (array of objects, optional): Only in one screen's own view (`GET /devices/{id}` and the answers to a change): the first 20 screens it may be the same machine as, in id order. `looksLikeCount` is the total; when there are more, `looksLikeNext` is the cursor to pass to `GET /devices/{id}/looks-like` as `after`.
  - `id` (string (uuid), optional):
  - `name` (string, optional):
  - `why` (string, optional): What the match rests on. Both are what the PC itself reported (its serial and maker, or its TPM key hash): a claim, not proof. Check the install key and the time it joined before you replace a screen with it. One of: `serial`, `tpm`.
- `looksLikeNext` (string, optional): Only in one screen's own view, and only when `looksLike` is not the whole list: the `after` for `GET /devices/{id}/looks-like`.
- `possibleCopy` (boolean, optional): True when the machine's identity changed since it enrolled in a way that looks like its files were copied to another machine. An owner clears it with `cloneChecked: true`.
- `copyProven` (boolean, optional): True when Mestra has found that this screen's identity is in use on another PC. A replace clears it, and so does the owner saying it is not a copy (cloneChecked).
- `keyCheck` (object, optional, nullable): A PC set up from a provisioning package plays nothing until its check that Windows' readable copy of the install key is gone has passed. `state` is `checking`, `failed` (the check could not finish; `reason` says why, and it tries again by itself) or `exposed` (it proved a readable copy of the key: revoke the key; `reason` names the places, with any piece of the key in a name masked). `since` is when the hold was first seen. Null when the screen is not held. `checking` and `failed`, and a failure's `reason`, are the PC's own report on its heartbeat: Mestra bounds and cleans the text but cannot check it, and a held PC is kept inert by its own agent (it is an unassigned pool row either way, which gets no content, commands or credentials). `exposed` is Mestra's own mark, set only from a report the server verified against the key the screen joined with.
  - `state` (string, optional):  One of: `checking`, `failed`, `exposed`.
  - `reason` (string, optional):
  - `since` (string (date-time), optional, nullable):
- `siteCode` (string, optional): The code of the site the screen is linked to; empty when it is not linked.
- `kind` (string, optional): `single` is a PC; `group` is a screen group: one screen made of several, with no PC of its own. One of: `single`, `group`.
- `group` (object, optional): On a member of a group (when the group is in your scope): which group and the member's place.
  - `id` (string (uuid), optional):
  - `name` (string, optional):
  - `position` (integer, optional):
- `members` (array of objects, optional): On a group: its screens, by place.
  - `id` (string (uuid), optional):
  - `name` (string, optional):
  - `position` (integer, optional):
  - `online` (boolean, optional):
- `layout` (object, optional): On a group: its rows and columns, the gap and size you gave, the canvas that comes to, and the `version` to send with a change.
  - `rows` (integer, optional):
  - `cols` (integer, optional):
  - `bezelMm` (number, optional, nullable):
  - `diagIn` (number, optional, nullable):
  - `canvasW` (integer, optional):
  - `canvasH` (integer, optional):
  - `gapPx` (integer, optional):
  - `cellW` (integer, optional):
  - `cellH` (integer, optional):
  - `placed` (boolean, optional):
  - `placing` (boolean, optional):
  - `version` (integer, optional):
  - `identifyUntil` (string (date-time), optional, nullable):
- `look` (boolean, optional): The screen needs a look: it last showed something other than what it was told to, or it has several displays and Mestra uses one.
- `syncState` (string, optional): On a placed group, in a paged list only: whether its screens are in step. One of: `placing`, `in_step`, `out_of_step`, `unknown`.
- `syncLate` (array of integers, optional): On a group that is out of step, in a paged list only: the positions of the members the reasons name, in order.
- `display` (object, optional, nullable): What the PC said about its displays: how many, the primary and whole desktop size, `notSpanned` (more than one display and Mestra shows on one), `spanned` (the graphics driver joins them into one) and `sizeChanged` (the size before its last change); `null` from a group and a PC that has not said.
  - `monitors` (integer, optional):
  - `primaryW` (integer, optional):
  - `primaryH` (integer, optional):
  - `virtualW` (integer, optional):
  - `virtualH` (integer, optional):
  - `notSpanned` (boolean, optional):
  - `spanned` (boolean, optional):
  - `sizeChanged` (object, optional, nullable):
    - `fromW` (integer, optional):
    - `fromH` (integer, optional):
    - `toW` (integer, optional):
    - `toH` (integer, optional):
- `sound` (string, optional, nullable): This screen's own sound setting; `null` follows its site. One of: `on`, `off`, `null`.
- `panelVolume` (integer, optional, nullable): This screen's own panel volume; `null` follows its site.
- `hours` (array of values, optional, nullable): This screen's own on and off times; `null` follows its site.
- `brightness` (array of values, optional, nullable): This screen's own brightness times; `null` follows its site.
- `location` (object, optional, nullable): This screen's own place; `null` follows its site.
  - `lat` (number, optional):
  - `lon` (number, optional):
  - `name` (string, optional):
  - `address` (string, optional):
  - `city` (string, optional):
  - `state` (string, optional):
  - `postcode` (string, optional):
- `site` (object, optional, nullable): The site the screen is linked to; null when it has none.
  - `key` (string, optional): The brand code.
  - `name` (string, optional):
- `now` (object, optional): What the screen is showing, from its last report. While the screen or the organisation is stopped, `state` is `stopped` and `entry` is null, whatever the screen last said. `off` means its panel is switched off. `entry` is null when the screen isn't showing an item or the item has been deleted.
  - `state` (string, optional):  One of: `playing`, `waiting`, `pairing`, `stopped`, `off`, `unknown`.
  - `entry` (object, optional, nullable):
    - `id` (string (uuid), optional):
    - `name` (string, optional):
    - `sha256` (string, optional): The entry's file. A screen that is offline or has not caught up may still be showing an earlier one.
    - `publicationId` (string (uuid), optional, nullable): The publication the item came from; null when the entry has no published item.
  - `since` (string (date-time), optional, nullable):
- `next` (object, optional, nullable): The item the screen shows after this one. Null when the screen is stopped or has not said.
  - `entry` (object, optional):
    - `id` (string (uuid), optional):
    - `name` (string, optional):
    - `sha256` (string, optional): The entry's file. A screen that is offline or has not caught up may still be showing an earlier one.
    - `publicationId` (string (uuid), optional, nullable): The publication the item came from; null when the entry has no published item.
- `lastShot` (object, optional): On a page of the screens list, for a screen with nothing booked now or next: its newest screenshot that has a small preview. Left out otherwise. `thumb` is the preview's address, which holds the shot's id and never changes.
  - `id` (string (uuid), optional):
  - `thumb` (string, optional):
  - `takenAt` (string (date-time), optional):
- `health` (object, optional): `online` is the live check (the screen called within the last 3 minutes). `presence` is the state the webhooks follow, moved by the screen's report and a once-a-minute sweep, so the two can differ for up to a minute.
  - `online` (boolean, optional):
  - `presence` (string, optional):  One of: `online`, `offline`.
  - `presenceSince` (string (date-time), optional, nullable):
  - `lastSeenAt` (string (date-time), optional, nullable):
  - `appVersion` (string, optional):
  - `cacheBytes` (integer (int64), optional, nullable): The size of the screen's file cache; null until it reports.
  - `issue` (object, optional): The screen's health line: what is wrong, or that it fixed itself, and what to do about it.
    - `pill` (string, optional):  One of: `Healthy`, `Fixed itself`, `Needs a look`, `Needs a visit`, `Offline`.
    - `title` (string, optional):
    - `fix` (string, optional):
    - `since` (string (date-time), optional, nullable): When the fault began, or when it fixed itself.
    - `code` (string, optional):
  - `uptime` (object, optional): The screen's last 30 days (its own days, to today) from the days Mestra has signed. Null fractions where no day was counted.
    - `last30d` (number, optional, nullable):
    - `last30dExSitePower` (number, optional, nullable): With the seconds lost to the site's power left out of both sides.
    - `trend` (object, optional): Uptime a day at a time: 30 days, oldest first, each the up seconds over the counted seconds of that day, cut (never rounded up) to four places; null where nothing was counted. On a screen in a paged list, on a site in the list of sites, and on an uptime answer for the default span.
      - `to` (string (date), optional): The last of the 30 days.
      - `days` (array of numbers, optional):
    - `today` (object, optional): On a page of the screens list: today so far in the screen's zone, from the hours it has sealed since midnight. Always partial. It is not in `trend`, `last30d` or any signed day. Left out until an hour has been sealed today.
      - `up` (number, optional, nullable): Up seconds over counted seconds of those hours, cut (never rounded up) to four places.
      - `hours` (integer, optional): The sealed hours it rests on.
      - `partial` (boolean, optional):
  - `lastMismatch` (object, optional, nullable): The last time the screen found a file that failed its check; `entries` are the entry ids (or `stopshow` for the stopped picture). Null when it never has.
    - `at` (string (date-time), optional):
    - `entries` (array of strings, optional):
  - `diag` (object, optional, nullable): What the screen's PC last reported about itself. Null for a group and for a screen that has not reported. Text the device wrote is not shown.
    - `reportedAt` (string (date-time), optional):
    - `diskFreeBytes` (integer (int64), optional, nullable):
    - `diskTotalBytes` (integer (int64), optional, nullable):
    - `memTotalBytes` (integer (int64), optional, nullable):
    - `memAvailBytes` (integer (int64), optional, nullable):
    - `playerRamBytes` (integer (int64), optional, nullable): The memory the player uses.
    - `tempC` (number, optional, nullable): The PC's temperature in degrees Celsius.
    - `clockOffsetMs` (integer, optional, nullable): How far the PC's clock is from the server's, in milliseconds.
    - `bootedAt` (string (date-time), optional, nullable):
    - `shellUp` (boolean, optional): Whether the player's shell is running.

```json
{
  "id": "string",
  "name": "string",
  "width": 0,
  "height": 0,
  "timezone": "string",
  "appVersion": "string",
  "online": false,
  "lastSeenAt": "string",
  "stopped": false,
  "stopShow": "same",
  "siteStopShow": "",
  "stopShowFrom": "screen",
  "unassigned": false,
  "frames": {
    "version": 0,
    "frames": [
      {
        "id": "string",
        "name": "string",
        "x": 0,
        "y": 0,
        "w": 0,
        "h": 0,
        "layer": 0,
        "sound": false
      }
    ]
  },
  "orgStopped": false,
  "transition": "same",
  "h265": false,
  "html5": false,
  "decodeAt": "string",
  "decode": [
    {
      "codec": "h264",
      "maxSide": 0,
      "maxPixels": 0,
      "fps": 30
    }
  ],
  "cantPlay": [
    {
      "name": "string",
      "reason": "no_codec",
      "codec": "h264",
      "detail": "string",
      "maxWidth": 0,
      "maxHeight": 0,
      "maxFps": 0
    }
  ],
  "stopVideoCantPlay": {
    "name": "string",
    "reason": "no_codec",
    "codec": "h264",
    "detail": "string",
    "maxWidth": 0,
    "maxHeight": 0,
    "maxFps": 0
  },
  "html5Off": "",
  "orgHalt": "",
  "hardware": {
    "manufacturer": "string",
    "model": "string",
    "serial": "string",
    "tpm": false,
    "serialShared": false
  },
  "enrolledAt": "string",
  "opencrsRef": "string",
  "looksLikeCount": 0,
  "looksLike": [
    {
      "id": "string",
      "name": "string",
      "why": "serial"
    }
  ],
  "looksLikeNext": "string",
  "possibleCopy": false,
  "copyProven": false,
  "keyCheck": {
    "state": "checking",
    "reason": "string",
    "since": "string"
  },
  "siteCode": "string",
  "kind": "single",
  "group": {
    "id": "string",
    "name": "string",
    "position": 0
  },
  "members": [
    {
      "id": "string",
      "name": "string",
      "position": 0,
      "online": false
    }
  ],
  "layout": {
    "rows": 0,
    "cols": 0,
    "bezelMm": 0,
    "diagIn": 0,
    "canvasW": 0,
    "canvasH": 0,
    "gapPx": 0,
    "cellW": 0,
    "cellH": 0,
    "placed": false,
    "placing": false,
    "version": 0,
    "identifyUntil": "string"
  },
  "look": false,
  "syncState": "placing",
  "syncLate": [
    0
  ],
  "display": {
    "monitors": 0,
    "primaryW": 0,
    "primaryH": 0,
    "virtualW": 0,
    "virtualH": 0,
    "notSpanned": false,
    "spanned": false,
    "sizeChanged": {
      "fromW": 0,
      "fromH": 0,
      "toW": 0,
      "toH": 0
    }
  },
  "sound": "on",
  "panelVolume": 0,
  "now": {
    "state": "playing",
    "since": "string"
  },
  "lastShot": {
    "id": "string",
    "thumb": "string",
    "takenAt": "string"
  },
  "health": {
    "online": false,
    "presence": "online",
    "presenceSince": "string",
    "lastSeenAt": "string",
    "appVersion": "string",
    "cacheBytes": 0,
    "issue": {
      "pill": "Healthy",
      "title": "string",
      "fix": "string",
      "since": "string",
      "code": "string"
    },
    "uptime": {
      "last30d": 0,
      "last30dExSitePower": 0,
      "trend": {
        "to": "string",
        "days": []
      },
      "today": {
        "up": 0,
        "hours": 0,
        "partial": false
      }
    }
  }
}
```

## List all screens

`GET /api/v1/player/devices`

Permission: Screens · Read.

Any member's session (viewer, editor or owner), or a key with the Screens permission. Lists the organisation's Mestra Player screens, oldest first. A screen is online when it called within the last 3 minutes. A key limited to some screens sees only those. `?site=<site code>` lists only the screens linked to that site; a site with none of your screens is 404 `unknown_site`. Each screen carries its `site`, what it is showing `now`, the item `next`, and its `health`. `health.online` is the live check (the screen called within 3 minutes); `health.presence` is the state the webhooks follow, moved by the heartbeat and a once-a-minute sweep, so the two can differ for up to a minute. While the screen or the organisation is stopped `now.state` is `stopped` and `next` is null, whatever the screen last said.

**Paged.** With `unassigned` or `key` the answer is a page instead, `{screens, total, next}`, in the order the screens joined: `total` counts every screen the filter matches, and `next` (null on the last page) is passed as `after` for the next page. This form is an editor's or an owner's (a viewer-role member is refused by role), and for a key that sees every screen (else 403 `screens_limited`); a bad `unassigned`, `limit` or `after` is 400 (`bad_unassigned`, `bad_limit`, `bad_after`). Without either filter, `limit` and `after` are ignored and the answer is the plain list.
Each row also carries the screen's `siteCode` (the code of the site it is linked to, or an empty string), and the screen's own `hours`, `brightness`, `sound`, `panelVolume` and `location` (`null` follows the
site), and any running power `override`. An editor's or an owner's own browser session, or an owner's key or grant with Screens · Write, sees more fields than this reference lists (the panel link, the update status); any other key does not.

### Parameters

- `site` (string, optional): A site code: list only the screens linked to it.
- `unassigned` (boolean, optional): Pages the list (see below): only screens nobody has named yet (true), or only the named ones (false).
- `key` (string (uuid), optional): Pages the list (see below): only the screens that joined with this install key. Needs the Screens write permission.
- `limit` (integer, optional): Screens in a page, at most 200 (50 when left out). With `unassigned` or `key`, at most 500 and the cursor is `after`. Alone it is ignored: the answer is every screen as an array.
- `after` (string, optional): With `unassigned` or `key`: the `next` of the page before. Ignored otherwise.
- `cursor` (string, optional): The `next` of the previous page. Pages the list, and only for the same filters and `sort`.
- `kind` (string, optional): Pages the list: only PCs, or only screen groups. One of: `single`, `group`.
- `status` (string, optional): Pages the list: a stopped screen counts as stopped only, not online or offline. One of: `online`, `offline`, `stopped`.
- `look` (string, optional): Pages the list: only screens that need a look. One of: `1`.
- `attention` (string, optional): Pages the list: only screens that need a person now (not stopped, and offline, showing black, with a fault open or needing a look). One of: `1`.
- `nosite` (string, optional): Pages the list: only screens linked to no site. Not with `site`. One of: `1`.
- `group` (string (uuid), optional): Pages the list: the members of one screen group. Members are otherwise left out of the list.
- `q` (string, optional): Pages the list: screens whose name or site name contains this, members of a group included.
- `sort` (string, optional): Pages the list: the order. Default name. Status puts offline first, then online, then stopped. One of: `name`, `site`, `status`.

### Returns

The screens, oldest first; with a filter, `sort` or `cursor`, one page as `{screens, next}` (`next` is null on the last page; pass it back as `cursor`); with `unassigned` or `key`, a page of them as `{screens, total, next}`.

### Errors

- 400 (`bad_unassigned`, `bad_limit`, `bad_after`): With `unassigned` or `key`: `bad_unassigned`, `bad_limit` or `bad_after`.
- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`, `screens_limited`): `wrong_key`: the key lacks the Screens permission this call needs; or `screens_limited`: the key is limited to some screens and this call acts on all of them.
- 404 (`not_connected`, `unknown_site`): `not_connected`, or `unknown_site` (with `?site=`, no screen in your scope is linked to that site).
- 409 (`api_off`, `integration_off`): `api_off` (an owner hasn't turned the API on), or `integration_off` (Mestra screens are off).
- 501: The player is not available on this server.

### Example request

```sh
curl --request GET \
  --url https://app.withmestra.com/api/v1/player/devices \
  --header "Authorization: Bearer $MESTRA_TOKEN"
```

## Retrieve a screen

`GET /api/v1/player/devices/{id}`

Permission: Screens · Read.

Any member's session (viewer, editor or owner), or a key with the Screens permission. Returns one screen, the same as its row in the list.

### Parameters

- `id` (string (uuid), required):

### Returns

The screen.

### Errors

- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`, `screens_limited`): `wrong_key`: the key lacks the Screens permission this call needs; or `screens_limited`: the key is limited to some screens and this call acts on all of them.
- 404 (`unknown_screen`, `not_connected`): `unknown_screen` (no such screen, or one this key can't see), or `not_connected`.
- 409 (`api_off`, `integration_off`): `api_off` (an owner hasn't turned the API on), or `integration_off` (Mestra screens are off).
- 501: The player is not available on this server.

### Example request

```sh
curl --request GET \
  --url https://app.withmestra.com/api/v1/player/devices/string \
  --header "Authorization: Bearer $MESTRA_TOKEN"
```

## Add a screen by its pairing code

`POST /api/v1/player/devices/claim`

Permission: Screens · Write.

Needs an owner's key or session. The code is the 8 letters the screen shows; dashes, spaces and case don't matter. Too many wrong codes are refused with 429. The screen collects its key on its next poll. Mestra screens must be on and connected. A key limited to some screens can't pair a new one (403 `screens_limited`).

**Two steps, if you want them.** Send `{code, confirm: false}` to look at the screen behind the code first: the answer is `{pending: {width, height, rotation, timezone, lastSeenAt, hardware, pairing}}` and nothing is written. `lastSeenAt` is when the screen last asked for its key (null if not yet) and is shown, never refused on; `hardware` is the screen's own claim (maker, model, serial, whether it has a TPM) and is unproven. Then send `{code, name, confirm: true, pairing}` with the `pairing` from the preview to add it. If the code was reissued to another screen in between, the answer is 409 `pairing_changed` and nothing is added. A wrong or expired code counts as a failed try, preview or not. A body with no `confirm` adds the screen at once, and then needs a `name` (a body with no name is 400); only an explicit `confirm: false` looks without adding. `confirm: true` without a `pairing` is 422.

### Parameters

- `code` (string, required):
- `name` (string, optional): Required unless `confirm` is `false`.
- `confirm` (boolean, optional): `false`: look at the screen without adding it. `true`: add it (needs `pairing`). Absent: add it at once, with no check (needs `name`).
- `pairing` (string, optional): From the preview; required with `confirm: true`.

### Returns

The screen was added (the screen as listed), or, for a preview, `{pending: {...}}` and nothing was written.

Returns the Screen object.

An object with:

- `pending` (object, required):
  - `width` (integer, optional):
  - `height` (integer, optional):
  - `rotation` (integer, optional):
  - `timezone` (string, optional):
  - `lastSeenAt` (string (date-time), optional, nullable):
  - `hardware` (object, optional):
    - `manufacturer` (string, optional):
    - `model` (string, optional):
    - `serial` (string, optional):
    - `tpm` (boolean, optional):
  - `pairing` (string, optional): Send it back with `confirm: true`.

### Errors

- 400: `name` is empty or has control, text-direction or zero-width characters (not needed for `confirm: false`).
- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`, `screens_limited`): `wrong_key`: the key lacks the Screens permission this call needs; or `screens_limited`: the key is limited to some screens and this call acts on all of them. A session below an owner's gets “Your role (\<role>) can't \<action>.”
- 404 (`not_connected`): `not_connected`.
- 409 (`api_off`, `integration_off`, `pairing_changed`): `api_off` (an owner hasn't turned the API on), `integration_off` (Mestra screens are off), or `pairing_changed` (the code now belongs to another screen: 'That code now belongs to another screen. Check the screen.').
- 413: “body exceeds limit (\<n> bytes)”.
- 422: The pairing letters are unknown, already used or have run out; or `confirm: true` came without a `pairing`.
- 429: Too many tries.
- 501: The player is not available on this server.

### Example request

```sh
curl --request POST \
  --url https://app.withmestra.com/api/v1/player/devices/claim \
  --header "Authorization: Bearer $MESTRA_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"code":"BCDF-GHJK","name":"Lobby north"}'
```

## Retrieve the screens a screen looks like

`GET /api/v1/player/devices/{id}/looks-like`

Permission: Screens · Read.

Needs an editor's or an owner's key or session. One screen's own view (`GET /devices/{id}`) lists the first 20 screens it may be the same machine as, with `looksLikeCount` the total and `looksLikeNext` a cursor when there are more. This returns the rest a page at a time: pass `looksLikeNext` as `after`. Screens come in id order, so none is repeated or missed while you page, and only screens inside your key's scope are counted.

### Parameters

- `id` (string (uuid), required):
- `after` (string (uuid), optional): The `looksLikeNext` of the view, or the `next` of the previous page. Omit for the first page.
- `limit` (integer, optional): How many to return; at most 500 are returned whatever is asked (use the cursor for the rest).

### Returns

A page of the screens it looks like.

An object with:

- `looksLike` (array of objects, required):
  - `id` (string (uuid), optional):
  - `name` (string, optional):
  - `why` (string, optional): What the match rests on. Both are what the PC itself reported (its serial and maker, or its TPM key hash): a claim, not proof. Check the install key and the time it joined before you replace a screen with it. One of: `serial`, `tpm`.
- `looksLikeCount` (integer, required): How many screens it looks like in all, not only on this page.
- `next` (string, required, nullable): The `after` for the next page; null on the last.

### Errors

- 400 (`bad_limit`, `bad_after`): `bad_limit` or `bad_after`.
- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`, `screens_limited`): `wrong_key`: the key lacks the Screens permission this call needs; or `screens_limited`: the key is limited to some screens and this call acts on all of them. A session below an owner's gets “Your role (\<role>) can't \<action>.”
- 404 (`unknown_screen`, `not_connected`): `unknown_screen` (no such screen, or one this key can't see), or `not_connected`.
- 409 (`api_off`, `integration_off`): `api_off` (an owner hasn't turned the API on), or `integration_off` (Mestra screens are off).
- 501: The player is not available on this server.

### Example request

```sh
curl --request GET \
  --url https://app.withmestra.com/api/v1/player/devices/string/looks-like \
  --header "Authorization: Bearer $MESTRA_TOKEN"
```

## Update a screen

`PATCH /api/v1/player/devices/{id}`

Permission: Screens · Write.

Needs an editor's or an owner's key or session, and an editor may only rename: `name` is the one field an editor can send, and any other field is refused `403` `owner_only` with that `field`, before anything changes (rename needs the Screens · Write permission on a key). At least one field. `stopShow` is `same` (as all screens), `black` or `logo` (the logo chosen for all screens; 409 `no_logo` until one is). A screen's own image is set by `POST /player/stop-image?device=`. Stopping or starting reaches the screen at once. A key that may only stop screens uses `POST /api/v1/player/devices/{id}/stop`; starting a screen needs this call with `stopped` false. `transition` is `cut`, `fade`, or `null` for the same as all screens: how this screen moves from one ad to the next.
For an owner's session or a key with the Screens write permission, `hours`, `brightness`, `sound` and
`panelVolume` are this screen's own settings: absent keeps them, `"same"` (or `null`) follows the site, and
a value replaces them. A plugin's app token may not change them (403 `session_only`). The answer shows
them, but never the panel link to a key.
`location` is the screen's own place, for Dynamic's `lat`, `lon`, `city`, `state` and `postcode` signals: absent
keeps it, `"same"` (or `null`) follows its site, and an object replaces it. Only an owner can change it, and a plugin's app token may not (403 `session_only`). A bad
one is 400 with `field` `location`.

### Parameters

- `id` (string (uuid), required):
- `name` (string, optional):
- `stopped` (boolean, optional):
- `stopShow` (string, optional):  One of: `same`, `black`, `logo`.
- `transition` (string, optional, nullable): `cut`, `fade`, or `null` for the same as all screens: how this screen moves from one ad to the next. One of: `cut`, `fade`, `null`.
- `hours` (one of, optional): `same`, or this screen's on and off times. A session, or a key with the Screens write permission (not a plugin's app token).
- `brightness` (one of, optional): `same`, or this screen's brightness times. A session, or a key with the Screens write permission (not a plugin's app token).
- `sound` (string, optional): `same` (the site's), `on` or `off`. A session, or a key with the Screens write permission (not a plugin's app token). One of: `same`, `on`, `off`.
- `panelVolume` (one of, optional): `same` (the site's), or 0 to 100. A session, or a key with the Screens write permission (not a plugin's app token).
- `location` (one of, optional): `same` (the site's), or this screen's own place. An owner only; not a plugin's app token.
- `frames` (object, optional): Replace the screen's frames: `version` is the `frames.version` you read, `frames` the whole set. A frame with an `id` keeps that frame and its bookings; one without is new; one left out is removed. Frames are judged against the screen's window, which comes from its panel profile. Only a named single screen that is in no group takes frames.
  - `version` (integer, required):
  - `frames` (array of objects, required):
    - `id` (string (uuid), optional): Leave out for a new frame.
    - `name` (string, required): Unique on the screen, in any case.
    - `x` (integer, required): From the window's top left, in the turned window's pixels.
    - `y` (integer, required):
    - `w` (integer, required):
    - `h` (integer, required):
    - `layer` (integer, optional): A higher layer is in front.
    - `sound` (boolean, optional): Only one frame on a screen can have sound.

### Returns

The screen as it is now.

### Errors

- 400 (`bad_frame`, `frame_outside_window`, `two_sound_frames`, `not_single`): Nothing to change, or a bad `name`, `stopShow`, `hours`, `brightness` or `frames` (with `field`). A frames refusal has a code: `bad_frame` (bad frame values, or two frames with one name), `frame_outside_window` (a frame not inside the turned window), `two_sound_frames` (more than one frame with sound), or `not_single` (frames on a group, on an unassigned screen, or on a screen in a group).
- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`, `screens_limited`): `wrong_key`: the key lacks the Screens permission this call needs; or `screens_limited`: the key is limited to some screens and this call acts on all of them. A session below an editor's gets “Your role (\<role>) can't \<action>.”
- 404 (`unknown_screen`, `not_connected`): `unknown_screen` (no such screen, or one this key can't see), or `not_connected`.
- 409 (`api_off`, `integration_off`, `no_logo`): `api_off` (an owner hasn't turned the API on), `integration_off` (Mestra screens are off), `no_logo`, `conflict` (the frames changed since `frames.version` was read), or `booked` (a frame change that would leave live or draft bookings the wrong shape or size: `bookings` lists them as “{id, name, publicationId}”).
- 413: “body exceeds limit (\<n> bytes)”.
- 501: The player is not available on this server.

### Example request

```sh
curl --request PATCH \
  --url https://app.withmestra.com/api/v1/player/devices/string \
  --header "Authorization: Bearer $MESTRA_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"name":"Lobby north","stopped":false}'
```

## Delete a screen

`DELETE /api/v1/player/devices/{id}`

Permission: Screens · Write.

Needs an owner's key or session. Deletes the screen: its key stops working at once, and a takedown still waiting for it counts it as `removed`. Its plays are kept, and so are the bookings that named it; nothing plays on it again.

### Parameters

- `id` (string (uuid), required):

### Returns

Removed.

### Errors

- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`, `screens_limited`): `wrong_key`: the key lacks the Screens permission this call needs; or `screens_limited`: the key is limited to some screens and this call acts on all of them. A session below an owner's gets “Your role (\<role>) can't \<action>.”
- 404 (`unknown_screen`, `not_connected`): `unknown_screen` (no such screen, or one this key can't see), or `not_connected`.
- 409 (`api_off`, `integration_off`): `api_off` (an owner hasn't turned the API on), or `integration_off` (Mestra screens are off).
- 501: The player is not available on this server.

### Example request

```sh
curl --request DELETE \
  --url https://app.withmestra.com/api/v1/player/devices/string \
  --header "Authorization: Bearer $MESTRA_TOKEN"
```

## List all brands a screen can be placed in

`GET /api/v1/player/brands`

Permission: Screens · Read.

Any member's session (viewer, editor or owner), or a key with the Screens permission and no limit to some screens. The brands of the organisation, by key and name and nothing else of their settings: the choice for placing a screen. A screen joins a brand with `POST /devices/assign`.

### Returns

The brands.

An object with:

- `brands` (array of objects, optional):
  - `key` (string, optional):
  - `name` (string, optional):

### Errors

- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`, `screens_limited`): `wrong_key` (the key lacks the Screens permission) or `screens_limited` (the key is limited to some screens).
- 404 (`not_connected`): `not_connected`.
- 409 (`api_off`, `integration_off`): `api_off` (an owner hasn't turned the API on), or `integration_off` (Mestra screens are off).

### Example request

```sh
curl --request GET \
  --url https://app.withmestra.com/api/v1/player/brands \
  --header "Authorization: Bearer $MESTRA_TOKEN"
```

## List all screens at a glance

`GET /api/v1/player/screens/quick`

Permission: Screens · Read.

Any member's session (viewer, editor or owner), or a key with the Screens permission. Returns a page of the organisation's screens, by name, each with its status (`online`, `offline`, `stopped` or `never`, which has not called in yet) and three 24-point series for the last 24 hours, oldest hour first: `online` (the share of the hour, 0 to 1, Mestra was hearing from the screen; null before it was added, and all null for one that has never called), `plays` (plays an hour) and `issues` (problems an hour). `kind` is `screen` or `group`; a group's figures are its members'. `windowStart` is the start of the first hour. It reads Mestra's own records, so it works whatever else is down. A key limited to some screens sees only those. `loopToday` is what the screen's loop plan puts on screen on its own local day, planned and not played (see its field); null when the screen has no plan for today. `grafanaUrl` is null unless hosted dashboards are set up.

### Parameters

- `limit` (integer, optional): Screens in the page.
- `offset` (integer, optional): Screens to skip.
- `id` (array of strings, optional): Only these screens or groups (repeat the parameter). An id that is not one of the caller's screens is left out of the answer; `limit` and `offset` are then ignored.

### Returns

The page.

An object with:

- `screens` (array of objects, required):
  - `id` (string (uuid), required):
  - `name` (string, required):
  - `kind` (string, required):  One of: `screen`, `group`.
  - `status` (string, required):  One of: `online`, `offline`, `stopped`, `never`.
  - `lastSeenAt` (string (date-time), required, nullable):
  - `online` (array of numbers, required):
  - `plays` (array of integers, required):
  - `issues` (array of integers, required):
  - `loopToday` (object, required, nullable): What the loop plan puts on screen on the screen's own local day. It is planned, not played: the screen logs no play for a gap and does not mark a fill, so these come from the plan, and a change during the day re-plans the whole day. Null when the screen has no plan for today or is stopped. A group's is its members' added together.
    - `paidFills` (integer, required): Turns smart fill added to the loop from paid bookings.
    - `houseFills` (integer, required): Turns smart fill added from house items.
    - `gaps` (integer, required): Gap turns (the stop show between items) when nothing else could play.
    - `gapSeconds` (integer, required): Total length of those gaps, in seconds.
  - `grafanaUrl` (string, required, nullable):
- `total` (integer, required): Screens in all, for paging.
- `limit` (integer, required):
- `offset` (integer, required):
- `windowStart` (string (date-time), required):
- `bucketSeconds` (integer, required):
- `grafanaUrl` (string, required, nullable):

### Errors

- 400: `limit` or `offset` is out of range (the answer names the `field`).
- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`): `wrong_key`: the key lacks the Screens permission this call needs.
- 404 (`not_connected`): `not_connected`.
- 409 (`api_off`, `integration_off`): `api_off` (an owner hasn't turned the API on), or `integration_off` (Mestra screens are off).
- 501: The player is not available on this server.

### Example request

```sh
curl --request GET \
  --url https://app.withmestra.com/api/v1/player/screens/quick \
  --header "Authorization: Bearer $MESTRA_TOKEN"
```

## Retrieve a screen's schedule

`GET /api/v1/player/devices/{id}/schedule`

Permission: Screens · Read.

Needs an editor's or owner's key or session. What the screen plays: `items`, its bookings in loop order, each with its dates, daypart window (`windowStart` and `windowEnd`, when it has one) and `timezone`, its `name` and `publicationId` (null when it has none). A group also answers `slots`, the plays from `from` to `to` (RFC 3339; default now and one loop, never more than 24 hours) with each `start` and `end`; a single screen's `slots` is null. No file address and no volume are given.

### Parameters

- `id` (string (uuid), required):
- `from` (string (date-time), optional): A group only; default now.
- `to` (string (date-time), optional): A group only; default one loop after `from`. Never more than 24 hours after it.

### Returns

The screen's schedule.

An object with:

- `screen` (object, required):
  - `id` (string (uuid), required):
  - `kind` (string, required):  One of: `single`, `group`.
- `items` (array of objects, required):
  - `entryId` (string (uuid), required):
  - `name` (string, required):
  - `publicationId` (string, required, nullable):
  - `bookingName` (string, required): What the booking is called: a content booking's own name, else `name`.
  - `status` (string, required):  One of: `draft`, `live`.
  - `campaign` (object, optional): Only when the booking is in a campaign.
    - `id` (string (uuid), optional):
    - `name` (string, optional):
  - `days` (array of strings, optional): Only when the booking plays on some weekdays.
  - `sha256` (string, required):
  - `mime` (string, required):
  - `durationMs` (integer, required):
  - `slots` (integer, required): How many times in a row it plays in each turn of the loop, as asked.
  - `turns` (integer, optional): How many turns the loop gives it when every item is live, which is what it does; `slots` is what was asked. The same as `slots` when the screen has no plan for that set. See `getMestraScreenLoop`.
  - `startDate` (string, required): YYYY-MM-DD in `timezone`.
  - `endDate` (string, required): YYYY-MM-DD in `timezone`, inclusive.
  - `windowStart` (string, optional): HH:MM; only when the booking has a daypart window.
  - `windowEnd` (string, optional): HH:MM.
  - `timezone` (string, required):
- `slots` (array of objects, required, nullable): A group only; null for a single screen.
  - `entryId` (string (uuid), required, nullable): Null for filler, a slot with no booking.
  - `name` (string, required):
  - `publicationId` (string, required, nullable):
  - `durationMs` (integer, required):
  - `start` (string (date-time), required):
  - `end` (string (date-time), required):

### Errors

- 400: `from` or `to` isn't a time, or `to` isn't after `from`.
- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`): `wrong_key`: the key lacks the Screens permission this call needs. A session below an editor's gets “Your role (\<role>) can't \<action>.”
- 404 (`unknown_screen`, `not_connected`): `unknown_screen` (no such screen, or one this key can't see), or `not_connected`.
- 409 (`api_off`, `integration_off`): `api_off` (an owner hasn't turned the API on), or `integration_off` (Mestra screens are off).
- 501: The player is not available on this server.

### Example request

```sh
curl --request GET \
  --url https://app.withmestra.com/api/v1/player/devices/string/schedule \
  --header "Authorization: Bearer $MESTRA_TOKEN"
```

## Retrieve the schedule across screens

`GET /api/v1/player/schedule`

Permission: Screens · Read.

Every screen's bookings over a range of days in one read, with what each screen is showing now and next. Any member or key that can read screens may call it. `from` and `to` are days (YYYY-MM-DD), both inclusive, at most 31 days apart. A screen lists each draft or live booking that overlaps the range, including one with no end date; `windowStart`, `windowEnd` and `days` narrow when it plays inside those days, in the booking's `timezone`. Without `site` or `screen` it answers every screen the caller can read (a group once, not its members); `site` limits it to one site's screens, `screen` to one screen. `now` and `next` are the same as on a screen in `getMestraScreens`.

### Parameters

- `from` (string (date), required): First day, YYYY-MM-DD.
- `to` (string (date), required): Last day, YYYY-MM-DD; not before `from`, at most 31 days after it.
- `site` (string, optional): A site's key. Not with `screen`.
- `screen` (string (uuid), optional): One screen. Not with `site`.

### Returns

The schedule.

An object with:

- `from` (string, required):
- `to` (string, required):
- `screens` (array of objects, required):
  - `id` (string (uuid), required):
  - `name` (string, required):
  - `kind` (string, required):  One of: `single`, `group`.
  - `site` (object, required, nullable):
    - `key` (string, optional):
    - `name` (string, optional):
  - `timezone` (string, required):
  - `now` (object, required): What the screen is showing: `state` (playing, stopped, unknown and so on), the `entry` when playing, and `since`.
  - `next` (object, required, nullable): `entry`: what comes after; null while stopped or unknown.
  - `entries` (array of objects, required):
    - `entryId` (string (uuid), required):
    - `name` (string, required):
    - `bookingName` (string, required):
    - `status` (string, required):  One of: `draft`, `live`.
    - `publicationId` (string, required, nullable):
    - `campaign` (object, optional):
      - `id` (string (uuid), optional):
      - `name` (string, optional):
    - `sha256` (string, required):
    - `mime` (string, required):
    - `durationMs` (integer, required):
    - `slots` (integer, required):
    - `startDate` (string, required): YYYY-MM-DD in `timezone`; empty for no start.
    - `endDate` (string, required): YYYY-MM-DD in `timezone`, inclusive; empty for no end.
    - `days` (array of strings, optional):
    - `windowStart` (string, optional):
    - `windowEnd` (string, optional):
    - `timezone` (string, required):

### Errors

- 400 (`range_too_long`): `from` or `to` isn't a day, `to` is before `from`, both `site` and `screen` were given, or `range_too_long` (more than 31 days).
- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`): `wrong_key`: the key lacks the Screens permission this call needs.
- 404 (`unknown_screen`, `unknown_site`, `not_connected`): `unknown_screen` (no such screen, or one this key can't see), `unknown_site`, or `not_connected`.
- 409 (`api_off`, `integration_off`): `api_off` (an owner hasn't turned the API on), or `integration_off` (Mestra screens are off).
- 501: The player is not available on this server.

### Example request

```sh
curl --request GET \
  --url 'https://app.withmestra.com/api/v1/player/schedule?from=string&to=string' \
  --header "Authorization: Bearer $MESTRA_TOKEN"
```

## Update many screens at once

`POST /api/v1/player/devices/assign`

Permission: Screens · Write.

Needs the Screens write permission and an owner. Each item names a screen by its `device` id or by its hardware `serial` (matched among all the organisation's screens), then says what to set: `name`, `site` (the brand's code; `""` unlinks the screen) and `opencrsRef` (`""` clears it). A field left out is left alone. Writing a name or a brand takes the screen out of the unassigned pool. All or nothing: every row is judged first, and if any row's `outcome` is not `assigned`, `unchanged` or `skipped` nothing is written and the answer is 422 with every row's result. With `dryRun: true` the rows are judged exactly as for a real run and nothing is written. With `unassignedOnly: true` a row whose screen has been set up since it was picked is `not_unassigned` and the answer is 409. Outcomes: `assigned`, `unchanged`, `skipped`, `no_match`, `duplicate_serial`, `bad_name`, `unknown_site`, `unknown_opencrs`, `opencrs_taken`, `twice_in_batch`, `nothing_to_change`, `on_screens` (a screen showing a booking cannot be moved to another brand or unlinked), `spreadsheet_number`, `not_unassigned`, `key_check`. `batch` is empty when nothing was written. A key limited to some screens may set up only screens it holds, each named by its `device` id (not by `serial`), and link them only to the sites in its limit; any other row refuses the whole request with 403 `screens_limited` and nothing is judged or written. A key limited to groups only has no site to link to. It may unlink a screen it holds (`site` `""`) and clear an OpenCRS tie, but not set one: a row with a non-empty `opencrsRef` is refused the same way.

### Parameters

- `items` (array of objects, required):
  - `device` (string (uuid), optional): The screen's id. Used before `serial` when both are given.
  - `serial` (string, optional): The hardware serial the screen reported.
  - `name` (string, optional):
  - `site` (string, optional): A brand's code; empty unlinks.
  - `opencrsRef` (string, optional): An OpenCRS screen ref; empty clears.
- `skipUnmatched` (boolean, optional): Skip rows that match no screen instead of refusing the batch.
- `dryRun` (boolean, optional):
- `unassignedOnly` (boolean, optional): The screens were picked from the Unassigned pool: a row whose screen has been set up since is `not_unassigned` and refuses the batch with 409.

### Returns

Written (`applied: true`, with the `batch`), or a dry run that would be written (`applied: false`).

An object with:

- `batch` (string (uuid), optional): Names the batch that was written; empty when nothing was.
- `applied` (boolean, required):
- `dryRun` (boolean, optional):
- `ignoredColumns` (array of strings, optional): Only from assign-csv: the file's column headings that were not read.
- `results` (array of objects, required):
  - `row` (integer, required): The item's 1-based position in the request.
  - `device` (string (uuid), optional): The screen the row resolved to.
  - `outcome` (string, required):  One of: `assigned`, `unchanged`, `skipped`, `no_match`, `duplicate_serial`, `bad_name`, `unknown_site`, `unknown_opencrs`, `opencrs_taken`, `twice_in_batch`, `nothing_to_change`, `on_screens`, `spreadsheet_number`, `not_unassigned`, `key_check`.
  - `message` (string, optional):
  - `screen` (object, optional): The screen the row matched, as the row found it, so a dry run shows what Apply would change: check that the key it joined with, when it joined and its hardware are the ones you expect (a serial is only what the screen says). Left out when the row matched no screen.
    - `name` (string, optional):
    - `unassigned` (boolean, optional):
    - `enrolledAt` (string (date-time), optional):
    - `enrolledVia` (object, optional, nullable):
      - `id` (string (uuid), optional):
      - `name` (string, optional):
    - `hardware` (object, optional):
      - `manufacturer` (string, optional):
      - `model` (string, optional):
      - `serial` (string, optional):
      - `tpm` (boolean, optional):
    - `possibleCopy` (boolean, optional):

### Errors

- 400: No items (`field` is `items`).
- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`, `screens_limited`): `wrong_key`, `screens_limited`, or a role below an owner's.
- 404 (`not_connected`): `not_connected`.
- 409 (`api_off`, `integration_off`, `too_many_links`, `opencrs_taken`, `on_screens`, `unknown_site`, `not_unassigned`): `api_off` (an owner hasn't turned the API on), or `integration_off`; `too_many_links`; a change that landed first (an answer with `results`, where the row that lost is `opencrs_taken`, `on_screens` or `unknown_site`); or, with `unassignedOnly`, a row that is `not_unassigned` (an answer with `results`; nothing written, dry run or not).
- 413: “body exceeds limit (\<n> bytes)”.
- 422: A row refused the batch; nothing was written. `results` has every row.
- 501: The player is not available on this server.

### Example request

```sh
curl --request POST \
  --url https://app.withmestra.com/api/v1/player/devices/assign \
  --header "Authorization: Bearer $MESTRA_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"items":[{"device":"7c1e5f2a-3b4d-4e6f-8a9b-0c1d2e3f4a5b","name":"Lobby north","site":"ABC"},{"serial":"5CD1234XYZ","name":"Lobby south"}]}'
```

## Update screens from a CSV

`POST /api/v1/player/devices/assign-csv`

Permission: Screens · Write.

Needs the Screens write permission and an owner. The same as assigning many screens at once (same permission, all-or-nothing rule, dry run, outcomes and statuses), with the rows read from a CSV in `csv`. The first row is a header, matched without regard to case: `serial`, `device`, `name`, `site` (or the older `centre`) and `opencrs`; the file needs `serial` or `device`. Other columns are ignored and listed in `ignoredColumns` (the exported file's `manufacturer`, `model`, `enrolled` and `key` among them). A BOM and CRLF line ends are accepted. In a cell, an empty value leaves the field alone and exactly `-` clears it. A key limited to some screens may set up only screens it holds, each named by its `device` id (not by `serial`), and link them only to the sites in its limit; any other row refuses the whole request with 403 `screens_limited` and nothing is judged or written. A key limited to groups only has no site to link to. It may unlink a screen it holds (`site` `""`) and clear an OpenCRS tie, but not set one: a row with a non-empty `opencrsRef` is refused the same way.

### Parameters

- `csv` (string, required):
- `skipUnmatched` (boolean, optional):
- `dryRun` (boolean, optional):

### Returns

Written, or a dry run that would be written.

An object with:

- `batch` (string (uuid), optional): Names the batch that was written; empty when nothing was.
- `applied` (boolean, required):
- `dryRun` (boolean, optional):
- `ignoredColumns` (array of strings, optional): Only from assign-csv: the file's column headings that were not read.
- `results` (array of objects, required):
  - `row` (integer, required): The item's 1-based position in the request.
  - `device` (string (uuid), optional): The screen the row resolved to.
  - `outcome` (string, required):  One of: `assigned`, `unchanged`, `skipped`, `no_match`, `duplicate_serial`, `bad_name`, `unknown_site`, `unknown_opencrs`, `opencrs_taken`, `twice_in_batch`, `nothing_to_change`, `on_screens`, `spreadsheet_number`, `not_unassigned`, `key_check`.
  - `message` (string, optional):
  - `screen` (object, optional): The screen the row matched, as the row found it, so a dry run shows what Apply would change: check that the key it joined with, when it joined and its hardware are the ones you expect (a serial is only what the screen says). Left out when the row matched no screen.
    - `name` (string, optional):
    - `unassigned` (boolean, optional):
    - `enrolledAt` (string (date-time), optional):
    - `enrolledVia` (object, optional, nullable):
      - `id` (string (uuid), optional):
      - `name` (string, optional):
    - `hardware` (object, optional):
      - `manufacturer` (string, optional):
      - `model` (string, optional):
      - `serial` (string, optional):
      - `tpm` (boolean, optional):
    - `possibleCopy` (boolean, optional):

### Errors

- 400: The file is empty, is not valid CSV, has no `serial` or `device` column or has no rows (`field` is `csv`).
- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`, `screens_limited`): `wrong_key`, `screens_limited`, or a role below an owner's.
- 404 (`not_connected`): `not_connected`.
- 409 (`api_off`, `integration_off`, `too_many_links`, `try_again`): `api_off` (an owner hasn't turned the API on), or As assign: `integration_off`, `too_many_links`, `try_again`, or a change that landed first.
- 413: “body exceeds limit (\<n> bytes)”.
- 422: A row refused the batch; nothing was written.
- 501: The player is not available on this server.

### Example request

```sh
curl --request POST \
  --url https://app.withmestra.com/api/v1/player/devices/assign-csv \
  --header "Authorization: Bearer $MESTRA_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"csv":"serial,name,site\r\n5CD1234XYZ,Lobby south,ABC\r\n","dryRun":true}'
```

## Download screens as CSV

`GET /api/v1/player/devices.csv`

Permission: Screens · Read.

Needs the Screens read permission and an editor. Every screen the filter matches, as a CSV download with no page limit. The header row is `device,serial,manufacturer,model,enrolled,key,name,site,opencrs`. The `key` column (install key names) is filled only for an owner or a key with the Screens write permission. A cell that starts with `=`, `+`, `-`, `@`, a tab or a carriage return begins with `'` so a spreadsheet won't run it; uploading the file back takes that `'` off again. It streams: if it fails part-way the connection is cut without a clean end, so treat a download that ends in an error as incomplete. A key limited to some screens gets the rows of those screens (and the members of its groups) only.

### Parameters

- `unassigned` (boolean, optional): Only screens nobody has named yet (true), or only the named ones (false).

### Returns

The screens, as CSV.

### Errors

- 400 (`bad_unassigned`): `bad_unassigned`.
- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`, `screens_limited`): `wrong_key`, `screens_limited`, or a role below an editor's.
- 404 (`not_connected`): `not_connected`.
- 409 (`api_off`, `integration_off`): `api_off` (an owner hasn't turned the API on), or `integration_off`.
- 501: The player is not available on this server.

### Example request

```sh
curl --request GET \
  --url https://app.withmestra.com/api/v1/player/devices.csv \
  --header "Authorization: Bearer $MESTRA_TOKEN"
```

## Update a screen to use a new player

`POST /api/v1/player/devices/{id}/replace`

Permission: Screens · Write.

Needs the Screens write permission and an owner. A machine was re-imaged and joined again as a new, unset-up player; this puts the old screen onto it. The old screen keeps its id, name, site, layout, bookings and plays; it takes the new player's key and everything the device reported. The new player's own entry is removed, and the old machine's key stops working. Answers 409 `replace_not_new` if the new player has been set up, `replace_online` if the old screen called in within the last 3 minutes (send `evenIfOnline` to go on), `replace_copy` if the new player is flagged as a possible copy (send `evenIfCopy`), `replace_held` if the new player is still held by its install key check (send `evenIfHeld`), or `replace_key` if the new player joined with another install key than the old screen did (send `evenIfKey`). Both ids must be screens of this organisation, else 404 `unknown_screen`. Repeating a call that already succeeded answers 200 again and changes nothing. A key limited to some screens must hold both screens, else 404 `unknown_screen`.

### Parameters

- `id` (string (uuid), required): The new player: a screen that joined with an install key and has not been set up.
- `replaces` (string (uuid), required): The screen being replaced; it stays.
- `evenIfOnline` (boolean, optional):
- `evenIfCopy` (boolean, optional):
- `evenIfKey` (boolean, optional):
- `evenIfHeld` (boolean, optional):

### Returns

The kept screen, now on the new player.

### Errors

- 400: `replaces` missing, or the same screen.
- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`): `403` for a role below the route's minimum (“Your role (\<role>) can't \<action>.”, or “Choose an organisation first.”), or, for an API key without the permission this call needs, code `wrong_key` with “This key needs the \<Area> · \<Read|Write> permission.” (for example “This key needs the Reviews · Write permission.”), or “This key can't do that.” for a call only the Mestra apps make.
- 404 (`unknown_screen`, `not_connected`): `unknown_screen`, or `not_connected`.
- 409 (`api_off`, `replace_not_new`, `replace_online`, `replace_copy`, `replace_held`, `replace_key`, `try_again`, `integration_off`): `api_off` (an owner hasn't turned the API on), or `replace_not_new`, `replace_online`, `replace_copy`, `replace_held`, `replace_key`, `try_again`, or `integration_off`.
- 413: “body exceeds limit (\<n> bytes)”.
- 501: The player is not available on this server.

### Example request

```sh
curl --request POST \
  --url https://app.withmestra.com/api/v1/player/devices/string/replace \
  --header "Authorization: Bearer $MESTRA_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"replaces":"5e2c8a40-91d7-4f63-b0a8-7d14c9e2f365"}'
```

## Delete many screens

`POST /api/v1/player/devices/remove`

Permission: Screens · Write.

Needs the Screens write permission and an owner. All or nothing: if any id is not a screen of this organisation, nothing is removed and the answer is 404 `unknown_screen` with the first such id in `device`. A repeated id counts once. With `unassignedOnly: true`, if any of the screens has been set up since it was picked nothing is removed and the answer is 409 `not_unassigned` with those screens' ids in `devices`. Each removed screen's key stops working at once. A key limited to some screens may remove only screens it holds: if any named screen is outside its scope the answer is 403 `screens_limited` and nothing is removed.

### Parameters

- `devices` (array of strings, required):
- `unassignedOnly` (boolean, optional): Remove only if every screen is still unassigned; otherwise 409 `not_unassigned` and nothing is removed.

### Returns

Removed.

An object with:

- `removed` (integer, required):

### Errors

- 400: No devices (`field` is `devices`).
- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`): `403` for a role below the route's minimum (“Your role (\<role>) can't \<action>.”, or “Choose an organisation first.”), or, for an API key without the permission this call needs, code `wrong_key` with “This key needs the \<Area> · \<Read|Write> permission.” (for example “This key needs the Reviews · Write permission.”), or “This key can't do that.” for a call only the Mestra apps make.
- 404 (`unknown_screen`, `not_connected`): `unknown_screen` (with `device`), or `not_connected`.
- 409 (`api_off`, `integration_off`, `not_unassigned`): `api_off` (an owner hasn't turned the API on), or `integration_off`, or `not_unassigned` (with `unassignedOnly`; `devices` lists the screens set up since they were picked).
- 413: “body exceeds limit (\<n> bytes)”.
- 501: The player is not available on this server.

### Example request

```sh
curl --request POST \
  --url https://app.withmestra.com/api/v1/player/devices/remove \
  --header "Authorization: Bearer $MESTRA_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"devices":["0b9a5f1e-6d3c-4b7a-9f21-3c8e5d7a1b42"],"unassignedOnly":true}'
```

## Update a screen's power

`POST /api/v1/player/devices/{id}/power`

Permission: Screens · Write.

Needs the Screens write permission and an owner. `power` is `on`, `off` or `schedule`: `on` and `off` hold the panel that way until `until` (a future time) or, without it, until changed; `schedule` clears the hold and goes back to the screen's on and off times. The screen is told at once. A screen's power may be changed a limited number of times an hour (429). A key limited to some screens may act only on its own (404 `unknown_screen` for others). A key with only the Screens read or takedown permission cannot do this.

### Parameters

- `id` (string (uuid), required):
- `power` (string, required):  One of: `on`, `off`, `schedule`.
- `until` (string (date-time), optional): In the future. Only with `on` or `off`; without it the hold lasts until changed.

### Returns

The screen as it is now.

### Errors

- 400: A bad `power`, or an `until` that is not a future time (with `field`).
- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`, `screens_limited`): `wrong_key`, `screens_limited`, or a role below an owner's.
- 404 (`unknown_screen`, `not_connected`): `unknown_screen`, or `not_connected`.
- 409 (`api_off`, `integration_off`): `api_off` (an owner hasn't turned the API on), or `integration_off`.
- 413: “body exceeds limit (\<n> bytes)”.
- 429 (`rate_limited`): `rate_limited`: the power was changed too often in the last hour (`Retry-After` says when to try again).
- 501: The player is not available on this server.

### Example request

```sh
curl --request POST \
  --url https://app.withmestra.com/api/v1/player/devices/string/power \
  --header "Authorization: Bearer $MESTRA_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"power":"off","until":"2026-11-12T08:00:00Z"}'
```
