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)OptionalscreenIdstring (uuid)OptionalactionstringOptionalPossible values
shotlogsrestartrefetchrebootstatusstringOptionalPossible values
queueddonefailedexpiredreasonstringOptionalWhy a
failedcommand failed, as a short code; empty otherwise.requestedByNamestringOptionalNullableWho asked in the app; null for a command asked with an API key.
requestedAtstring (date-time)OptionalfinishedAtstring (date-time)OptionalNullablecaptureIdstringOptionalThe screenshot or log bundle a finished
shotorlogsmade; empty otherwise.
Create a command for a screen
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
actionstringRequiredPossible values
shotlogsrestartrefetchrebootconfirmbooleanOptionalRequired
trueforreboot.atMsinteger (int64)OptionalOn a
shot: the Mestra instant to take it at, in milliseconds since the epoch, up to 10 seconds ahead.idempotencyKeystring (uuid)OptionalA 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
| Status | Code | Meaning |
|---|---|---|
400 | confirm_needed |
|
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
404 | unknown_screennot_connected |
|
409 | idempotency_conflictscreen_unassignedorg_haltedapi_offintegration_off |
|
413 | “body exceeds limit (<n> bytes)”. | |
429 | too_many |
|
501 | The player is not available on this server. |
List all of a screen's commands
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)OptionalThe
requestedAtof the last command of the previous page. Leave it out to start from the newest.beforeIdstring (uuid)OptionalThe
idof the last command of the previous page; send it withbeforeso commands that share a time are neither skipped nor repeated. Optional.
Returns
The commands.
Returns a list of Command objects.
Errors
| Status | Code | Meaning |
|---|---|---|
400 |
| |
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
404 | unknown_screennot_connected |
|
409 | api_offintegration_off |
|
501 | The player is not available on this server. |
Retrieve a command
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)RequiredcommandIdstring (uuid)Required
Returns
The command.
Returns the Command object.
Errors
| Status | Code | Meaning |
|---|---|---|
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
404 | unknown_screenunknown_commandnot_connected |
|
409 | api_offintegration_off |
|
501 | The player is not available on this server. |
List all of a screen's screenshots
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)OptionalbeforeIdstring (uuid)OptionalThe
idof the last screenshot of the previous page; send it withbefore(that screenshot’sreceivedAt) 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)OptionaltakenAtstring (date-time)OptionalreceivedAtstring (date-time)OptionalThe key
beforepages by.widthintegerOptionalheightintegerOptionalperiodicbooleanOptional
Errors
| Status | Code | Meaning |
|---|---|---|
400 | A bad | |
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
404 | unknown_screenunknown_capturenot_connected |
|
409 | api_offintegration_off |
|
501 | The player is not available on this server. |
Retrieve a screenshot
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)RequiredshotIdstring (uuid)Required
Returns
The JPEG.
Errors
| Status | Code | Meaning |
|---|---|---|
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
404 | unknown_screenunknown_capturenot_connected |
|
409 | api_offintegration_off |
|
501 | The player is not available on this server. |
Retrieve a screen's log bundle
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)RequiredcaptureIdstring (uuid)Required
Returns
The log bundle.
Errors
| Status | Code | Meaning |
|---|---|---|
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
404 | unknown_screenunknown_capturenot_connected |
|
409 | api_offintegration_off |
|
501 | The player is not available on this server. |
Retrieve a screenshot preview
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)RequiredshotIdstring (uuid)Required
Returns
The PNG.
Errors
| Status | Code | Meaning |
|---|---|---|
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
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_screenunknown_capturenot_connected |
|
409 | api_offintegration_off |
|
501 | The player is not available on this server. |