Skip to content

API reference

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.

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.

Attributes

  • idstring (uuid)Optional
  • screenIdstring (uuid)Optional
  • actionstringOptional

    Possible valuesshotlogsrestartrefetchreboot

  • statusstringOptional

    Possible valuesqueueddonefailedexpired

  • reasonstringOptional

    Why a failed command failed, as a short code; empty otherwise.

  • requestedByNamestringOptionalNullable

    Who asked in the app; null for a command asked with an API key.

  • requestedAtstring (date-time)Optional
  • finishedAtstring (date-time)OptionalNullable
  • captureIdstringOptional

    The screenshot or log bundle a finished shot or logs made; empty otherwise.

Create a command for a screen

PermissionScreens · 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.

Path parameters

  • idstring (uuid)Required

Body parameters

  • actionstringRequired

    Possible valuesshotlogsrestartrefetchreboot

  • confirmbooleanOptional

    Required true for reboot.

  • atMsinteger (int64)Optional

    On a shot: the Mestra instant to take it at, in milliseconds since the epoch, up to 10 seconds ahead.

  • idempotencyKeystring (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.

Returns the Command object.

Errors

StatusCodeMeaning
400confirm_needed

idempotencyKey, action or atMs (with field), or confirm_needed.

401invalid_token

The key is missing, unknown, revoked or expired (code invalid_token). Send it as Authorization: Bearer <key>.

403wrong_key

wrong_key: the key lacks the Screens · Write permission. A session below an owner’s gets “Your role (<role>) can’t <action>.”

404unknown_screennot_connected

unknown_screen (no such screen, or one this key can’t see), or not_connected.

409idempotency_conflictscreen_unassignedorg_haltedapi_offintegration_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)”.

429too_many

too_many; Retry-After is in seconds.

501

The player is not available on this server.

List all of a screen's commands

PermissionScreens · 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.

Path parameters

  • idstring (uuid)Required

Query parameters

  • beforestring (date-time)Optional

    The requestedAt of the last command of the previous page. Leave it out to start from the newest.

  • beforeIdstring (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.

Returns a list of Command objects.

Errors

StatusCodeMeaning
400

before (with field).

401invalid_token

The key is missing, unknown, revoked or expired (code invalid_token). Send it as Authorization: Bearer <key>.

403wrong_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>.”

404unknown_screennot_connected

unknown_screen (no such screen, or one this key can’t see), or not_connected.

409api_offintegration_off

api_off (an owner hasn’t turned the API on), or integration_off.

501

The player is not available on this server.

Retrieve a command

PermissionScreens · 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.

Path parameters

  • idstring (uuid)Required
  • commandIdstring (uuid)Required

Returns

The command.

Returns the Command object.

Errors

StatusCodeMeaning
401invalid_token

The key is missing, unknown, revoked or expired (code invalid_token). Send it as Authorization: Bearer <key>.

403wrong_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>.”

404unknown_screenunknown_commandnot_connected

unknown_screen (no such screen, or one this key can’t see), unknown_command, or not_connected.

409api_offintegration_off

api_off (an owner hasn’t turned the API on), or integration_off.

501

The player is not available on this server.

List all of a screen's screenshots

PermissionScreens · 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).

Path parameters

  • idstring (uuid)Required

Query parameters

  • beforestring (date-time)Optional
  • beforeIdstring (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:

  • idstring (uuid)Optional
  • takenAtstring (date-time)Optional
  • receivedAtstring (date-time)Optional

    The key before pages by.

  • widthintegerOptional
  • heightintegerOptional
  • periodicbooleanOptional

Errors

StatusCodeMeaning
400

A bad before (with field).

401invalid_token

The key is missing, unknown, revoked or expired (code invalid_token). Send it as Authorization: Bearer <key>.

403wrong_key

wrong_key: the key lacks the Screens · Read permission.

404unknown_screenunknown_capturenot_connected

unknown_screen, unknown_capture, or not_connected.

409api_offintegration_off

api_off (an owner hasn’t turned the API on), or integration_off.

501

The player is not available on this server.

Retrieve a screenshot

PermissionScreens · 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.

Path parameters

  • idstring (uuid)Required
  • shotIdstring (uuid)Required

Returns

The JPEG.

Errors

StatusCodeMeaning
401invalid_token

The key is missing, unknown, revoked or expired (code invalid_token). Send it as Authorization: Bearer <key>.

403wrong_key

wrong_key: the key lacks the Screens · Read permission.

404unknown_screenunknown_capturenot_connected

unknown_screen, unknown_capture, or not_connected.

409api_offintegration_off

api_off (an owner hasn’t turned the API on), or integration_off.

501

The player is not available on this server.

Retrieve a screen's log bundle

PermissionScreens · 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.

Path parameters

  • idstring (uuid)Required
  • captureIdstring (uuid)Required

Returns

The log bundle.

Errors

StatusCodeMeaning
401invalid_token

The key is missing, unknown, revoked or expired (code invalid_token). Send it as Authorization: Bearer <key>.

403wrong_key

wrong_key: the key lacks the Screens · Read permission. A session below an editor’s gets “Your role (<role>) can’t <action>.”

404unknown_screenunknown_capturenot_connected

unknown_screen, unknown_capture, or not_connected.

409api_offintegration_off

api_off (an owner hasn’t turned the API on), or integration_off.

501

The player is not available on this server.

Retrieve a screenshot preview

PermissionScreens · 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.

Path parameters

  • idstring (uuid)Required
  • shotIdstring (uuid)Required

Returns

The PNG.

Errors

StatusCodeMeaning
401invalid_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).

404unknown_screenunknown_capturenot_connected

unknown_screen, unknown_capture (no such shot, or it has no preview), or not_connected.

409api_offintegration_off

api_off (an owner hasn’t turned the API on), or integration_off.

501

The player is not available on this server.