# Stop and takedowns

Stopping a screen makes it show a stopped message instead of its content. A takedown stops screens, a site, every screen or one publication in one go, and records it so you can see when each screen has stopped. The settings here say what a stopped screen shows.

Stopping a screen makes it show a stopped message instead of its content. A takedown stops screens, a site, every screen or one publication in one go, and records it so you can see when each screen has stopped. The settings here say what a stopped screen shows.

## The Takedown object

A takedown: a request to stop screens, with what it covers, why, whether it is done, and the state of each screen it names.

- `id` (string (uuid), optional):
- `scope` (string, optional):  One of: `publication`, `screen`, `site`, `all`.
- `target` (string, optional, nullable):
- `reason` (string, optional, nullable):
- `status` (string, optional): `done` when no screen you can see is `pending` or `told`: each is `off`, `removed` or `started_again`. A screen `started_again` may be showing the content again. One of: `pending`, `done`.
- `createdAt` (string (date-time), optional):
- `doneAt` (string (date-time), optional, nullable):
- `screens` (array of objects, optional): The screens your key can see.
  - `id` (string (uuid), optional):
  - `name` (string, optional): The screen's name; empty once it was deleted.
  - `state` (string, optional): `pending`: not yet told. `told`: its manifest no longer plays it. `off`: its heartbeat shows it off (the screen's own report). `removed`: the screen was deleted first. `started_again`: the screen was started again first. One of: `pending`, `told`, `off`, `removed`, `started_again`.
  - `toldAt` (string (date-time), optional, nullable):
  - `offAt` (string (date-time), optional, nullable):
  - `reason` (string, optional, nullable): Why a `pending` or `told` screen is not moving: `offline` while it has not called in for 3 minutes. Null otherwise. One of: `offline`, `null`.

```json
{
  "id": "string",
  "scope": "publication",
  "target": "string",
  "reason": "string",
  "status": "pending",
  "createdAt": "string",
  "doneAt": "string",
  "screens": [
    {
      "id": "string",
      "name": "string",
      "state": "pending",
      "toldAt": "string",
      "offAt": "string",
      "reason": "offline"
    }
  ]
}
```

## Stop a screen

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

Permission: Screens · Takedown.

Needs an editor's or an owner's key or session. Stops one screen so it shows its stopped picture, and reaches the screen at once. A key with the Screens Takedown permission may call this; it can't start, rename or delete a screen. The body is `{}` or empty. Stopping a screen that is already stopped is not an error: the answer is the same and nothing more is recorded. This call records the stop only; to be told when a screen has stopped showing an ad, use takedowns.

### Parameters

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

### Returns

The screen, with `stopped` true.

Returns the Screen object (/docs/api/screens/#object).

### Errors

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

### Example request

```sh
curl --request POST \
  --url https://app.withmestra.com/api/v1/player/devices/string/stop \
  --header "Authorization: Bearer $MESTRA_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{}'
```

## Retrieve what stopped screens show

`GET /api/v1/player/settings`

Permission: Screens · Read.

Needs an owner's key or session. `logos` lists the organisation's PNG and JPEG logos a screen can show, as `<site>/<variant>`.

### Returns

The choice for all screens.

An object with:

- `stopShow` (string, optional):  One of: `black`, `logo`, `image`, `video`.
- `transition` (string, optional): How every screen moves from one ad to the next. One of: `cut`, `fade`.
- `imageId` (string, optional): The picture's sha256 while `stopShow` is `image`, else empty.
- `videoId` (string, optional): The video's sha256 while `stopShow` is `video`, else empty.
- `logoId` (string, optional): The logo chosen, `<site>/<variant>`; empty when none or it has since changed.
- `logos` (array of objects, optional):
  - `id` (string, optional):
  - `site` (string, optional):
  - `variant` (string, optional):
- `updatesPaused` (boolean, optional): True while updates are paused for every screen, security updates included. In an editor's or an owner's signed-in session, or an owner's key or grant with Screens · Write; left out for any other key, a viewer and an app token. Only an owner can change it.

### Errors

- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`, `screens_limited`): `wrong_key`: the key lacks the Screens permission this call needs; or `screens_limited`: the key is limited to some screens and this call acts on all of them. A session below an owner's gets “Your role (\<role>) can't \<action>.”
- 404 (`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/settings \
  --header "Authorization: Bearer $MESTRA_TOKEN"
```

## Update what stopped screens show

`PUT /api/v1/player/settings`

Permission: Screens · Write.

Needs an owner's key or session. `black`; `logo` with a `logoId` from the settings' `logos` (the logo's file is copied for the screens); `image` with the `imageId` an upload gave; or `video` with the `videoId` an upload gave. Screens with a choice of their own keep it. Held screens are told at once. A key limited to some screens can't change this (403 `screens_limited`). `transition` (`cut` or `fade`) is how every screen moves from one ad to the next; sent alone, it leaves `stopShow` as it is.
In a signed-in owner's session, `{"updatesPaused": true}` (or `false`) alone pauses or resumes updates for every screen, security updates included, and the settings carry `updatesPaused`. An owner's key or grant with Screens · Write may do it too and sees `updatesPaused`; a plugin's app token may not (403 `session_only`). Each change is in Activity.

### Parameters

- `stopShow` (string, optional): Required unless `transition` is sent. One of: `black`, `logo`, `image`, `video`.
- `videoId` (string, optional): The video's sha256, for `video`.
- `imageId` (string, optional): The picture's sha256.
- `logoId` (string, optional):
- `transition` (string, optional):  One of: `cut`, `fade`.
- `updatesPaused` (boolean, optional): `true` pauses updates for every screen, security updates included; `false` resumes them. Sent alone it changes nothing else. An owner's session, or an owner's key or grant with Screens · Write; a plugin's app token gets 403 `session_only`.

### Returns

Saved; the settings as they are now.

An object with:

- `stopShow` (string, optional):  One of: `black`, `logo`, `image`, `video`.
- `transition` (string, optional): How every screen moves from one ad to the next. One of: `cut`, `fade`.
- `imageId` (string, optional): The picture's sha256 while `stopShow` is `image`, else empty.
- `videoId` (string, optional): The video's sha256 while `stopShow` is `video`, else empty.
- `logoId` (string, optional): The logo chosen, `<site>/<variant>`; empty when none or it has since changed.
- `logos` (array of objects, optional):
  - `id` (string, optional):
  - `site` (string, optional):
  - `variant` (string, optional):
- `updatesPaused` (boolean, optional): True while updates are paused for every screen, security updates included. In an editor's or an owner's signed-in session, or an owner's key or grant with Screens · Write; left out for any other key, a viewer and an app token. Only an owner can change it.

### Errors

- 400: A bad `stopShow` or `imageId` (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`, `session_only`): `wrong_key`: the key lacks the Screens permission this call needs; or `screens_limited`: the key is limited to some screens and this call acts on all of them; or `session_only`: a plugin's app token sent `updatesPaused`. A session below an owner's gets “Your role (\<role>) can't \<action>.”
- 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).
- 413: “body exceeds limit (\<n> bytes)”.
- 422: The logo can't be shown (not a PNG or JPEG, or not there), or the image is unknown.
- 501: The player is not available on this server.

### Example request

```sh
curl --request PUT \
  --url https://app.withmestra.com/api/v1/player/settings \
  --header "Authorization: Bearer $MESTRA_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"stopShow":"logo","logoId":"ESP/primary"}'
```

## Create a takedown

`POST /api/v1/player/takedowns`

Permission: Screens · Takedown.

Needs an editor's or an owner's key or session. Takes screens off and records it so you can be told when they are. `scope` is `screen` (`target` is a screen's id), `site` (`target` is a site code: every screen linked to it), `all` (no `target`: every screen the key can see) or `publication` (`target` is a Mestra publication's id: it is put into take-down mode, its Mestra entries end at once so the screens drop it on their next poll, and the screens it played on are the targets; a publication still waiting to be sent is cancelled, and one still being sent is `409 publication_busy`, so try again in a moment). A screen, site or all takedown stops each target screen, which a key with only the Screens Takedown permission may do; starting them again needs the Screens Write permission. A key limited to some screens can take down only those screens, and can't take down a publication, which ends on every screen it plays on (403 `screens_limited`).

`idempotencyKey` (a UUID you make) is required. Sending the same key with the same request returns the takedown it made (`200`, no second stop, no second record); the same key with a different request is `409 idempotency_conflict`, and so is a key whose takedown has no screen your key can see.

Each target screen is `pending` until its next manifest no longer plays the thing (a stopped screen, or a screen without the publication's entries), `told` from then, and `off` once its heartbeat shows it off (stopped, or for a publication takedown anything but one of its entries). `off` is the screen's own report: Mestra has no other way to see what a screen shows. A screen that was already stopped starts `off` only if its last heartbeat said it shows stopped; one stopped while it was away starts `pending` like any other. A screen that is deleted before it is off becomes `removed`. A screen that is started again before it is off becomes `started_again` (a publication takedown is not affected: it does not need the screen stopped), so the takedown can finish. An offline screen stays `pending`, with `reason: offline` on it: nothing times out. The takedown is `done` when no screen is `pending` or `told`.

### Parameters

- `idempotencyKey` (string (uuid), required): A UUID you make for this takedown. The same key with the same request returns the takedown it made.
- `scope` (string, required):  One of: `publication`, `screen`, `site`, `all`.
- `target` (string, optional, nullable): The screen's id (`screen`), the brand code (`site`) or the publication's id (`publication`). Leave it out for `all`.
- `reason` (string, optional, nullable):

### Returns

The key was already used for this request. The takedown it made.

### Errors

- 400: `idempotencyKey`, `scope`, `target` or `reason` (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`: the key lacks the Screens permission this call needs; or `screens_limited`: the key is limited to some screens and this call acts on all of them. A session below an editor's gets “Your role (\<role>) can't \<action>.”
- 404 (`unknown_screen`, `unknown_site`, `unknown_publication`, `not_connected`): `unknown_screen` (no such screen, or one this key can't see), `unknown_site` (no screen this key can see is linked to that site), `unknown_publication` (no such Mestra publication), or `not_connected`.
- 409 (`idempotency_conflict`, `publication_busy`, `api_off`, `integration_off`): `idempotency_conflict` (the key was used for a different takedown), `publication_busy` (the publication is still being sent to screens, so the ad could still go live: try again in a moment), `api_off` (an owner hasn't turned the API on), or `integration_off` (Mestra screens are off).
- 413: “body exceeds limit (\<n> bytes)”.
- 501: The player is not available on this server.

### Example request

```sh
curl --request POST \
  --url https://app.withmestra.com/api/v1/player/takedowns \
  --header "Authorization: Bearer $MESTRA_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"idempotencyKey":"3f6c1e7a-9b2d-4a58-8c3e-7d1f0a2b4c5d","scope":"publication","target":"5e2f9c34-7a1b-4c8d-b3e6-9d0a1f2b3c4d","reason":"Wrong price"}'
```

## List all takedowns

`GET /api/v1/player/takedowns`

Permission: Screens · Read.

Needs an editor's or an owner's key or session. The takedowns that name at least one screen the key can see, newest first. Each lists only the screens the key can see, and its `status` and `doneAt` are worked out from those. `next` is the cursor for the page after, or null on the last page.

### Parameters

- `cursor` (string, optional): The `next` of the previous response. Leave it out to start from the newest takedown.
- `limit` (integer, optional): Takedowns in the page.

### Returns

A page of takedowns.

### Errors

- 400: `limit` or `cursor` (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`): `wrong_key`: the key lacks the Screens permission this call needs. A session below an editor's gets “Your role (\<role>) can't \<action>.”
- 404 (`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/takedowns \
  --header "Authorization: Bearer $MESTRA_TOKEN"
```

## Retrieve a takedown

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

Permission: Screens · Read.

Needs an editor's or an owner's key or session. One takedown and where each of its screens has got to. A key limited to some screens sees only those, and a takedown with none of them is `404 unknown_takedown`.

### Parameters

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

### Returns

The takedown.

### 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. A session below an editor's gets “Your role (\<role>) can't \<action>.”
- 404 (`unknown_takedown`, `not_connected`): `unknown_takedown` (no such takedown, or none of its screens is one this key can see), or `not_connected`.
- 409 (`api_off`, `integration_off`): `api_off` (an owner hasn't turned the API on), or `integration_off` (Mestra screens are off).
- 501: The player is not available on this server.

### Example request

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