# Screen commands

A command asks a screen to do something: take a screenshot, collect its logs, restart the player, download its content again or reboot the PC. The screen carries it out the next time it checks in, and the result is read here. Logs: the way to read and keep screen logs is the monitoring export over OTLP, to any OTLP destination; a log bundle is for a one-off pull. When a command finishes, the `screen.action_done` webhook says so; see [Webhooks](https://withmestra.com/docs/player/webhooks/).

A command asks a screen to do something: take a screenshot, collect its logs, restart the player, download its content again or reboot the PC. The screen carries it out the next time it checks in, and the result is read here. Logs: the way to read and keep screen logs is the monitoring export over OTLP, to any OTLP destination; a log bundle is for a one-off pull. When a command finishes, the `screen.action_done` webhook says so; see [Webhooks](https://withmestra.com/docs/player/webhooks/).

## The Command object

A command asked of a screen: what was asked, who asked, whether it is queued, done, failed or expired, and the screenshot or log bundle it made.

- `id` (string (uuid), optional):
- `screenId` (string (uuid), optional):
- `action` (string, optional):  One of: `shot`, `logs`, `restart`, `refetch`, `reboot`.
- `status` (string, optional):  One of: `queued`, `done`, `failed`, `expired`.
- `reason` (string, optional): Why a `failed` command failed, as a short code; empty otherwise.
- `requestedByName` (string, optional, nullable): Who asked in the app; null for a command asked with an API key.
- `requestedAt` (string (date-time), optional):
- `finishedAt` (string (date-time), optional, nullable):
- `captureId` (string, optional): The screenshot or log bundle a finished `shot` or `logs` made; empty otherwise.

```json
{
  "id": "string",
  "screenId": "string",
  "action": "shot",
  "status": "queued",
  "reason": "string",
  "requestedByName": "string",
  "requestedAt": "string",
  "finishedAt": "string",
  "captureId": "string"
}
```

## Create a command for a screen

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

Permission: Screens · Write.

Needs an owner's key or session. Asks a screen for a screenshot (`shot`), its logs (`logs`), a restart of the player (`restart`), a fresh download of its content (`refetch`) or a reboot of the PC (`reboot`, which needs `confirm: true`). The screen does it the next time it polls, within 10 minutes or the command expires. The Test panel has its own route in the app. `atMs` on a `shot` is the Mestra instant (milliseconds since the epoch) to take it at, up to 10 seconds ahead.

### Parameters

- `id` (string (uuid), required):
- `action` (string, required):  One of: `shot`, `logs`, `restart`, `refetch`, `reboot`.
- `confirm` (boolean, optional): Required `true` for `reboot`.
- `atMs` (integer (int64), optional): On a `shot`: the Mestra instant to take it at, in milliseconds since the epoch, up to 10 seconds ahead.
- `idempotencyKey` (string (uuid), optional): A UUID you make for this request. Required for a key.

### Returns

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

### Errors

- 400 (`confirm_needed`): `idempotencyKey`, `action` or `atMs` (with `field`), or `confirm_needed`.
- 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 · Write permission. A session below an owner's gets “Your role (\<role>) can't \<action>.”
- 404 (`unknown_screen`, `not_connected`): `unknown_screen` (no such screen, or one this key can't see), or `not_connected`.
- 409 (`idempotency_conflict`, `screen_unassigned`, `org_halted`, `api_off`, `integration_off`): `idempotency_conflict` (the key was used for a different request), `screen_unassigned` (the screen is waiting to be named), `org_halted`, `api_off` (an owner hasn't turned the API on), or `integration_off`.
- 413: “body exceeds limit (\<n> bytes)”.
- 429 (`too_many`): `too_many`; `Retry-After` is in seconds.
- 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/commands \
  --header "Authorization: Bearer $MESTRA_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"idempotencyKey":"3f6c1e7a-9b2d-4a58-8c3e-7d1f0a2b4c5d","action":"shot"}'
```

## List all of a screen's commands

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

Permission: Screens · Read.

Needs an editor's or an owner's key or session. The screen's commands, newest first, 20 to a page; page back with `before`. Finished commands are kept for the same time as the screen's events.

### Parameters

- `id` (string (uuid), required):
- `before` (string (date-time), optional): The `requestedAt` of the last command of the previous page. Leave it out to start from the newest.
- `beforeId` (string (uuid), optional): The `id` of the last command of the previous page; send it with `before` so commands that share a time are neither skipped nor repeated. Optional.

### Returns

The commands.

### Errors

- 400: `before` (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 (`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`.
- 501: The player is not available on this server.

### Example request

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

## Retrieve a command

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

Permission: Screens · Read.

Needs an editor's or an owner's key or session. One command of the screen: `status` is `queued` until the screen answers, then `done` or `failed` (with a `reason`), or `expired` when it did not take the command in time.

### Parameters

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

### Returns

The command.

### 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_screen`, `unknown_command`, `not_connected`): `unknown_screen` (no such screen, or one this key can't see), `unknown_command`, 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/devices/string/commands/string \
  --header "Authorization: Bearer $MESTRA_TOKEN"
```

## List all of a screen's screenshots

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

Permission: Screens · Read.

Any member's session (viewer, editor or owner), or a key with the Screens permission. Newest first by the time the server received them, 50 a page. Pass the
last `receivedAt` as `before` for the next page. Screenshots show everything on the screen at that moment, including anything open on top; they are kept for the same time as in the app (periodic ones 7 days, on-demand ones 30 days) and do not use the organisation's storage allowance. A key limited to some screens reads only those (an unknown or out-of-scope screen is `404 unknown_screen`).

### Parameters

- `id` (string (uuid), required):
- `before` (string (date-time), optional):
- `beforeId` (string (uuid), optional): The `id` of the last screenshot of the previous page; send it with `before` (that screenshot's `receivedAt`) so screenshots that share a time are neither skipped nor repeated. Optional.

### Returns

A page of screenshots.

A list of objects, each with:

- `id` (string (uuid), optional):
- `takenAt` (string (date-time), optional):
- `receivedAt` (string (date-time), optional): The key `before` pages by.
- `width` (integer, optional):
- `height` (integer, optional):
- `periodic` (boolean, optional):

### Errors

- 400: A bad `before` (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 · Read permission.
- 404 (`unknown_screen`, `unknown_capture`, `not_connected`): `unknown_screen`, `unknown_capture`, 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/devices/string/shots \
  --header "Authorization: Bearer $MESTRA_TOKEN"
```

## Retrieve a screenshot

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

Permission: Screens · Read.

Any member's session (viewer, editor or owner), or a key with the Screens permission. The picture itself, decrypted, with `Cache-Control: private, no-store`,
`X-Content-Type-Options: nosniff` and a sandboxing `Content-Security-Policy`. Ask a screen for one with `POST /devices/{id}/commands` (action `shot`); the finished command's `captureId` is this `shotId`. The id of a log bundle is `404 unknown_capture` here.

### Parameters

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

### Returns

The JPEG.

### 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 · Read permission.
- 404 (`unknown_screen`, `unknown_capture`, `not_connected`): `unknown_screen`, `unknown_capture`, 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/devices/string/shots/string \
  --header "Authorization: Bearer $MESTRA_TOKEN"
```

## Retrieve a screen's log bundle

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

Permission: Screens · Read.

Needs an editor's or an owner's key or session; a viewer is refused. The way to read and keep screen logs is the customer monitoring export over OTLP, to any OTLP destination. This route is for a one-off pull of a log bundle a screen collected: ask for one with `POST /devices/{id}/commands` (action `logs`), then read it here with the finished command's `captureId`. It is a gzip file; there is no log viewer and no streaming.

### Parameters

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

### Returns

The log bundle.

### 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 · Read permission. A session below an editor's gets “Your role (\<role>) can't \<action>.”
- 404 (`unknown_screen`, `unknown_capture`, `not_connected`): `unknown_screen`, `unknown_capture`, 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/devices/string/logs/string \
  --header "Authorization: Bearer $MESTRA_TOKEN"
```

## Retrieve a screenshot preview

`GET /api/v1/player/devices/{id}/shots/{shotId}/thumb`

Permission: Screens · Read.

Needs the Screens read permission; any member's session (a viewer too) will do. The small PNG preview of a screenshot, at the address in a screen's `lastShot`.

### Parameters

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

### Returns

The PNG.

### Errors

- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403: “Your role (\<role>) can't \<action>.” (the role is below the route's minimum) or “Choose an organisation first.” (the session has no organisation).
- 404 (`unknown_screen`, `unknown_capture`, `not_connected`): `unknown_screen`, `unknown_capture` (no such shot, or it has no preview), 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/devices/string/shots/string/thumb \
  --header "Authorization: Bearer $MESTRA_TOKEN"
```
