# Loop

A screen's loop is the playlist it repeats. Loop settings are the rules the loop is built under, and are set at three levels: for all screens, for a site, or for one screen. A setting that is not set means no rule. See [Who plays when: customers and the loop](https://withmestra.com/docs/player/loop/) for the guide.

A screen's loop is the playlist it repeats. Loop settings are the rules the loop is built under, and are set at three levels: for all screens, for a site, or for one screen. A setting that is not set means no rule. See [Who plays when: customers and the loop](https://withmestra.com/docs/player/loop/) for the guide.

## The Loop settings object

The loop settings set at one level. A setting that is not set is `null`, and means no rule: Mestra picks no value.

- `loopMs` (integer, required, nullable): How long a loop is, in milliseconds.
- `defaultSlotMs` (integer, required, nullable): How long a slot is when a booking doesn't say, in milliseconds.
- `maxLoopMs` (integer, required, nullable): A hard limit: the longest a loop may be, in milliseconds. At least `loopMs`.
- `minSlotMs` (integer, required, nullable): A hard limit: the shortest a slot may be, in milliseconds. At most `defaultSlotMs`.
- `maxSharePct` (integer, required, nullable): A hard limit: the most of a loop any one customer may take, 1 to 100.
- `order` (string, required, nullable): The order of turns in a loop. One of: `as_booked`, `spread`, `shuffled`, `null`.

```json
{
  "loopMs": 0,
  "defaultSlotMs": 0,
  "maxLoopMs": 0,
  "minSlotMs": 0,
  "maxSharePct": 0,
  "order": "as_booked"
}
```

## Retrieve the loop settings for all screens

`GET /api/v1/player/loop-settings`

Permission: Screens · Read.

Needs the Screens read permission and an owner. A key limited to some screens can't use it (403 `screens_limited`). The settings every screen's loop is built under unless its site or the screen sets its own.

### Returns

The organisation's settings.

### 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 or role can't do this) or a key limited to some screens.
- 404 (`not_connected`): `not_connected`.
- 409 (`api_off`, `integration_off`): `api_off` or `integration_off`.

### Example request

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

## Create or update the loop settings for all screens

`PUT /api/v1/player/loop-settings`

Permission: Screens · Write.

Needs the Screens write permission and an owner. Sets the loop settings for all screens; they reach every screen of the organisation. A PUT replaces the settings at this level: a setting left out is cleared. A key limited to some screens can't use it (403 `screens_limited`).

### Parameters

- `loopMs` (integer, optional, nullable): How long a loop is, in milliseconds.
- `defaultSlotMs` (integer, optional, nullable): How long a slot is when a booking doesn't say, in milliseconds.
- `maxLoopMs` (integer, optional, nullable): A hard limit: the longest a loop may be, in milliseconds. At least `loopMs`.
- `minSlotMs` (integer, optional, nullable): A hard limit: the shortest a slot may be, in milliseconds. At most `defaultSlotMs`.
- `maxSharePct` (integer, optional, nullable): A hard limit: the most of a loop any one customer may take, 1 to 100.
- `order` (string, optional, nullable): The order of turns in a loop. One of: `as_booked`, `spread`, `shuffled`, `null`.

### Returns

Saved; the settings as the matching GET answers them.

### Errors

- 400 (`loop_longer_than_max`, `slot_shorter_than_min`): A value out of range (with `field`: `loopMs`, `defaultSlotMs`, `maxLoopMs`, `minSlotMs`, `maxSharePct` or `order`), or `loop_longer_than_max`, or `slot_shorter_than_min`.
- 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 (where it may not) or `plan_refused`.
- 404 (`not_connected`): `not_connected`.
- 409 (`api_off`, `integration_off`): `api_off` or `integration_off`.

### Example request

```sh
curl --request PUT \
  --url https://app.withmestra.com/api/v1/player/loop-settings \
  --header "Authorization: Bearer $MESTRA_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"loopMs":120000,"defaultSlotMs":10000,"maxLoopMs":null,"minSlotMs":5000,"maxSharePct":40,"order":"spread"}'
```

## Retrieve a site's loop settings

`GET /api/v1/player/sites/{site}/loop-settings`

Permission: Screens · Read.

Needs the Screens read permission and an owner. A key limited to some screens can't use it (403 `screens_limited`). The settings a site's screens are built under unless a screen sets its own.

### Parameters

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

### Returns

The site's settings.

### 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 or role can't do this) or a key limited to some screens.
- 404 (`unknown_site`, `not_connected`): `unknown_site`, or `not_connected`.
- 409 (`api_off`, `integration_off`): `api_off` or `integration_off`.

### Example request

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

## Create or update a site's loop settings

`PUT /api/v1/player/sites/{site}/loop-settings`

Permission: Screens · Write.

Needs the Screens write permission and an owner. A PUT replaces the settings at this level: a setting left out is cleared. A key limited to some screens can't use it (403 `screens_limited`). Sets a site's loop settings; they reach the screens linked to the site.

### Parameters

- `site` (string, required): The site's site code.
- `loopMs` (integer, optional, nullable): How long a loop is, in milliseconds.
- `defaultSlotMs` (integer, optional, nullable): How long a slot is when a booking doesn't say, in milliseconds.
- `maxLoopMs` (integer, optional, nullable): A hard limit: the longest a loop may be, in milliseconds. At least `loopMs`.
- `minSlotMs` (integer, optional, nullable): A hard limit: the shortest a slot may be, in milliseconds. At most `defaultSlotMs`.
- `maxSharePct` (integer, optional, nullable): A hard limit: the most of a loop any one customer may take, 1 to 100.
- `order` (string, optional, nullable): The order of turns in a loop. One of: `as_booked`, `spread`, `shuffled`, `null`.

### Returns

Saved; the settings as the matching GET answers them.

### Errors

- 400 (`loop_longer_than_max`, `slot_shorter_than_min`): A value out of range (with `field`: `loopMs`, `defaultSlotMs`, `maxLoopMs`, `minSlotMs`, `maxSharePct` or `order`), or `loop_longer_than_max`, or `slot_shorter_than_min`.
- 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 (where it may not) or `plan_refused`.
- 404 (`unknown_site`, `not_connected`): `unknown_site`, or `not_connected`.
- 409 (`api_off`, `integration_off`): `api_off` or `integration_off`.

### Example request

```sh
curl --request PUT \
  --url https://app.withmestra.com/api/v1/player/sites/string/loop-settings \
  --header "Authorization: Bearer $MESTRA_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"loopMs":120000,"defaultSlotMs":10000,"maxLoopMs":null,"minSlotMs":5000,"maxSharePct":40,"order":"spread"}'
```

## Retrieve a screen's loop settings

`GET /api/v1/player/devices/{id}/loop-settings`

Permission: Screens · Read.

Needs the Screens read permission and an editor (a viewer can read the screen's loop, but not its loop settings). A key limited to some screens can use it for its own screens. A screen's own loop settings, the ones its loop is built under, and where each came from.

### Parameters

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

### Returns

The screen's settings.

An object with:

- `own` (object, required): The loop settings set at one level. A setting that is not set is `null`, and means no rule: Mestra picks no value.
  - `loopMs` (integer, required, nullable): How long a loop is, in milliseconds.
  - `defaultSlotMs` (integer, required, nullable): How long a slot is when a booking doesn't say, in milliseconds.
  - `maxLoopMs` (integer, required, nullable): A hard limit: the longest a loop may be, in milliseconds. At least `loopMs`.
  - `minSlotMs` (integer, required, nullable): A hard limit: the shortest a slot may be, in milliseconds. At most `defaultSlotMs`.
  - `maxSharePct` (integer, required, nullable): A hard limit: the most of a loop any one customer may take, 1 to 100.
  - `order` (string, required, nullable): The order of turns in a loop. One of: `as_booked`, `spread`, `shuffled`, `null`.
- `resolved` (object, required): What the screen's loop is built under: each setting from the screen, else its site, else the organisation.
  - `loopMs` (integer, required, nullable): How long a loop is, in milliseconds.
  - `defaultSlotMs` (integer, required, nullable): How long a slot is when a booking doesn't say, in milliseconds.
  - `maxLoopMs` (integer, required, nullable): A hard limit: the longest a loop may be, in milliseconds. At least `loopMs`.
  - `minSlotMs` (integer, required, nullable): A hard limit: the shortest a slot may be, in milliseconds. At most `defaultSlotMs`.
  - `maxSharePct` (integer, required, nullable): A hard limit: the most of a loop any one customer may take, 1 to 100.
  - `order` (string, required, nullable): The order of turns in a loop. One of: `as_booked`, `spread`, `shuffled`, `null`.
- `from` (object, required): The level each set setting of `resolved` came from, by its name. A screen in a group is built under its group's settings: `group` is the group's own level. A setting that is set nowhere is left out.

### 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 or role can't do this).
- 404 (`unknown_screen`, `not_connected`): `unknown_screen` (including one the key doesn't hold), or `not_connected`.
- 409 (`api_off`, `integration_off`): `api_off` or `integration_off`.

### Example request

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

## Create or update a screen's loop settings

`PUT /api/v1/player/devices/{id}/loop-settings`

Permission: Screens · Write.

Needs the Screens write permission and an editor. A PUT replaces the settings at this level: a setting left out is cleared. A key limited to some screens can use it for its own screens. Sets a screen's own loop settings; they win over its site's and the organisation's.

### Parameters

- `id` (string (uuid), required):
- `loopMs` (integer, optional, nullable): How long a loop is, in milliseconds.
- `defaultSlotMs` (integer, optional, nullable): How long a slot is when a booking doesn't say, in milliseconds.
- `maxLoopMs` (integer, optional, nullable): A hard limit: the longest a loop may be, in milliseconds. At least `loopMs`.
- `minSlotMs` (integer, optional, nullable): A hard limit: the shortest a slot may be, in milliseconds. At most `defaultSlotMs`.
- `maxSharePct` (integer, optional, nullable): A hard limit: the most of a loop any one customer may take, 1 to 100.
- `order` (string, optional, nullable): The order of turns in a loop. One of: `as_booked`, `spread`, `shuffled`, `null`.

### Returns

Saved; the settings as the matching GET answers them.

An object with:

- `own` (object, required): The loop settings set at one level. A setting that is not set is `null`, and means no rule: Mestra picks no value.
  - `loopMs` (integer, required, nullable): How long a loop is, in milliseconds.
  - `defaultSlotMs` (integer, required, nullable): How long a slot is when a booking doesn't say, in milliseconds.
  - `maxLoopMs` (integer, required, nullable): A hard limit: the longest a loop may be, in milliseconds. At least `loopMs`.
  - `minSlotMs` (integer, required, nullable): A hard limit: the shortest a slot may be, in milliseconds. At most `defaultSlotMs`.
  - `maxSharePct` (integer, required, nullable): A hard limit: the most of a loop any one customer may take, 1 to 100.
  - `order` (string, required, nullable): The order of turns in a loop. One of: `as_booked`, `spread`, `shuffled`, `null`.
- `resolved` (object, required): What the screen's loop is built under: each setting from the screen, else its site, else the organisation.
  - `loopMs` (integer, required, nullable): How long a loop is, in milliseconds.
  - `defaultSlotMs` (integer, required, nullable): How long a slot is when a booking doesn't say, in milliseconds.
  - `maxLoopMs` (integer, required, nullable): A hard limit: the longest a loop may be, in milliseconds. At least `loopMs`.
  - `minSlotMs` (integer, required, nullable): A hard limit: the shortest a slot may be, in milliseconds. At most `defaultSlotMs`.
  - `maxSharePct` (integer, required, nullable): A hard limit: the most of a loop any one customer may take, 1 to 100.
  - `order` (string, required, nullable): The order of turns in a loop. One of: `as_booked`, `spread`, `shuffled`, `null`.
- `from` (object, required): The level each set setting of `resolved` came from, by its name. A screen in a group is built under its group's settings: `group` is the group's own level. A setting that is set nowhere is left out.

### Errors

- 400 (`loop_longer_than_max`, `slot_shorter_than_min`): A value out of range (with `field`: `loopMs`, `defaultSlotMs`, `maxLoopMs`, `minSlotMs`, `maxSharePct` or `order`), or `loop_longer_than_max`, or `slot_shorter_than_min`.
- 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 (where it may not) or `plan_refused`.
- 404 (`unknown_screen`, `not_connected`): `unknown_screen` (including one the key doesn't hold), or `not_connected`.
- 409 (`api_off`, `integration_off`): `api_off` or `integration_off`.

### Example request

```sh
curl --request PUT \
  --url https://app.withmestra.com/api/v1/player/devices/string/loop-settings \
  --header "Authorization: Bearer $MESTRA_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"loopMs":120000,"defaultSlotMs":10000,"maxLoopMs":null,"minSlotMs":5000,"maxSharePct":40,"order":"spread"}'
```

## Retrieve a screen's loop

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

Permission: Screens · Read.

Needs the Screens read permission; any member's session (a viewer too) will do. What a screen's loop will do, planned before it plays: the turns each booking asked for and was given, why they differ, and the order they play in.

### Parameters

- `id` (string (uuid), required):
- `at` (string (date-time), optional): An instant in the next 7 days: only the plan that is live then. Leave out for every plan.

### Returns

The screen's loop.

An object with:

- `mode` (string, required): `as_before`: nothing in force asks for a plan, and the screen loops its bookings in order. One of: `plan`, `as_before`.
- `settings` (object, required): The loop settings the loop is built under.
  - `loopMs` (integer, required, nullable): How long a loop is, in milliseconds.
  - `defaultSlotMs` (integer, required, nullable): How long a slot is when a booking doesn't say, in milliseconds.
  - `maxLoopMs` (integer, required, nullable): A hard limit: the longest a loop may be, in milliseconds. At least `loopMs`.
  - `minSlotMs` (integer, required, nullable): A hard limit: the shortest a slot may be, in milliseconds. At most `defaultSlotMs`.
  - `maxSharePct` (integer, required, nullable): A hard limit: the most of a loop any one customer may take, 1 to 100.
  - `order` (string, required, nullable): The order of turns in a loop. One of: `as_booked`, `spread`, `shuffled`, `null`.
- `from` (object, required): The level each set setting came from.
- `plans` (array of objects, required):
  - `live` (array of objects, required): The bookings that are live together in this plan.
    - `id` (string (uuid), required):
    - `name` (string, required):
    - `customer` (string, optional): The customer's name; left out when the booking has none.
    - `category` (string, optional): The customer's category; left out when it has none.
    - `durationMs` (integer, required):
  - `from` (string (date-time), required): The first stretch of the next 7 days in which these bookings are live together starts here.
  - `until` (string (date-time), required): Where that stretch ends.
  - `loopMs` (integer, required): How long the loop is, gaps included.
  - `gapMs` (integer, required): How long a gap turn shows the stop show.
  - `orders` (array of arrays, required): The turns, one booking id each; an empty string is a gap. Played in turn when there are several.
  - `turns` (array of objects, required):
    - `entryId` (string (uuid), required):
    - `asked` (integer, required): The turns the booking asked for (its slots).
    - `given` (integer, required): The turns it gets in the loop.
    - `why` (array of strings, required): In words, why `given` differs from `asked`.
  - `notes` (array of objects, required): What was done to keep every cap and separation. A fill or gap note stands for a count of turns, one note for each booking.
    - `kind` (string, required):  One of: `cut`, `left_out`, `over_booked`, `fill_paid`, `fill_house`, `house`, `gap`, `too_large`.
    - `entryId` (string (uuid), optional):
    - `text` (string, required):

### Errors

- 400: `at` is not a time (with `field`: `at`).
- 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 or role can't do this).
- 404 (`unknown_screen`, `not_connected`): `unknown_screen` (including one the key doesn't hold), or `not_connected`.
- 409 (`api_off`, `integration_off`): `api_off` or `integration_off`.

### Example request

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