# Sites

A site is a place that screens are linked to, such as a shopping centre or a store. A site has its own time zone, on and off times, brightness and location, and a key can be limited to some sites.

A site is a place that screens are linked to, such as a shopping centre or a store. A site has its own time zone, on and off times, brightness and location, and a key can be limited to some sites.

## The Site object

A site: its details, a count of its screens by state, and the screens linked to it.

- `site` (object, optional):
  - `key` (string, optional): The brand code.
  - `name` (string, optional):
- `summary` (object, optional): A site's screens by state. A stopped screen is also counted online or offline.
  - `key` (string, optional, nullable): The site code; null for the row of screens linked to no site.
  - `name` (string, optional, nullable):
  - `screens` (integer, optional):
  - `online` (integer, optional):
  - `offline` (integer, optional):
  - `stopped` (integer, optional):
  - `playing` (integer, optional): Online screens that are not stopped and last reported showing an item.
  - `uptime` (object, optional): The site's screens' last 30 days added up (up seconds over counted seconds, never an average of the screens' figures). 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):
  - `grafanaUrl` (string, optional, nullable): Opens the site's dashboard in the organisation's hosted Grafana, signed in by a hand-off from the viewer. Null unless hosted dashboards are set up, and for the row with no site.
- `screens` (array of objects, optional):
  - `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
{
  "site": {
    "key": "string",
    "name": "string"
  },
  "summary": {
    "key": "string",
    "name": "string",
    "screens": 0,
    "online": 0,
    "offline": 0,
    "stopped": 0,
    "playing": 0,
    "uptime": {
      "last30d": 0,
      "last30dExSitePower": 0,
      "trend": {
        "to": "string",
        "days": []
      }
    },
    "grafanaUrl": "string"
  },
  "screens": [
    {
      "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": []
      },
      "orgStopped": false,
      "transition": "same",
      "h265": false,
      "html5": false,
      "decodeAt": "string",
      "decode": [
        {
          "codec": "h264",
          "fps": 30
        }
      ],
      "cantPlay": [
        {
          "reason": "no_codec",
          "codec": "h264"
        }
      ],
      "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": [
        {
          "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": [
        {}
      ],
      "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": {}
      },
      "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"
        },
        "uptime": {}
      }
    }
  ]
}
```

## List all sites

`GET /api/v1/player/sites`

Permission: Screens · Read.

Any member's session (viewer, editor or owner), or a key with the Screens permission. A site is a brand: the site a screen is linked to. Lists each site with at least one of your Mestra screens, by name, with counts over the screens a key can see, then one row with a null `key` for screens linked to no site (left out when there are none). `online` and `offline` split the screens by the live 3-minute check; `stopped` counts screens stopped on their own or with the organisation (a stopped screen is also online or offline); `playing` counts online screens that are not stopped and last reported showing an item.

### Returns

The sites.

A list of objects, each with:

- `key` (string, optional, nullable): The site code; null for the row of screens linked to no site.
- `name` (string, optional, nullable):
- `screens` (integer, optional):
- `online` (integer, optional):
- `offline` (integer, optional):
- `stopped` (integer, optional):
- `playing` (integer, optional): Online screens that are not stopped and last reported showing an item.
- `uptime` (object, optional): The site's screens' last 30 days added up (up seconds over counted seconds, never an average of the screens' figures). 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):
- `grafanaUrl` (string, optional, nullable): Opens the site's dashboard in the organisation's hosted Grafana, signed in by a hand-off from the viewer. Null unless hosted dashboards are set up, and for the row with no site.

### Errors

- 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/sites \
  --header "Authorization: Bearer $MESTRA_TOKEN"
```

## Retrieve a site

`GET /api/v1/player/sites/{site}`

Permission: Screens · Read.

Any member's session (viewer, editor or owner), or a key with the Screens permission. One site: its summary, as in the list, and its screens, each as in the screens list. A key limited to some screens sees and counts only those.

### Parameters

- `site` (string, required): The brand code.

### Returns

The site.

### Errors

- 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_site`, `not_connected`): `unknown_site` (no screen in your scope is linked to that site, or there is no such 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/sites/string \
  --header "Authorization: Bearer $MESTRA_TOKEN"
```

## Create a site

`POST /api/v1/player/sites`

Permission: Screens · Write.

Needs the Screens write permission and an editor. Makes a site for screens: the same record as a brand in Mestra, with a name and a code.

### Parameters

- `code` (string, required):
- `name` (string, required):

### Returns

The site.

An object with:

- `code` (string, optional):
- `name` (string, optional):

### Errors

- 400: The name or the key isn't acceptable.
- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`, `plan_refused`): `wrong_key` (the key or role can't do this), a key limited to some screens, or `plan_refused`.
- 404 (`not_connected`): `not_connected`.
- 409 (`api_off`, `integration_off`): The code is taken, or `api_off` or `integration_off`.

### Example request

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

## Retrieve a site's times, brightness and sound

`GET /api/v1/player/sites/{site}/control`

Permission: Screens · Read.

Needs the Screens read permission and an owner. A site is a brand's code that Mestra screens are linked to. Returns its time zone, on and off times, brightness steps, at-screen setting, sound, panel volume and location (`null` means not chosen) and the screens linked to it. A screen's panel link is not shown. A key limited to some screens gets 403 `screens_limited` unless it holds every screen linked to the site.

### Parameters

- `site` (string, required): A site code with at least one Mestra screen linked to it (URL-encoded).

### Returns

The site's settings and the screens linked to it.

An object with:

- `timezone` (string, optional, nullable):
- `hours` (array of values, optional, nullable): On intervals in the screen's zone. An empty list (or none) means no hours: Mestra won't turn the panel on or off, and the page plays.
- `brightness` (array of values, optional, nullable): Brightness steps; each holds until the next, wrapping the day. An empty list never sets brightness.
- `atScreen` (string, optional, nullable):  One of: `restore`, `leave`, `null`.
- `sound` (string, optional, nullable): `null` is not chosen, which plays muted. One of: `on`, `off`, `null`.
- `panelVolume` (integer, optional, nullable):
- `location` (object, optional, nullable): Where the site is; `null` is not set.
  - `lat` (number, optional):
  - `lon` (number, optional):
  - `name` (string, optional):
  - `address` (string, optional):
  - `city` (string, optional):
  - `state` (string, optional):
  - `postcode` (string, optional):
- `devices` (array of objects, optional): The Mestra screens linked to the site.
  - `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.

### 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`, `screens_limited`, or a role below an owner's.
- 404 (`unknown_site`, `not_connected`): `unknown_site` (no Mestra screen of the organisation is linked to that site), or `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/sites/string/control \
  --header "Authorization: Bearer $MESTRA_TOKEN"
```

## Update a site's times, brightness or sound

`PUT /api/v1/player/sites/{site}/control`

Permission: Screens · Write.

Needs the Screens write permission and an owner. An absent field is kept; an explicit `null` clears it; `{}` changes nothing. Fields: `timezone`, `hours`, `brightness`, `atScreen` (`restore` or `leave`), `sound` (the string `on` or `off`, or `null`), `panelVolume` and `location` (an object, or `null` to clear). The site's screens are told at once. A key limited to some screens gets 403 `screens_limited` unless it holds every screen linked to the site.

### Parameters

- `site` (string, required): A site code with at least one Mestra screen linked to it (URL-encoded).
- `timezone` (string, optional, nullable): An IANA zone name, like `Australia/Sydney`.
- `hours` (array of values, optional, nullable): On intervals in the screen's zone. An empty list (or none) means no hours: Mestra won't turn the panel on or off, and the page plays.
- `brightness` (array of values, optional, nullable): Brightness steps; each holds until the next, wrapping the day. An empty list never sets brightness.
- `atScreen` (string, optional, nullable):  One of: `restore`, `leave`, `null`.
- `sound` (string, optional, nullable): Sound at the site's screens. Unset plays muted. One of: `on`, `off`, `null`.
- `panelVolume` (integer, optional, nullable): The panel's own volume; `null` leaves the panel as set.
- `location` (object, optional, nullable): Where the site is; its screens use it unless they have their own. `null` clears it.
  - `lat` (number, optional):
  - `lon` (number, optional):
  - `name` (string, optional):
  - `address` (string, optional):
  - `city` (string, optional):
  - `state` (string, optional):
  - `postcode` (string, optional):

### Returns

The site as it is now.

An object with:

- `timezone` (string, optional, nullable):
- `hours` (array of values, optional, nullable): On intervals in the screen's zone. An empty list (or none) means no hours: Mestra won't turn the panel on or off, and the page plays.
- `brightness` (array of values, optional, nullable): Brightness steps; each holds until the next, wrapping the day. An empty list never sets brightness.
- `atScreen` (string, optional, nullable):  One of: `restore`, `leave`, `null`.
- `sound` (string, optional, nullable): `null` is not chosen, which plays muted. One of: `on`, `off`, `null`.
- `panelVolume` (integer, optional, nullable):
- `location` (object, optional, nullable): Where the site is; `null` is not set.
  - `lat` (number, optional):
  - `lon` (number, optional):
  - `name` (string, optional):
  - `address` (string, optional):
  - `city` (string, optional):
  - `state` (string, optional):
  - `postcode` (string, optional):
- `devices` (array of objects, optional): The Mestra screens linked to the site.
  - `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.

### Errors

- 400: A setting that is not valid, or not a site setting (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_site`, `not_connected`): `unknown_site`, 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)”.
- 501: The player is not available on this server.

### Example request

```sh
curl --request PUT \
  --url https://app.withmestra.com/api/v1/player/sites/string/control \
  --header "Authorization: Bearer $MESTRA_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"timezone":"Australia/Sydney","sound":"on"}'
```

## Update the power of a site's screens

`POST /api/v1/player/sites/{site}/power`

Permission: Screens · Write.

Needs the Screens write permission and an owner. `power` is `on`, `off` or `schedule`, as for one screen, applied to every screen linked to the site now. `until` must be in the future. A site's power may be changed a limited number of times an hour (429). A key limited to some screens gets 403 `screens_limited` unless it holds every screen linked to the site.

### Parameters

- `site` (string, required): A site code with at least one Mestra screen linked to it (URL-encoded).
- `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 site as it is now.

An object with:

- `timezone` (string, optional, nullable):
- `hours` (array of values, optional, nullable): On intervals in the screen's zone. An empty list (or none) means no hours: Mestra won't turn the panel on or off, and the page plays.
- `brightness` (array of values, optional, nullable): Brightness steps; each holds until the next, wrapping the day. An empty list never sets brightness.
- `atScreen` (string, optional, nullable):  One of: `restore`, `leave`, `null`.
- `sound` (string, optional, nullable): `null` is not chosen, which plays muted. One of: `on`, `off`, `null`.
- `panelVolume` (integer, optional, nullable):
- `location` (object, optional, nullable): Where the site is; `null` is not set.
  - `lat` (number, optional):
  - `lon` (number, optional):
  - `name` (string, optional):
  - `address` (string, optional):
  - `city` (string, optional):
  - `state` (string, optional):
  - `postcode` (string, optional):
- `devices` (array of objects, optional): The Mestra screens linked to the site.
  - `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.

### 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_site`, `not_connected`): `unknown_site`, 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/sites/string/power \
  --header "Authorization: Bearer $MESTRA_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"power":"off","until":"2026-11-12T08:00:00Z"}'
```

## Update the site of screens

`PUT /api/v1/player/sites/link`

Permission: Screens · Write.

Needs the Screens write permission and an editor. Links screens to a site, or with an empty `site` takes them off their site.

### Parameters

- `frames` (array of strings, required):
- `site` (string, required):

### Returns

How many screens were linked.

An object with:

- `linked` (integer, optional):

### Errors

- 400: No screens, or an id that isn't a screen.
- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`, `plan_refused`): `wrong_key` (the key or role can't do this), a key limited to some screens, or `plan_refused`.
- 404 (`not_connected`): There's no such site, or `not_connected`.
- 409 (`api_off`, `integration_off`): `api_off`, `integration_off`, or a screen that has a booking on it.

### Example request

```sh
curl --request PUT \
  --url https://app.withmestra.com/api/v1/player/sites/link \
  --header "Authorization: Bearer $MESTRA_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"frames":["8f3a9b1c-2d4e-4f60-9a7b-1c2d3e4f5a6b"],"site":"north-mall"}'
```
