Skip to content

API reference

Screens

The Screen object

A Mestra Player screen: a display that shows the organisation’s published artwork, with its size, whether it is online and whether it is stopped.

Attributes

  • idstring (uuid)Optional
  • namestringOptional
  • widthintegerOptional

    The screen’s pixels; 0 until known.

  • heightintegerOptional
  • timezonestringOptional
  • appVersionstringOptional
  • onlinebooleanOptional
  • lastSeenAtstring (date-time)OptionalNullable
  • stoppedbooleanOptional
  • stopShowstringOptional

    This screen’s own choice of what it shows while stopped; same follows the organisation’s.

    Possible valuessameblacklogoimagevideo

  • siteStopShowstringOptional

    The choice of the screen’s site (same follows the choice for all screens); empty when the screen has no site.

    Possible valuessameblacklogoimage

  • stopShowFromstringOptional

    Where what the screen shows while stopped comes from: its own choice (screen), its site’s (site) or the choice for all screens (org).

    Possible valuesscreensiteorg

  • unassignedbooleanOptional

    True for a screen that joined with an install key and no owner has named yet.

  • windowobjectOptionalNullable

    The window the screen plays in; null is the whole screen, and always null on a group and on an unassigned screen.

    Show child attributesHide child attributes
    • profileobjectOptional

      The panel profile the window comes from.

      Show child attributesHide child attributes
      • idstringOptional
      • namestringOptional
    • xintegerOptional
    • yintegerOptional
    • wintegerOptional
    • hintegerOptional
    • rotationintegerOptional

      Possible values090180270

    • placeWintegerOptional
    • placeHintegerOptional
  • framesobjectOptional

    A screen’s frames, always present: an empty list on a plain screen, version 0 on a group and on an unassigned screen. A booking can name a frame as it names a screen.

    Show child attributesHide child attributes
    • versionintegerOptional

      Send it back to change the frames.

    • framesarray of objectsOptional
      Show child attributesHide child attributes
      • idstring (uuid)Optional
      • namestringOptional
      • xintegerOptional
      • yintegerOptional
      • wintegerOptional
      • hintegerOptional
      • layerintegerOptional
      • soundbooleanOptional
  • orgStoppedbooleanOptional

    True while every screen is stopped: the organisation’s own stop is on, or the organisation is halted (orgHalt).

  • transitionstringOptional

    This screen’s own change between ads; same follows the organisation’s.

    Possible valuessamecutfade

  • h265booleanOptional

    The screen reported it plays H.265.

  • html5booleanOptional

    The screen reported it plays HTML5 packages.

  • decodeAtstring (date-time)OptionalNullable

    When the screen’s reported decoders last changed; null until it has reported.

  • decodearray of objectsOptionalNullable

    What the screen says it decodes, as the server kept it: for each codec and frame rate, the largest picture it plays smoothly. null until it has reported; an empty list is a screen that reported and decodes none (H.264 still plays where the list holds no H.264). The screen’s report is untrusted: entries outside the bounds are dropped.

    Show child attributesHide child attributes
    • codecstringOptional

      Possible valuesh264h265vp9av1

    • maxSideintegerOptional

      The longest side, in pixels.

    • maxPixelsinteger (int64)Optional

      Width times height, in pixels.

    • fpsintegerOptional

      The frame-rate tier this entry covers.

      Possible values3060

  • cantPlayarray of objectsOptional

    The files of this screen’s live bookings that it can’t play, and why. Empty when it plays them all. reason is no_codec (codec is the one it lacks), too_big (maxWidth and maxHeight are the largest picture it decodes for the codec), too_fast (maxFps is its highest frame rate), no_html5 (detail is why HTML5 is off) or no_report (the screen hasn’t said what it plays).

    Show child attributesHide child attributes
    • namestringOptional

      The booking’s name.

    • reasonstringOptional

      Possible valuesno_codectoo_bigtoo_fastno_html5no_report

    • codecstringOptional

      Possible valuesh264h265vp9av1

    • detailstringOptional
    • maxWidthintegerOptional
    • maxHeightintegerOptional
    • maxFpsintegerOptional
  • stopVideoCantPlayobjectOptional

    Present when this screen is meant to show a stop video it can’t play: it shows black instead. name is stop video; reason and the rest are as in cantPlay.

    Show child attributesHide child attributes
    • namestringOptional
    • reasonstringOptional

      Possible valuesno_codectoo_bigtoo_fastno_html5no_report

    • codecstringOptional

      Possible valuesh264h265vp9av1

    • detailstringOptional
    • maxWidthintegerOptional
    • maxHeightintegerOptional
    • maxFpsintegerOptional
  • html5OffstringOptional

    Why HTML5 is off on this screen, when it said: the player is starting (starting), the player hasn’t started it (shell_not_ready), the network lock isn’t confirmed (net_jail) or sound can’t be kept off (mute_unconfirmed). Empty when HTML5 is on or no cause was given.

    Possible valuesstartingshell_not_readynet_jailmute_unconfirmed

  • orgHaltstringOptional

    Why the organisation’s screens are halted and black: read_only (the account is read-only; they start again when it is active) or disabled (disabled, or scheduled for deletion). Empty when they are not.

    Possible valuesread_onlydisabled

  • hardwareobjectOptional

    What the screen says it is (its own claim, never proof). tpm is true when it reported a TPM endorsement key; the key itself is never shown.

    Show child attributesHide child attributes
    • manufacturerstringOptional
    • modelstringOptional
    • serialstringOptional
    • tpmbooleanOptional
    • serialSharedbooleanOptional

      True when many PCs report this serial (a placeholder this organisation’s own screens show, or one staff confirmed). It identifies none of them, so the screen gets no “looks like” by serial. Omitted when false.

  • enrolledViaobjectOptionalNullable

    The install key the screen joined with; null for a screen added with a code. name is shown only to a caller with the Screens write permission, and never to staff acting as the organisation.

    Show child attributesHide child attributes
    • idstring (uuid)Optional
    • namestringOptional
  • enrolledAtstring (date-time)Optional

    When the screen joined (paired or enrolled). It never changes; the unassigned pool is listed in this order.

  • opencrsRefstringOptionalNullable

    The OpenCRS screen this screen is the face of, or null.

  • looksLikeCountintegerOptional

    How many of the organisation’s other screens (inside the caller’s scope) may be this same machine: the same serial and maker, or the same TPM key. Only an unassigned screen and a set-up one are ever paired: two unassigned screens never count each other. Lists carry the count; one screen’s own view also carries looksLike.

  • looksLikearray of objectsOptional

    Only in one screen’s own view (GET /devices/{id} and the answers to a change): the first 20 screens it may be the same machine as, in id order. looksLikeCount is the total; when there are more, looksLikeNext is the cursor to pass to GET /devices/{id}/looks-like as after.

    Show child attributesHide child attributes
    • idstring (uuid)Optional
    • namestringOptional
    • whystringOptional

      What the match rests on. Both are what the PC itself reported (its serial and maker, or its TPM key hash): a claim, not proof. Check the install key and the time it joined before you replace a screen with it.

      Possible valuesserialtpm

  • looksLikeNextstringOptional

    Only in one screen’s own view, and only when looksLike is not the whole list: the after for GET /devices/{id}/looks-like.

  • possibleCopybooleanOptional

    True when the machine’s identity changed since it enrolled in a way that looks like its files were copied to another machine. An owner clears it with cloneChecked: true.

  • copyProvenbooleanOptional

    True when Mestra has found that this screen’s identity is in use on another PC. A replace clears it, and so does the owner saying it is not a copy (cloneChecked).

  • keyCheckobjectOptionalNullable

    A PC set up from a provisioning package plays nothing until its check that Windows’ readable copy of the install key is gone has passed. state is checking, failed (the check could not finish; reason says why, and it tries again by itself) or exposed (it proved a readable copy of the key: revoke the key; reason names the places, with any piece of the key in a name masked). since is when the hold was first seen. Null when the screen is not held. checking and failed, and a failure’s reason, are the PC’s own report on its heartbeat: Mestra bounds and cleans the text but cannot check it, and a held PC is kept inert by its own agent (it is an unassigned pool row either way, which gets no content, commands or credentials). exposed is Mestra’s own mark, set only from a report the server verified against the key the screen joined with.

    Show child attributesHide child attributes
    • statestringOptional

      Possible valuescheckingfailedexposed

    • reasonstringOptional
    • sincestring (date-time)OptionalNullable
  • siteCodestringOptional

    The code of the site the screen is linked to; empty when it is not linked.

  • kindstringOptional

    single is a PC; group is a screen group: one screen made of several, with no PC of its own.

    Possible valuessinglegroup

  • groupobjectOptional

    On a member of a group (when the group is in your scope): which group and the member’s place.

    Show child attributesHide child attributes
    • idstring (uuid)Optional
    • namestringOptional
    • positionintegerOptional
  • membersarray of objectsOptional

    On a group: its screens, by place.

    Show child attributesHide child attributes
    • idstring (uuid)Optional
    • namestringOptional
    • positionintegerOptional
    • onlinebooleanOptional
  • layoutobjectOptional

    On a group: its rows and columns, the gap and size you gave, the canvas that comes to, and the version to send with a change.

    Show child attributesHide child attributes
    • rowsintegerOptional
    • colsintegerOptional
    • bezelMmnumberOptionalNullable
    • diagInnumberOptionalNullable
    • canvasWintegerOptional
    • canvasHintegerOptional
    • gapPxintegerOptional
    • cellWintegerOptional
    • cellHintegerOptional
    • placedbooleanOptional
    • placingbooleanOptional
    • versionintegerOptional
    • identifyUntilstring (date-time)OptionalNullable
  • lookbooleanOptional

    The screen needs a look: it last showed something other than what it was told to, or it has several displays and Mestra uses one.

  • syncStatestringOptional

    On a placed group, in a paged list only: whether its screens are in step.

    Possible valuesplacingin_stepout_of_stepunknown

  • syncLatearray of integersOptional

    On a group that is out of step, in a paged list only: the positions of the members the reasons name, in order.

  • displayobjectOptionalNullable

    What the PC said about its displays: how many, the primary and whole desktop size, notSpanned (more than one display and Mestra shows on one), spanned (the graphics driver joins them into one) and sizeChanged (the size before its last change); null from a group and a PC that has not said.

    Show child attributesHide child attributes
    • monitorsintegerOptional
    • primaryWintegerOptional
    • primaryHintegerOptional
    • virtualWintegerOptional
    • virtualHintegerOptional
    • notSpannedbooleanOptional
    • spannedbooleanOptional
    • sizeChangedobjectOptionalNullable
      Show child attributesHide child attributes
      • fromWintegerOptional
      • fromHintegerOptional
      • toWintegerOptional
      • toHintegerOptional
  • soundstringOptionalNullable

    This screen’s own sound setting; null follows its site.

    Possible valuesonoffnull

  • panelVolumeintegerOptionalNullable

    This screen’s own panel volume; null follows its site.

  • hoursarray of valuesOptionalNullable

    This screen’s own on and off times; null follows its site.

  • brightnessarray of valuesOptionalNullable

    This screen’s own brightness times; null follows its site.

  • locationobjectOptionalNullable

    This screen’s own place; null follows its site.

    Show child attributesHide child attributes
    • latnumberOptional
    • lonnumberOptional
    • namestringOptional
    • addressstringOptional
    • citystringOptional
    • statestringOptional
    • postcodestringOptional
  • siteobjectOptionalNullable

    The site the screen is linked to; null when it has none.

    Show child attributesHide child attributes
    • keystringOptional

      The brand code.

    • namestringOptional
  • nowobjectOptional

    What the screen is showing, from its last report. While the screen or the organisation is stopped, state is stopped and entry is null, whatever the screen last said. off means its panel is switched off. entry is null when the screen isn’t showing an item or the item has been deleted.

    Show child attributesHide child attributes
    • statestringOptional

      Possible valuesplayingwaitingpairingstoppedoffunknown

    • entryobjectOptionalNullable
      Show child attributesHide child attributes
      • idstring (uuid)Optional
      • namestringOptional
      • sha256stringOptional

        The entry’s file. A screen that is offline or has not caught up may still be showing an earlier one.

      • publicationIdstring (uuid)OptionalNullable

        The publication the item came from; null when the entry has no published item.

    • sincestring (date-time)OptionalNullable
  • nextobjectOptionalNullable

    The item the screen shows after this one. Null when the screen is stopped or has not said.

    Show child attributesHide child attributes
    • entryobjectOptional
      Show child attributesHide child attributes
      • idstring (uuid)Optional
      • namestringOptional
      • sha256stringOptional

        The entry’s file. A screen that is offline or has not caught up may still be showing an earlier one.

      • publicationIdstring (uuid)OptionalNullable

        The publication the item came from; null when the entry has no published item.

  • lastShotobjectOptional

    On a page of the screens list, for a screen with nothing booked now or next: its newest screenshot that has a small preview. Left out otherwise. thumb is the preview’s address, which holds the shot’s id and never changes.

    Show child attributesHide child attributes
    • idstring (uuid)Optional
    • thumbstringOptional
    • takenAtstring (date-time)Optional
  • healthobjectOptional

    online is the live check (the screen called within the last 3 minutes). presence is the state the webhooks follow, moved by the screen’s report and a once-a-minute sweep, so the two can differ for up to a minute.

    Show child attributesHide child attributes
    • onlinebooleanOptional
    • presencestringOptional

      Possible valuesonlineoffline

    • presenceSincestring (date-time)OptionalNullable
    • lastSeenAtstring (date-time)OptionalNullable
    • appVersionstringOptional
    • cacheBytesinteger (int64)OptionalNullable

      The size of the screen’s file cache; null until it reports.

    • issueobjectOptional

      The screen’s health line: what is wrong, or that it fixed itself, and what to do about it.

      Show child attributesHide child attributes
      • pillstringOptional

        Possible valuesHealthyFixed itselfNeeds a lookNeeds a visitOffline

      • titlestringOptional
      • fixstringOptional
      • sincestring (date-time)OptionalNullable

        When the fault began, or when it fixed itself.

      • codestringOptional
    • uptimeobjectOptional

      The screen’s last 30 days (its own days, to today) from the days Mestra has signed. Null fractions where no day was counted.

      Show child attributesHide child attributes
      • last30dnumberOptionalNullable
      • last30dExSitePowernumberOptionalNullable

        With the seconds lost to the site’s power left out of both sides.

      • trendobjectOptional

        Uptime a day at a time: 30 days, oldest first, each the up seconds over the counted seconds of that day, cut (never rounded up) to four places; null where nothing was counted. On a screen in a paged list, on a site in the list of sites, and on an uptime answer for the default span.

        Show child attributesHide child attributes
        • tostring (date)Optional

          The last of the 30 days.

        • daysarray of numbersOptional
      • todayobjectOptional

        On a page of the screens list: today so far in the screen’s zone, from the hours it has sealed since midnight. Always partial. It is not in trend, last30d or any signed day. Left out until an hour has been sealed today.

        Show child attributesHide child attributes
        • upnumberOptionalNullable

          Up seconds over counted seconds of those hours, cut (never rounded up) to four places.

        • hoursintegerOptional

          The sealed hours it rests on.

        • partialbooleanOptional
    • lastMismatchobjectOptionalNullable

      The last time the screen found a file that failed its check; entries are the entry ids (or stopshow for the stopped picture). Null when it never has.

      Show child attributesHide child attributes
      • atstring (date-time)Optional
      • entriesarray of stringsOptional
    • diagobjectOptionalNullable

      What the screen’s PC last reported about itself. Null for a group and for a screen that has not reported. Text the device wrote is not shown.

      Show child attributesHide child attributes
      • reportedAtstring (date-time)Optional
      • diskFreeBytesinteger (int64)OptionalNullable
      • diskTotalBytesinteger (int64)OptionalNullable
      • memTotalBytesinteger (int64)OptionalNullable
      • memAvailBytesinteger (int64)OptionalNullable
      • playerRamBytesinteger (int64)OptionalNullable

        The memory the player uses.

      • tempCnumberOptionalNullable

        The PC’s temperature in degrees Celsius.

      • clockOffsetMsintegerOptionalNullable

        How far the PC’s clock is from the server’s, in milliseconds.

      • bootedAtstring (date-time)OptionalNullable
      • shellUpbooleanOptional

        Whether the player’s shell is running.

List all screens

PermissionScreens · Read

Any member’s session (viewer, editor or owner), or a key with the Screens permission. Lists the organisation’s Mestra Player screens, oldest first. A screen is online when it called within the last 3 minutes. A key limited to some screens sees only those. ?site=<site code> lists only the screens linked to that site; a site with none of your screens is 404 unknown_site. Each screen carries its site, what it is showing now, the item next, and its health. health.online is the live check (the screen called within 3 minutes); health.presence is the state the webhooks follow, moved by the heartbeat and a once-a-minute sweep, so the two can differ for up to a minute. While the screen or the organisation is stopped now.state is stopped and next is null, whatever the screen last said.

Paged. With unassigned or key the answer is a page instead, {screens, total, next}, in the order the screens joined: total counts every screen the filter matches, and next (null on the last page) is passed as after for the next page. This form is an editor’s or an owner’s (a viewer-role member is refused by role), and for a key that sees every screen (else 403 screens_limited); a bad unassigned, limit or after is 400 (bad_unassigned, bad_limit, bad_after). Without either filter, limit and after are ignored and the answer is the plain list. Each row also carries the screen’s siteCode (the code of the site it is linked to, or an empty string), and the screen’s own hours, brightness, sound, panelVolume and location (null follows the site), and any running power override. An editor’s or an owner’s own browser session, or an owner’s key or grant with Screens · Write, sees more fields than this reference lists (the panel link, the update status); any other key does not.

Query parameters

  • sitestringOptional

    A site code: list only the screens linked to it.

  • unassignedbooleanOptional

    Pages the list (see below): only screens nobody has named yet (true), or only the named ones (false).

  • keystring (uuid)Optional

    Pages the list (see below): only the screens that joined with this install key. Needs the Screens write permission.

  • limitintegerOptional

    Screens in a page, at most 200 (50 when left out). With unassigned or key, at most 500 and the cursor is after. Alone it is ignored: the answer is every screen as an array.

  • afterstringOptional

    With unassigned or key: the next of the page before. Ignored otherwise.

  • cursorstringOptional

    The next of the previous page. Pages the list, and only for the same filters and sort.

  • kindstringOptional

    Pages the list: only PCs, or only screen groups.

    Possible valuessinglegroup

  • statusstringOptional

    Pages the list: a stopped screen counts as stopped only, not online or offline.

    Possible valuesonlineofflinestopped

  • lookstringOptional

    Pages the list: only screens that need a look.

    Possible values1

  • attentionstringOptional

    Pages the list: only screens that need a person now (not stopped, and offline, showing black, with a fault open or needing a look).

    Possible values1

  • nositestringOptional

    Pages the list: only screens linked to no site. Not with site.

    Possible values1

  • groupstring (uuid)Optional

    Pages the list: the members of one screen group. Members are otherwise left out of the list.

  • qstringOptional

    Pages the list: screens whose name or site name contains this, members of a group included.

  • sortstringOptional

    Pages the list: the order. Default name. Status puts offline first, then online, then stopped.

    Possible valuesnamesitestatus

Returns

The screens, oldest first; with a filter, sort or cursor, one page as {screens, next} (next is null on the last page; pass it back as cursor); with unassigned or key, a page of them as {screens, total, next}.

Returns a list of Screen objects.

Errors

StatusCodeMeaning
400bad_unassignedbad_limitbad_after

With unassigned or key: bad_unassigned, bad_limit or bad_after.

401invalid_token

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

403wrong_keyscreens_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.

404not_connectedunknown_site

not_connected, or unknown_site (with ?site=, no screen in your scope is linked to that site).

409api_offintegration_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.

Retrieve a screen

PermissionScreens · Read

Any member’s session (viewer, editor or owner), or a key with the Screens permission. Returns one screen, the same as its row in the list.

Path parameters

  • idstring (uuid)Required

Returns

The screen.

Returns the Screen object.

Errors

StatusCodeMeaning
401invalid_token

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

403wrong_keyscreens_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.

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 (Mestra screens are off).

501

The player is not available on this server.

Add a screen by its pairing code

PermissionScreens · Write

Needs an owner’s key or session. The code is the 8 letters the screen shows; dashes, spaces and case don’t matter. Too many wrong codes are refused with 429. The screen collects its key on its next poll. Mestra screens must be on and connected. A key limited to some screens can’t pair a new one (403 screens_limited).

Two steps, if you want them. Send {code, confirm: false} to look at the screen behind the code first: the answer is {pending: {width, height, rotation, timezone, lastSeenAt, hardware, pairing}} and nothing is written. lastSeenAt is when the screen last asked for its key (null if not yet) and is shown, never refused on; hardware is the screen’s own claim (maker, model, serial, whether it has a TPM) and is unproven. Then send {code, name, confirm: true, pairing} with the pairing from the preview to add it. If the code was reissued to another screen in between, the answer is 409 pairing_changed and nothing is added. A wrong or expired code counts as a failed try, preview or not. A body with no confirm adds the screen at once, and then needs a name (a body with no name is 400); only an explicit confirm: false looks without adding. confirm: true without a pairing is 422.

Body parameters

  • codestringRequired
  • namestringOptional

    Required unless confirm is false.

  • confirmbooleanOptional

    false: look at the screen without adding it. true: add it (needs pairing). Absent: add it at once, with no check (needs name).

  • pairingstringOptional

    From the preview; required with confirm: true.

Returns

The screen was added (the screen as listed), or, for a preview, {pending: {...}} and nothing was written.

Returns one of:

The Screen object.

An object with:

  • pendingobjectRequired
    Show child attributesHide child attributes
    • widthintegerOptional
    • heightintegerOptional
    • rotationintegerOptional
    • timezonestringOptional
    • lastSeenAtstring (date-time)OptionalNullable
    • hardwareobjectOptional
      Show child attributesHide child attributes
      • manufacturerstringOptional
      • modelstringOptional
      • serialstringOptional
      • tpmbooleanOptional
    • pairingstringOptional

      Send it back with confirm: true.

Errors

StatusCodeMeaning
400

name is empty or has control, text-direction or zero-width characters (not needed for confirm: false).

401invalid_token

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

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

404not_connected

not_connected.

409api_offintegration_offpairing_changed

api_off (an owner hasn’t turned the API on), integration_off (Mestra screens are off), or pairing_changed (the code now belongs to another screen: ‘That code now belongs to another screen. Check the screen.’).

413

“body exceeds limit (<n> bytes)”.

422

The pairing letters are unknown, already used or have run out; or confirm: true came without a pairing.

429

Too many tries.

501

The player is not available on this server.

Retrieve the screens a screen looks like

PermissionScreens · Read

Needs an editor’s or an owner’s key or session. One screen’s own view (GET /devices/{id}) lists the first 20 screens it may be the same machine as, with looksLikeCount the total and looksLikeNext a cursor when there are more. This returns the rest a page at a time: pass looksLikeNext as after. Screens come in id order, so none is repeated or missed while you page, and only screens inside your key’s scope are counted.

Path parameters

  • idstring (uuid)Required

Query parameters

  • afterstring (uuid)Optional

    The looksLikeNext of the view, or the next of the previous page. Omit for the first page.

  • limitintegerOptional

    How many to return; at most 500 are returned whatever is asked (use the cursor for the rest).

    Default20

Returns

A page of the screens it looks like.

An object with:

  • looksLikearray of objectsRequired
    Show child attributesHide child attributes
    • idstring (uuid)Optional
    • namestringOptional
    • whystringOptional

      What the match rests on. Both are what the PC itself reported (its serial and maker, or its TPM key hash): a claim, not proof. Check the install key and the time it joined before you replace a screen with it.

      Possible valuesserialtpm

  • looksLikeCountintegerRequired

    How many screens it looks like in all, not only on this page.

  • nextstringRequiredNullable

    The after for the next page; null on the last.

Errors

StatusCodeMeaning
400bad_limitbad_after

bad_limit or bad_after.

401invalid_token

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

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

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 (Mestra screens are off).

501

The player is not available on this server.

Update a screen

PermissionScreens · Write

Needs an editor’s or an owner’s key or session, and an editor may only rename: name is the one field an editor can send, and any other field is refused 403 owner_only with that field, before anything changes (rename needs the Screens · Write permission on a key). At least one field. stopShow is same (as all screens), black or logo (the logo chosen for all screens; 409 no_logo until one is). A screen’s own image is set by POST /player/stop-image?device=. Stopping or starting reaches the screen at once. A key that may only stop screens uses POST /api/v1/player/devices/{id}/stop; starting a screen needs this call with stopped false. transition is cut, fade, or null for the same as all screens: how this screen moves from one ad to the next. For an owner’s session or a key with the Screens write permission, hours, brightness, sound and panelVolume are this screen’s own settings: absent keeps them, "same" (or null) follows the site, and a value replaces them. A plugin’s app token may not change them (403 session_only). The answer shows them, but never the panel link to a key. location is the screen’s own place, for Dynamic’s lat, lon, city, state and postcode signals: absent keeps it, "same" (or null) follows its site, and an object replaces it. Only an owner can change it, and a plugin’s app token may not (403 session_only). A bad one is 400 with field location.

Path parameters

  • idstring (uuid)Required

Body parameters

  • namestringOptional
  • stoppedbooleanOptional
  • stopShowstringOptional

    Possible valuessameblacklogo

  • transitionstringOptionalNullable

    cut, fade, or null for the same as all screens: how this screen moves from one ad to the next.

    Possible valuescutfadenull

  • hoursone ofOptional

    same, or this screen’s on and off times. A session, or a key with the Screens write permission (not a plugin’s app token).

    One of

    string

    Possible valuessame

    MestraHours array
  • brightnessone ofOptional

    same, or this screen’s brightness times. A session, or a key with the Screens write permission (not a plugin’s app token).

    One of

    string

    Possible valuessame

    MestraBrightness array
  • soundstringOptional

    same (the site’s), on or off. A session, or a key with the Screens write permission (not a plugin’s app token).

    Possible valuessameonoff

  • panelVolumeone ofOptional

    same (the site’s), or 0 to 100. A session, or a key with the Screens write permission (not a plugin’s app token).

    One of

    string

    Possible valuessame

    integer
  • locationone ofOptional

    same (the site’s), or this screen’s own place. An owner only; not a plugin’s app token.

    One of

    string

    Possible valuessame

    MestraLocation object
    • latnumberOptional
    • lonnumberOptional
    • namestringOptional
    • addressstringOptional
    • citystringOptional
    • statestringOptional
    • postcodestringOptional
  • framesobjectOptional

    Replace the screen’s frames: version is the frames.version you read, frames the whole set. A frame with an id keeps that frame and its bookings; one without is new; one left out is removed. Frames are judged against the screen’s window, which comes from its panel profile. Only a named single screen that is in no group takes frames.

    Show child attributesHide child attributes
    • versionintegerRequired
    • framesarray of objectsRequired
      Show child attributesHide child attributes
      • idstring (uuid)Optional

        Leave out for a new frame.

      • namestringRequired

        Unique on the screen, in any case.

      • xintegerRequired

        From the window’s top left, in the turned window’s pixels.

      • yintegerRequired
      • wintegerRequired
      • hintegerRequired
      • layerintegerOptional

        A higher layer is in front.

      • soundbooleanOptional

        Only one frame on a screen can have sound.

Returns

The screen as it is now.

Returns the Screen object.

Errors

StatusCodeMeaning
400bad_frameframe_outside_windowtwo_sound_framesnot_single

Nothing to change, or a bad name, stopShow, hours, brightness or frames (with field). A frames refusal has a code: bad_frame (bad frame values, or two frames with one name), frame_outside_window (a frame not inside the turned window), two_sound_frames (more than one frame with sound), or not_single (frames on a group, on an unassigned screen, or on a screen in a group).

401invalid_token

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

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

404unknown_screennot_connected

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

409api_offintegration_offno_logo

api_off (an owner hasn’t turned the API on), integration_off (Mestra screens are off), no_logo, conflict (the frames changed since frames.version was read), or booked (a frame change that would leave live or draft bookings the wrong shape or size: bookings lists them as “{id, name, publicationId}”).

413

“body exceeds limit (<n> bytes)”.

501

The player is not available on this server.

Delete a screen

PermissionScreens · Write

Needs an owner’s key or session. Deletes the screen: its key stops working at once, and a takedown still waiting for it counts it as removed. Its plays are kept, and so are the bookings that named it; nothing plays on it again.

Path parameters

  • idstring (uuid)Required

Returns

Removed.

Errors

StatusCodeMeaning
401invalid_token

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

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

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 (Mestra screens are off).

501

The player is not available on this server.

List all brands a screen can be placed in

PermissionScreens · Read

Any member’s session (viewer, editor or owner), or a key with the Screens permission and no limit to some screens. The brands of the organisation, by key and name and nothing else of their settings: the choice for placing a screen. A screen joins a brand with POST /devices/assign.

Returns

The brands.

An object with:

  • brandsarray of objectsOptional
    Show child attributesHide child attributes
    • keystringOptional
    • namestringOptional

Errors

StatusCodeMeaning
401invalid_token

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

403wrong_keyscreens_limited

wrong_key (the key lacks the Screens permission) or screens_limited (the key is limited to some screens).

404not_connected

not_connected.

409api_offintegration_off

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

List all screens at a glance

PermissionScreens · Read

Any member’s session (viewer, editor or owner), or a key with the Screens permission. Returns a page of the organisation’s screens, by name, each with its status (online, offline, stopped or never, which has not called in yet) and three 24-point series for the last 24 hours, oldest hour first: online (the share of the hour, 0 to 1, Mestra was hearing from the screen; null before it was added, and all null for one that has never called), plays (plays an hour) and issues (problems an hour). kind is screen or group; a group’s figures are its members’. windowStart is the start of the first hour. It reads Mestra’s own records, so it works whatever else is down. A key limited to some screens sees only those. loopToday is what the screen’s loop plan puts on screen on its own local day, planned and not played (see its field); null when the screen has no plan for today. grafanaUrl is null unless hosted dashboards are set up.

Query parameters

  • limitintegerOptional

    Screens in the page.

    Default50

  • offsetintegerOptional

    Screens to skip.

    Default0

  • idarray of stringsOptional

    Only these screens or groups (repeat the parameter). An id that is not one of the caller’s screens is left out of the answer; limit and offset are then ignored.

Returns

The page.

An object with:

  • screensarray of objectsRequired
    Show child attributesHide child attributes
    • idstring (uuid)Required
    • namestringRequired
    • kindstringRequired

      Possible valuesscreengroup

    • statusstringRequired

      Possible valuesonlineofflinestoppednever

    • lastSeenAtstring (date-time)RequiredNullable
    • onlinearray of numbersRequired
    • playsarray of integersRequired
    • issuesarray of integersRequired
    • loopTodayobjectRequiredNullable

      What the loop plan puts on screen on the screen’s own local day. It is planned, not played: the screen logs no play for a gap and does not mark a fill, so these come from the plan, and a change during the day re-plans the whole day. Null when the screen has no plan for today or is stopped. A group’s is its members’ added together.

      Show child attributesHide child attributes
      • paidFillsintegerRequired

        Turns smart fill added to the loop from paid bookings.

      • houseFillsintegerRequired

        Turns smart fill added from house items.

      • gapsintegerRequired

        Gap turns (the stop show between items) when nothing else could play.

      • gapSecondsintegerRequired

        Total length of those gaps, in seconds.

    • grafanaUrlstringRequiredNullable
  • totalintegerRequired

    Screens in all, for paging.

  • limitintegerRequired
  • offsetintegerRequired
  • windowStartstring (date-time)Required
  • bucketSecondsintegerRequired
  • grafanaUrlstringRequiredNullable

Errors

StatusCodeMeaning
400

limit or offset is out of range (the answer names the 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.

404not_connected

not_connected.

409api_offintegration_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.

Retrieve a screen's schedule

PermissionScreens · Read

Needs an editor’s or owner’s key or session. What the screen plays: items, its bookings in loop order, each with its dates, daypart window (windowStart and windowEnd, when it has one) and timezone, its name and publicationId (null when it has none). A group also answers slots, the plays from from to to (RFC 3339; default now and one loop, never more than 24 hours) with each start and end; a single screen’s slots is null. No file address and no volume are given.

Path parameters

  • idstring (uuid)Required

Query parameters

  • fromstring (date-time)Optional

    A group only; default now.

  • tostring (date-time)Optional

    A group only; default one loop after from. Never more than 24 hours after it.

Returns

The screen’s schedule.

An object with:

  • screenobjectRequired
    Show child attributesHide child attributes
    • idstring (uuid)Required
    • kindstringRequired

      Possible valuessinglegroup

  • itemsarray of objectsRequired
    Show child attributesHide child attributes
    • entryIdstring (uuid)Required
    • namestringRequired
    • publicationIdstringRequiredNullable
    • bookingNamestringRequired

      What the booking is called: a content booking’s own name, else name.

    • statusstringRequired

      Possible valuesdraftlive

    • campaignobjectOptional

      Only when the booking is in a campaign.

      Show child attributesHide child attributes
      • idstring (uuid)Optional
      • namestringOptional
    • daysarray of stringsOptional

      Only when the booking plays on some weekdays.

      Each is one ofmontuewedthufrisatsun

    • sha256stringRequired
    • mimestringRequired
    • durationMsintegerRequired
    • slotsintegerRequired

      How many times in a row it plays in each turn of the loop, as asked.

    • turnsintegerOptional

      How many turns the loop gives it when every item is live, which is what it does; slots is what was asked. The same as slots when the screen has no plan for that set. See getMestraScreenLoop.

    • startDatestringRequired

      YYYY-MM-DD in timezone.

    • endDatestringRequired

      YYYY-MM-DD in timezone, inclusive.

    • windowStartstringOptional

      HH:MM; only when the booking has a daypart window.

    • windowEndstringOptional

      HH:MM.

    • timezonestringRequired
  • slotsarray of objectsRequiredNullable

    A group only; null for a single screen.

    Show child attributesHide child attributes
    • entryIdstring (uuid)RequiredNullable

      Null for filler, a slot with no booking.

    • namestringRequired
    • publicationIdstringRequiredNullable
    • durationMsintegerRequired
    • startstring (date-time)Required
    • endstring (date-time)Required

Errors

StatusCodeMeaning
400

from or to isn’t a time, or to isn’t after from.

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 (Mestra screens are off).

501

The player is not available on this server.

Retrieve the schedule across screens

PermissionScreens · Read

Every screen’s bookings over a range of days in one read, with what each screen is showing now and next. Any member or key that can read screens may call it. from and to are days (YYYY-MM-DD), both inclusive, at most 31 days apart. A screen lists each draft or live booking that overlaps the range, including one with no end date; windowStart, windowEnd and days narrow when it plays inside those days, in the booking’s timezone. Without site or screen it answers every screen the caller can read (a group once, not its members); site limits it to one site’s screens, screen to one screen. now and next are the same as on a screen in getMestraScreens.

Query parameters

  • fromstring (date)Required

    First day, YYYY-MM-DD.

  • tostring (date)Required

    Last day, YYYY-MM-DD; not before from, at most 31 days after it.

  • sitestringOptional

    A site’s key. Not with screen.

  • screenstring (uuid)Optional

    One screen. Not with site.

Returns

The schedule.

An object with:

  • fromstringRequired
  • tostringRequired
  • screensarray of objectsRequired
    Show child attributesHide child attributes
    • idstring (uuid)Required
    • namestringRequired
    • kindstringRequired

      Possible valuessinglegroup

    • siteobjectRequiredNullable
      Show child attributesHide child attributes
      • keystringOptional
      • namestringOptional
    • timezonestringRequired
    • nowobjectRequired

      What the screen is showing: state (playing, stopped, unknown and so on), the entry when playing, and since.

    • nextobjectRequiredNullable

      entry: what comes after; null while stopped or unknown.

    • entriesarray of objectsRequired
      Show child attributesHide child attributes
      • entryIdstring (uuid)Required
      • namestringRequired
      • bookingNamestringRequired
      • statusstringRequired

        Possible valuesdraftlive

      • publicationIdstringRequiredNullable
      • campaignobjectOptional
        Show child attributesHide child attributes
        • idstring (uuid)Optional
        • namestringOptional
      • sha256stringRequired
      • mimestringRequired
      • durationMsintegerRequired
      • slotsintegerRequired
      • startDatestringRequired

        YYYY-MM-DD in timezone; empty for no start.

      • endDatestringRequired

        YYYY-MM-DD in timezone, inclusive; empty for no end.

      • daysarray of stringsOptional
      • windowStartstringOptional
      • windowEndstringOptional
      • timezonestringRequired

Errors

StatusCodeMeaning
400range_too_long

from or to isn’t a day, to is before from, both site and screen were given, or range_too_long (more than 31 days).

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.

404unknown_screenunknown_sitenot_connected

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

409api_offintegration_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.

Update many screens at once

PermissionScreens · Write

Needs the Screens write permission and an owner. Each item names a screen by its device id or by its hardware serial (matched among all the organisation’s screens), then says what to set: name, site (the brand’s code; "" unlinks the screen) and opencrsRef ("" clears it). A field left out is left alone. Writing a name or a brand takes the screen out of the unassigned pool. All or nothing: every row is judged first, and if any row’s outcome is not assigned, unchanged or skipped nothing is written and the answer is 422 with every row’s result. With dryRun: true the rows are judged exactly as for a real run and nothing is written. With unassignedOnly: true a row whose screen has been set up since it was picked is not_unassigned and the answer is 409. Outcomes: assigned, unchanged, skipped, no_match, duplicate_serial, bad_name, unknown_site, unknown_opencrs, opencrs_taken, twice_in_batch, nothing_to_change, on_screens (a screen showing a booking cannot be moved to another brand or unlinked), spreadsheet_number, not_unassigned, key_check. batch is empty when nothing was written. A key limited to some screens may set up only screens it holds, each named by its device id (not by serial), and link them only to the sites in its limit; any other row refuses the whole request with 403 screens_limited and nothing is judged or written. A key limited to groups only has no site to link to. It may unlink a screen it holds (site "") and clear an OpenCRS tie, but not set one: a row with a non-empty opencrsRef is refused the same way.

Body parameters

  • itemsarray of objectsRequired
    Show child attributesHide child attributes
    • devicestring (uuid)Optional

      The screen’s id. Used before serial when both are given.

    • serialstringOptional

      The hardware serial the screen reported.

    • namestringOptional
    • sitestringOptional

      A brand’s code; empty unlinks.

    • opencrsRefstringOptional

      An OpenCRS screen ref; empty clears.

  • skipUnmatchedbooleanOptional

    Skip rows that match no screen instead of refusing the batch.

  • dryRunbooleanOptional
  • unassignedOnlybooleanOptional

    The screens were picked from the Unassigned pool: a row whose screen has been set up since is not_unassigned and refuses the batch with 409.

Returns

Written (applied: true, with the batch), or a dry run that would be written (applied: false).

An object with:

  • batchstring (uuid)Optional

    Names the batch that was written; empty when nothing was.

  • appliedbooleanRequired
  • dryRunbooleanOptional
  • ignoredColumnsarray of stringsOptional

    Only from assign-csv: the file’s column headings that were not read.

  • resultsarray of objectsRequired
    Show child attributesHide child attributes
    • rowintegerRequired

      The item’s 1-based position in the request.

    • devicestring (uuid)Optional

      The screen the row resolved to.

    • outcomestringRequired

      Possible valuesassignedunchangedskippedno_matchduplicate_serialbad_nameunknown_siteunknown_opencrsopencrs_takentwice_in_batchnothing_to_changeon_screensspreadsheet_numbernot_unassignedkey_check

    • messagestringOptional
    • screenobjectOptional

      The screen the row matched, as the row found it, so a dry run shows what Apply would change: check that the key it joined with, when it joined and its hardware are the ones you expect (a serial is only what the screen says). Left out when the row matched no screen.

      Show child attributesHide child attributes
      • namestringOptional
      • unassignedbooleanOptional
      • enrolledAtstring (date-time)Optional
      • enrolledViaobjectOptionalNullable
        Show child attributesHide child attributes
        • idstring (uuid)Optional
        • namestringOptional
      • hardwareobjectOptional
        Show child attributesHide child attributes
        • manufacturerstringOptional
        • modelstringOptional
        • serialstringOptional
        • tpmbooleanOptional
      • possibleCopybooleanOptional

Errors

StatusCodeMeaning
400

No items (field is items).

401invalid_token

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

403wrong_keyscreens_limited

wrong_key, screens_limited, or a role below an owner’s.

404not_connected

not_connected.

409api_offintegration_offtoo_many_linksopencrs_takenon_screensunknown_sitenot_unassigned

api_off (an owner hasn’t turned the API on), or integration_off; too_many_links; a change that landed first (an answer with results, where the row that lost is opencrs_taken, on_screens or unknown_site); or, with unassignedOnly, a row that is not_unassigned (an answer with results; nothing written, dry run or not).

413

“body exceeds limit (<n> bytes)”.

422

A row refused the batch; nothing was written. results has every row.

501

The player is not available on this server.

Update screens from a CSV

PermissionScreens · Write

Needs the Screens write permission and an owner. The same as assigning many screens at once (same permission, all-or-nothing rule, dry run, outcomes and statuses), with the rows read from a CSV in csv. The first row is a header, matched without regard to case: serial, device, name, site (or the older centre) and opencrs; the file needs serial or device. Other columns are ignored and listed in ignoredColumns (the exported file’s manufacturer, model, enrolled and key among them). A BOM and CRLF line ends are accepted. In a cell, an empty value leaves the field alone and exactly - clears it. A key limited to some screens may set up only screens it holds, each named by its device id (not by serial), and link them only to the sites in its limit; any other row refuses the whole request with 403 screens_limited and nothing is judged or written. A key limited to groups only has no site to link to. It may unlink a screen it holds (site "") and clear an OpenCRS tie, but not set one: a row with a non-empty opencrsRef is refused the same way.

Body parameters

  • csvstringRequired
  • skipUnmatchedbooleanOptional
  • dryRunbooleanOptional

Returns

Written, or a dry run that would be written.

An object with:

  • batchstring (uuid)Optional

    Names the batch that was written; empty when nothing was.

  • appliedbooleanRequired
  • dryRunbooleanOptional
  • ignoredColumnsarray of stringsOptional

    Only from assign-csv: the file’s column headings that were not read.

  • resultsarray of objectsRequired
    Show child attributesHide child attributes
    • rowintegerRequired

      The item’s 1-based position in the request.

    • devicestring (uuid)Optional

      The screen the row resolved to.

    • outcomestringRequired

      Possible valuesassignedunchangedskippedno_matchduplicate_serialbad_nameunknown_siteunknown_opencrsopencrs_takentwice_in_batchnothing_to_changeon_screensspreadsheet_numbernot_unassignedkey_check

    • messagestringOptional
    • screenobjectOptional

      The screen the row matched, as the row found it, so a dry run shows what Apply would change: check that the key it joined with, when it joined and its hardware are the ones you expect (a serial is only what the screen says). Left out when the row matched no screen.

      Show child attributesHide child attributes
      • namestringOptional
      • unassignedbooleanOptional
      • enrolledAtstring (date-time)Optional
      • enrolledViaobjectOptionalNullable
        Show child attributesHide child attributes
        • idstring (uuid)Optional
        • namestringOptional
      • hardwareobjectOptional
        Show child attributesHide child attributes
        • manufacturerstringOptional
        • modelstringOptional
        • serialstringOptional
        • tpmbooleanOptional
      • possibleCopybooleanOptional

Errors

StatusCodeMeaning
400

The file is empty, is not valid CSV, has no serial or device column or has no rows (field is csv).

401invalid_token

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

403wrong_keyscreens_limited

wrong_key, screens_limited, or a role below an owner’s.

404not_connected

not_connected.

409api_offintegration_offtoo_many_linkstry_again

api_off (an owner hasn’t turned the API on), or As assign: integration_off, too_many_links, try_again, or a change that landed first.

413

“body exceeds limit (<n> bytes)”.

422

A row refused the batch; nothing was written.

501

The player is not available on this server.

Download screens as CSV

PermissionScreens · Read

Needs the Screens read permission and an editor. Every screen the filter matches, as a CSV download with no page limit. The header row is device,serial,manufacturer,model,enrolled,key,name,site,opencrs. The key column (install key names) is filled only for an owner or a key with the Screens write permission. A cell that starts with =, +, -, @, a tab or a carriage return begins with ' so a spreadsheet won’t run it; uploading the file back takes that ' off again. It streams: if it fails part-way the connection is cut without a clean end, so treat a download that ends in an error as incomplete. A key limited to some screens gets the rows of those screens (and the members of its groups) only.

Query parameters

  • unassignedbooleanOptional

    Only screens nobody has named yet (true), or only the named ones (false).

Returns

The screens, as CSV.

Errors

StatusCodeMeaning
400bad_unassigned

bad_unassigned.

401invalid_token

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

403wrong_keyscreens_limited

wrong_key, screens_limited, or a role below an editor’s.

404not_connected

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.

Update a screen to use a new player

PermissionScreens · Write

Needs the Screens write permission and an owner. A machine was re-imaged and joined again as a new, unset-up player; this puts the old screen onto it. The old screen keeps its id, name, site, layout, bookings and plays; it takes the new player’s key and everything the device reported. The new player’s own entry is removed, and the old machine’s key stops working. Answers 409 replace_not_new if the new player has been set up, replace_online if the old screen called in within the last 3 minutes (send evenIfOnline to go on), replace_copy if the new player is flagged as a possible copy (send evenIfCopy), replace_held if the new player is still held by its install key check (send evenIfHeld), or replace_key if the new player joined with another install key than the old screen did (send evenIfKey). Both ids must be screens of this organisation, else 404 unknown_screen. Repeating a call that already succeeded answers 200 again and changes nothing. A key limited to some screens must hold both screens, else 404 unknown_screen.

Path parameters

  • idstring (uuid)Required

    The new player: a screen that joined with an install key and has not been set up.

Body parameters

  • replacesstring (uuid)Required

    The screen being replaced; it stays.

  • evenIfOnlinebooleanOptional
  • evenIfCopybooleanOptional
  • evenIfKeybooleanOptional
  • evenIfHeldbooleanOptional

Returns

The kept screen, now on the new player.

Returns the Screen object.

Errors

StatusCodeMeaning
400

replaces missing, or the same screen.

401invalid_token

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

403wrong_key

403 for a role below the route’s minimum (“Your role (<role>) can’t <action>.”, or “Choose an organisation first.”), or, for an API key without the permission this call needs, code wrong_key with “This key needs the <Area> · <Read|Write> permission.” (for example “This key needs the Reviews · Write permission.”), or “This key can’t do that.” for a call only the Mestra apps make.

404unknown_screennot_connected

unknown_screen, or not_connected.

409api_offreplace_not_newreplace_onlinereplace_copyreplace_heldreplace_keytry_againintegration_off

api_off (an owner hasn’t turned the API on), or replace_not_new, replace_online, replace_copy, replace_held, replace_key, try_again, or integration_off.

413

“body exceeds limit (<n> bytes)”.

501

The player is not available on this server.

Delete many screens

PermissionScreens · Write

Needs the Screens write permission and an owner. All or nothing: if any id is not a screen of this organisation, nothing is removed and the answer is 404 unknown_screen with the first such id in device. A repeated id counts once. With unassignedOnly: true, if any of the screens has been set up since it was picked nothing is removed and the answer is 409 not_unassigned with those screens’ ids in devices. Each removed screen’s key stops working at once. A key limited to some screens may remove only screens it holds: if any named screen is outside its scope the answer is 403 screens_limited and nothing is removed.

Body parameters

  • devicesarray of stringsRequired
  • unassignedOnlybooleanOptional

    Remove only if every screen is still unassigned; otherwise 409 not_unassigned and nothing is removed.

Returns

Removed.

An object with:

  • removedintegerRequired

Errors

StatusCodeMeaning
400

No devices (field is devices).

401invalid_token

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

403wrong_key

403 for a role below the route’s minimum (“Your role (<role>) can’t <action>.”, or “Choose an organisation first.”), or, for an API key without the permission this call needs, code wrong_key with “This key needs the <Area> · <Read|Write> permission.” (for example “This key needs the Reviews · Write permission.”), or “This key can’t do that.” for a call only the Mestra apps make.

404unknown_screennot_connected

unknown_screen (with device), or not_connected.

409api_offintegration_offnot_unassigned

api_off (an owner hasn’t turned the API on), or integration_off, or not_unassigned (with unassignedOnly; devices lists the screens set up since they were picked).

413

“body exceeds limit (<n> bytes)”.

501

The player is not available on this server.

Update a screen's power

PermissionScreens · Write

Needs the Screens write permission and an owner. power is on, off or schedule: on and off hold the panel that way until until (a future time) or, without it, until changed; schedule clears the hold and goes back to the screen’s on and off times. The screen is told at once. A screen’s power may be changed a limited number of times an hour (429). A key limited to some screens may act only on its own (404 unknown_screen for others). A key with only the Screens read or takedown permission cannot do this.

Path parameters

  • idstring (uuid)Required

Body parameters

  • powerstringRequired

    Possible valuesonoffschedule

  • untilstring (date-time)Optional

    In the future. Only with on or off; without it the hold lasts until changed.

Returns

The screen as it is now.

Returns the Screen object.

Errors

StatusCodeMeaning
400

A bad power, or an until that is not a future time (with field).

401invalid_token

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

403wrong_keyscreens_limited

wrong_key, screens_limited, or a role below an owner’s.

404unknown_screennot_connected

unknown_screen, or not_connected.

409api_offintegration_off

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

413

“body exceeds limit (<n> bytes)”.

429rate_limited

rate_limited: the power was changed too often in the last hour (Retry-After says when to try again).

501

The player is not available on this server.