API reference
Screens
A screen is a display running Mestra Player.
A key’s Screens permission has three levels. Read: see screens, their schedule, health and proof of play, and screenshots and log bundles. Takedown: also stop screens and sites and pull ads, but can’t start them again. Write: also pair, rename, remove and start screens, enrol them, change their settings, restart or reboot them, and switch their panels (power, hours, brightness and sound). A key can be limited to some sites and screen groups when it is made; see the Player API overview.
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)OptionalnamestringOptionalwidthintegerOptionalThe screen’s pixels; 0 until known.
heightintegerOptionaltimezonestringOptionalappVersionstringOptionalonlinebooleanOptionallastSeenAtstring (date-time)OptionalNullablestoppedbooleanOptionalstopShowstringOptionalThis screen’s own choice of what it shows while stopped;
samefollows the organisation’s.Possible values
sameblacklogoimagevideositeStopShowstringOptionalThe choice of the screen’s site (
samefollows the choice for all screens); empty when the screen has no site.Possible values
sameblacklogoimagestopShowFromstringOptionalWhere what the screen shows while stopped comes from: its own choice (
screen), its site’s (site) or the choice for all screens (org).Possible values
screensiteorgunassignedbooleanOptionalTrue for a screen that joined with an install key and no owner has named yet.
windowobjectOptionalNullableThe 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
profileobjectOptionalThe panel profile the window comes from.
Show child attributesHide child attributes
idstringOptionalnamestringOptional
xintegerOptionalyintegerOptionalwintegerOptionalhintegerOptionalrotationintegerOptionalPossible values
090180270placeWintegerOptionalplaceHintegerOptional
framesobjectOptionalA 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
versionintegerOptionalSend it back to change the frames.
framesarray of objectsOptionalShow child attributesHide child attributes
idstring (uuid)OptionalnamestringOptionalxintegerOptionalyintegerOptionalwintegerOptionalhintegerOptionallayerintegerOptionalsoundbooleanOptional
orgStoppedbooleanOptionalTrue while every screen is stopped: the organisation’s own stop is on, or the organisation is halted (
orgHalt).transitionstringOptionalThis screen’s own change between ads;
samefollows the organisation’s.Possible values
samecutfadeh265booleanOptionalThe screen reported it plays H.265.
html5booleanOptionalThe screen reported it plays HTML5 packages.
decodeAtstring (date-time)OptionalNullableWhen the screen’s reported decoders last changed; null until it has reported.
decodearray of objectsOptionalNullableWhat the screen says it decodes, as the server kept it: for each codec and frame rate, the largest picture it plays smoothly.
nulluntil 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
codecstringOptionalPossible values
h264h265vp9av1maxSideintegerOptionalThe longest side, in pixels.
maxPixelsinteger (int64)OptionalWidth times height, in pixels.
fpsintegerOptionalThe frame-rate tier this entry covers.
Possible values
3060
cantPlayarray of objectsOptionalThe files of this screen’s live bookings that it can’t play, and why. Empty when it plays them all.
reasonisno_codec(codecis the one it lacks),too_big(maxWidthandmaxHeightare the largest picture it decodes for the codec),too_fast(maxFpsis its highest frame rate),no_html5(detailis why HTML5 is off) orno_report(the screen hasn’t said what it plays).Show child attributesHide child attributes
namestringOptionalThe booking’s name.
reasonstringOptionalPossible values
no_codectoo_bigtoo_fastno_html5no_reportcodecstringOptionalPossible values
h264h265vp9av1detailstringOptionalmaxWidthintegerOptionalmaxHeightintegerOptionalmaxFpsintegerOptional
stopVideoCantPlayobjectOptionalPresent when this screen is meant to show a stop video it can’t play: it shows black instead.
nameisstop video;reasonand the rest are as incantPlay.Show child attributesHide child attributes
namestringOptionalreasonstringOptionalPossible values
no_codectoo_bigtoo_fastno_html5no_reportcodecstringOptionalPossible values
h264h265vp9av1detailstringOptionalmaxWidthintegerOptionalmaxHeightintegerOptionalmaxFpsintegerOptional
html5OffstringOptionalWhy 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 values
startingshell_not_readynet_jailmute_unconfirmedorgHaltstringOptionalWhy the organisation’s screens are halted and black:
read_only(the account is read-only; they start again when it is active) ordisabled(disabled, or scheduled for deletion). Empty when they are not.Possible values
read_onlydisabledhardwareobjectOptionalWhat the screen says it is (its own claim, never proof).
tpmis true when it reported a TPM endorsement key; the key itself is never shown.Show child attributesHide child attributes
manufacturerstringOptionalmodelstringOptionalserialstringOptionaltpmbooleanOptionalserialSharedbooleanOptionalTrue 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.
enrolledViaobjectOptionalNullableThe install key the screen joined with; null for a screen added with a code.
nameis 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)OptionalnamestringOptional
enrolledAtstring (date-time)OptionalWhen the screen joined (paired or enrolled). It never changes; the unassigned pool is listed in this order.
opencrsRefstringOptionalNullableThe OpenCRS screen this screen is the face of, or null.
looksLikeCountintegerOptionalHow 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 objectsOptionalOnly 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.looksLikeCountis the total; when there are more,looksLikeNextis the cursor to pass toGET /devices/{id}/looks-likeasafter.Show child attributesHide child attributes
idstring (uuid)OptionalnamestringOptionalwhystringOptionalWhat 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 values
serialtpm
looksLikeNextstringOptionalOnly in one screen’s own view, and only when
looksLikeis not the whole list: theafterforGET /devices/{id}/looks-like.possibleCopybooleanOptionalTrue 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.copyProvenbooleanOptionalTrue 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).
keyCheckobjectOptionalNullableA PC set up from a provisioning package plays nothing until its check that Windows’ readable copy of the install key is gone has passed.
stateischecking,failed(the check could not finish;reasonsays why, and it tries again by itself) orexposed(it proved a readable copy of the key: revoke the key;reasonnames the places, with any piece of the key in a name masked).sinceis when the hold was first seen. Null when the screen is not held.checkingandfailed, and a failure’sreason, 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).exposedis Mestra’s own mark, set only from a report the server verified against the key the screen joined with.Show child attributesHide child attributes
statestringOptionalPossible values
checkingfailedexposedreasonstringOptionalsincestring (date-time)OptionalNullable
siteCodestringOptionalThe code of the site the screen is linked to; empty when it is not linked.
kindstringOptionalsingleis a PC;groupis a screen group: one screen made of several, with no PC of its own.Possible values
singlegroupgroupobjectOptionalOn 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)OptionalnamestringOptionalpositionintegerOptional
membersarray of objectsOptionalOn a group: its screens, by place.
Show child attributesHide child attributes
idstring (uuid)OptionalnamestringOptionalpositionintegerOptionalonlinebooleanOptional
layoutobjectOptionalOn a group: its rows and columns, the gap and size you gave, the canvas that comes to, and the
versionto send with a change.Show child attributesHide child attributes
rowsintegerOptionalcolsintegerOptionalbezelMmnumberOptionalNullablediagInnumberOptionalNullablecanvasWintegerOptionalcanvasHintegerOptionalgapPxintegerOptionalcellWintegerOptionalcellHintegerOptionalplacedbooleanOptionalplacingbooleanOptionalversionintegerOptionalidentifyUntilstring (date-time)OptionalNullable
lookbooleanOptionalThe screen needs a look: it last showed something other than what it was told to, or it has several displays and Mestra uses one.
syncStatestringOptionalOn a placed group, in a paged list only: whether its screens are in step.
Possible values
placingin_stepout_of_stepunknownsyncLatearray of integersOptionalOn a group that is out of step, in a paged list only: the positions of the members the reasons name, in order.
displayobjectOptionalNullableWhat 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) andsizeChanged(the size before its last change);nullfrom a group and a PC that has not said.Show child attributesHide child attributes
monitorsintegerOptionalprimaryWintegerOptionalprimaryHintegerOptionalvirtualWintegerOptionalvirtualHintegerOptionalnotSpannedbooleanOptionalspannedbooleanOptionalsizeChangedobjectOptionalNullableShow child attributesHide child attributes
fromWintegerOptionalfromHintegerOptionaltoWintegerOptionaltoHintegerOptional
soundstringOptionalNullableThis screen’s own sound setting;
nullfollows its site.Possible values
onoffnullpanelVolumeintegerOptionalNullableThis screen’s own panel volume;
nullfollows its site.hoursarray of valuesOptionalNullableThis screen’s own on and off times;
nullfollows its site.brightnessarray of valuesOptionalNullableThis screen’s own brightness times;
nullfollows its site.locationobjectOptionalNullableThis screen’s own place;
nullfollows its site.Show child attributesHide child attributes
latnumberOptionallonnumberOptionalnamestringOptionaladdressstringOptionalcitystringOptionalstatestringOptionalpostcodestringOptional
siteobjectOptionalNullableThe site the screen is linked to; null when it has none.
Show child attributesHide child attributes
keystringOptionalThe brand code.
namestringOptional
nowobjectOptionalWhat the screen is showing, from its last report. While the screen or the organisation is stopped,
stateisstoppedandentryis null, whatever the screen last said.offmeans its panel is switched off.entryis null when the screen isn’t showing an item or the item has been deleted.Show child attributesHide child attributes
statestringOptionalPossible values
playingwaitingpairingstoppedoffunknownentryobjectOptionalNullableShow child attributesHide child attributes
idstring (uuid)OptionalnamestringOptionalsha256stringOptionalThe entry’s file. A screen that is offline or has not caught up may still be showing an earlier one.
publicationIdstring (uuid)OptionalNullableThe publication the item came from; null when the entry has no published item.
sincestring (date-time)OptionalNullable
nextobjectOptionalNullableThe item the screen shows after this one. Null when the screen is stopped or has not said.
Show child attributesHide child attributes
entryobjectOptionalShow child attributesHide child attributes
idstring (uuid)OptionalnamestringOptionalsha256stringOptionalThe entry’s file. A screen that is offline or has not caught up may still be showing an earlier one.
publicationIdstring (uuid)OptionalNullableThe publication the item came from; null when the entry has no published item.
lastShotobjectOptionalOn 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.
thumbis the preview’s address, which holds the shot’s id and never changes.Show child attributesHide child attributes
idstring (uuid)OptionalthumbstringOptionaltakenAtstring (date-time)Optional
healthobjectOptionalonlineis the live check (the screen called within the last 3 minutes).presenceis 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
onlinebooleanOptionalpresencestringOptionalPossible values
onlineofflinepresenceSincestring (date-time)OptionalNullablelastSeenAtstring (date-time)OptionalNullableappVersionstringOptionalcacheBytesinteger (int64)OptionalNullableThe size of the screen’s file cache; null until it reports.
issueobjectOptionalThe screen’s health line: what is wrong, or that it fixed itself, and what to do about it.
Show child attributesHide child attributes
pillstringOptionalPossible values
HealthyFixed itselfNeeds a lookNeeds a visitOfflinetitlestringOptionalfixstringOptionalsincestring (date-time)OptionalNullableWhen the fault began, or when it fixed itself.
codestringOptional
uptimeobjectOptionalThe 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
last30dnumberOptionalNullablelast30dExSitePowernumberOptionalNullableWith the seconds lost to the site’s power left out of both sides.
trendobjectOptionalUptime 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)OptionalThe last of the 30 days.
daysarray of numbersOptional
todayobjectOptionalOn 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,last30dor any signed day. Left out until an hour has been sealed today.Show child attributesHide child attributes
upnumberOptionalNullableUp seconds over counted seconds of those hours, cut (never rounded up) to four places.
hoursintegerOptionalThe sealed hours it rests on.
partialbooleanOptional
lastMismatchobjectOptionalNullableThe last time the screen found a file that failed its check;
entriesare the entry ids (orstopshowfor the stopped picture). Null when it never has.Show child attributesHide child attributes
atstring (date-time)Optionalentriesarray of stringsOptional
diagobjectOptionalNullableWhat 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)OptionaldiskFreeBytesinteger (int64)OptionalNullablediskTotalBytesinteger (int64)OptionalNullablememTotalBytesinteger (int64)OptionalNullablememAvailBytesinteger (int64)OptionalNullableplayerRamBytesinteger (int64)OptionalNullableThe memory the player uses.
tempCnumberOptionalNullableThe PC’s temperature in degrees Celsius.
clockOffsetMsintegerOptionalNullableHow far the PC’s clock is from the server’s, in milliseconds.
bootedAtstring (date-time)OptionalNullableshellUpbooleanOptionalWhether the player’s shell is running.
List all screens
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
sitestringOptionalA site code: list only the screens linked to it.
unassignedbooleanOptionalPages the list (see below): only screens nobody has named yet (true), or only the named ones (false).
keystring (uuid)OptionalPages the list (see below): only the screens that joined with this install key. Needs the Screens write permission.
limitintegerOptionalScreens in a page, at most 200 (50 when left out). With
unassignedorkey, at most 500 and the cursor isafter. Alone it is ignored: the answer is every screen as an array.afterstringOptionalWith
unassignedorkey: thenextof the page before. Ignored otherwise.cursorstringOptionalThe
nextof the previous page. Pages the list, and only for the same filters andsort.kindstringOptionalPages the list: only PCs, or only screen groups.
Possible values
singlegroupstatusstringOptionalPages the list: a stopped screen counts as stopped only, not online or offline.
Possible values
onlineofflinestoppedlookstringOptionalPages the list: only screens that need a look.
Possible values
1attentionstringOptionalPages the list: only screens that need a person now (not stopped, and offline, showing black, with a fault open or needing a look).
Possible values
1nositestringOptionalPages the list: only screens linked to no site. Not with
site.Possible values
1groupstring (uuid)OptionalPages the list: the members of one screen group. Members are otherwise left out of the list.
qstringOptionalPages the list: screens whose name or site name contains this, members of a group included.
sortstringOptionalPages the list: the order. Default name. Status puts offline first, then online, then stopped.
Possible values
namesitestatus
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
| Status | Code | Meaning |
|---|---|---|
400 | bad_unassignedbad_limitbad_after | With |
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_keyscreens_limited |
|
404 | not_connectedunknown_site |
|
409 | api_offintegration_off |
|
501 | The player is not available on this server. |
Retrieve a screen
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
| Status | Code | Meaning |
|---|---|---|
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_keyscreens_limited |
|
404 | unknown_screennot_connected |
|
409 | api_offintegration_off |
|
501 | The player is not available on this server. |
Add a screen by its pairing code
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
codestringRequirednamestringOptionalRequired unless
confirmisfalse.confirmbooleanOptionalfalse: look at the screen without adding it.true: add it (needspairing). Absent: add it at once, with no check (needsname).pairingstringOptionalFrom 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:
pendingobjectRequiredShow child attributesHide child attributes
widthintegerOptionalheightintegerOptionalrotationintegerOptionaltimezonestringOptionallastSeenAtstring (date-time)OptionalNullablehardwareobjectOptionalShow child attributesHide child attributes
manufacturerstringOptionalmodelstringOptionalserialstringOptionaltpmbooleanOptional
pairingstringOptionalSend it back with
confirm: true.
Errors
| Status | Code | Meaning |
|---|---|---|
400 |
| |
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_keyscreens_limited |
|
404 | not_connected |
|
409 | api_offintegration_offpairing_changed |
|
413 | “body exceeds limit (<n> bytes)”. | |
422 | The pairing letters are unknown, already used or have run out; or | |
429 | Too many tries. | |
501 | The player is not available on this server. |
Retrieve the screens a screen looks like
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)OptionalThe
looksLikeNextof the view, or thenextof the previous page. Omit for the first page.limitintegerOptionalHow many to return; at most 500 are returned whatever is asked (use the cursor for the rest).
Default
20
Returns
A page of the screens it looks like.
An object with:
looksLikearray of objectsRequiredShow child attributesHide child attributes
idstring (uuid)OptionalnamestringOptionalwhystringOptionalWhat 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 values
serialtpm
looksLikeCountintegerRequiredHow many screens it looks like in all, not only on this page.
nextstringRequiredNullableThe
afterfor the next page; null on the last.
Errors
| Status | Code | Meaning |
|---|---|---|
400 | bad_limitbad_after |
|
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_keyscreens_limited |
|
404 | unknown_screennot_connected |
|
409 | api_offintegration_off |
|
501 | The player is not available on this server. |
Update a screen
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
namestringOptionalstoppedbooleanOptionalstopShowstringOptionalPossible values
sameblacklogotransitionstringOptionalNullablecut,fade, ornullfor the same as all screens: how this screen moves from one ad to the next.Possible values
cutfadenullhoursone ofOptionalsame, 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
stringPossible values
sameMestraHoursarraybrightnessone ofOptionalsame, or this screen’s brightness times. A session, or a key with the Screens write permission (not a plugin’s app token).One of
stringPossible values
sameMestraBrightnessarraysoundstringOptionalsame(the site’s),onoroff. A session, or a key with the Screens write permission (not a plugin’s app token).Possible values
sameonoffpanelVolumeone ofOptionalsame(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
stringPossible values
sameintegerlocationone ofOptionalsame(the site’s), or this screen’s own place. An owner only; not a plugin’s app token.One of
stringPossible values
sameMestraLocationobjectlatnumberOptionallonnumberOptionalnamestringOptionaladdressstringOptionalcitystringOptionalstatestringOptionalpostcodestringOptional
framesobjectOptionalReplace the screen’s frames:
versionis theframes.versionyou read,framesthe whole set. A frame with anidkeeps 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
versionintegerRequiredframesarray of objectsRequiredShow child attributesHide child attributes
idstring (uuid)OptionalLeave out for a new frame.
namestringRequiredUnique on the screen, in any case.
xintegerRequiredFrom the window’s top left, in the turned window’s pixels.
yintegerRequiredwintegerRequiredhintegerRequiredlayerintegerOptionalA higher layer is in front.
soundbooleanOptionalOnly one frame on a screen can have sound.
Returns
The screen as it is now.
Returns the Screen object.
Errors
| Status | Code | Meaning |
|---|---|---|
400 | bad_frameframe_outside_windowtwo_sound_framesnot_single | Nothing to change, or a bad |
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_keyscreens_limited |
|
404 | unknown_screennot_connected |
|
409 | api_offintegration_offno_logo |
|
413 | “body exceeds limit (<n> bytes)”. | |
501 | The player is not available on this server. |
Delete a screen
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
| Status | Code | Meaning |
|---|---|---|
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_keyscreens_limited |
|
404 | unknown_screennot_connected |
|
409 | api_offintegration_off |
|
501 | The player is not available on this server. |
List all brands a screen can be placed in
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 objectsOptionalShow child attributesHide child attributes
keystringOptionalnamestringOptional
Errors
| Status | Code | Meaning |
|---|---|---|
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_keyscreens_limited |
|
404 | not_connected |
|
409 | api_offintegration_off |
|
List all screens at a glance
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
limitintegerOptionalScreens in the page.
Default
50offsetintegerOptionalScreens to skip.
Default
0idarray of stringsOptionalOnly these screens or groups (repeat the parameter). An id that is not one of the caller’s screens is left out of the answer;
limitandoffsetare then ignored.
Returns
The page.
An object with:
screensarray of objectsRequiredShow child attributesHide child attributes
idstring (uuid)RequirednamestringRequiredkindstringRequiredPossible values
screengroupstatusstringRequiredPossible values
onlineofflinestoppedneverlastSeenAtstring (date-time)RequiredNullableonlinearray of numbersRequiredplaysarray of integersRequiredissuesarray of integersRequiredloopTodayobjectRequiredNullableWhat 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
paidFillsintegerRequiredTurns smart fill added to the loop from paid bookings.
houseFillsintegerRequiredTurns smart fill added from house items.
gapsintegerRequiredGap turns (the stop show between items) when nothing else could play.
gapSecondsintegerRequiredTotal length of those gaps, in seconds.
grafanaUrlstringRequiredNullable
totalintegerRequiredScreens in all, for paging.
limitintegerRequiredoffsetintegerRequiredwindowStartstring (date-time)RequiredbucketSecondsintegerRequiredgrafanaUrlstringRequiredNullable
Errors
| Status | Code | Meaning |
|---|---|---|
400 |
| |
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
404 | not_connected |
|
409 | api_offintegration_off |
|
501 | The player is not available on this server. |
Retrieve a screen's schedule
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)OptionalA group only; default now.
tostring (date-time)OptionalA group only; default one loop after
from. Never more than 24 hours after it.
Returns
The screen’s schedule.
An object with:
screenobjectRequiredShow child attributesHide child attributes
idstring (uuid)RequiredkindstringRequiredPossible values
singlegroup
itemsarray of objectsRequiredShow child attributesHide child attributes
entryIdstring (uuid)RequirednamestringRequiredpublicationIdstringRequiredNullablebookingNamestringRequiredWhat the booking is called: a content booking’s own name, else
name.statusstringRequiredPossible values
draftlivecampaignobjectOptionalOnly when the booking is in a campaign.
Show child attributesHide child attributes
idstring (uuid)OptionalnamestringOptional
daysarray of stringsOptionalOnly when the booking plays on some weekdays.
Each is one of
montuewedthufrisatsunsha256stringRequiredmimestringRequireddurationMsintegerRequiredslotsintegerRequiredHow many times in a row it plays in each turn of the loop, as asked.
turnsintegerOptionalHow many turns the loop gives it when every item is live, which is what it does;
slotsis what was asked. The same asslotswhen the screen has no plan for that set. SeegetMestraScreenLoop.startDatestringRequiredYYYY-MM-DD in
timezone.endDatestringRequiredYYYY-MM-DD in
timezone, inclusive.windowStartstringOptionalHH:MM; only when the booking has a daypart window.
windowEndstringOptionalHH:MM.
timezonestringRequired
slotsarray of objectsRequiredNullableA group only; null for a single screen.
Show child attributesHide child attributes
entryIdstring (uuid)RequiredNullableNull for filler, a slot with no booking.
namestringRequiredpublicationIdstringRequiredNullabledurationMsintegerRequiredstartstring (date-time)Requiredendstring (date-time)Required
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 the schedule across screens
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)RequiredFirst day, YYYY-MM-DD.
tostring (date)RequiredLast day, YYYY-MM-DD; not before
from, at most 31 days after it.sitestringOptionalA site’s key. Not with
screen.screenstring (uuid)OptionalOne screen. Not with
site.
Returns
The schedule.
An object with:
fromstringRequiredtostringRequiredscreensarray of objectsRequiredShow child attributesHide child attributes
idstring (uuid)RequirednamestringRequiredkindstringRequiredPossible values
singlegroupsiteobjectRequiredNullableShow child attributesHide child attributes
keystringOptionalnamestringOptional
timezonestringRequirednowobjectRequiredWhat the screen is showing:
state(playing, stopped, unknown and so on), theentrywhen playing, andsince.nextobjectRequiredNullableentry: what comes after; null while stopped or unknown.entriesarray of objectsRequiredShow child attributesHide child attributes
entryIdstring (uuid)RequirednamestringRequiredbookingNamestringRequiredstatusstringRequiredPossible values
draftlivepublicationIdstringRequiredNullablecampaignobjectOptionalShow child attributesHide child attributes
idstring (uuid)OptionalnamestringOptional
sha256stringRequiredmimestringRequireddurationMsintegerRequiredslotsintegerRequiredstartDatestringRequiredYYYY-MM-DD in
timezone; empty for no start.endDatestringRequiredYYYY-MM-DD in
timezone, inclusive; empty for no end.daysarray of stringsOptionalwindowStartstringOptionalwindowEndstringOptionaltimezonestringRequired
Errors
| Status | Code | Meaning |
|---|---|---|
400 | range_too_long |
|
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
404 | unknown_screenunknown_sitenot_connected |
|
409 | api_offintegration_off |
|
501 | The player is not available on this server. |
Update many screens at once
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 objectsRequiredShow child attributesHide child attributes
devicestring (uuid)OptionalThe screen’s id. Used before
serialwhen both are given.serialstringOptionalThe hardware serial the screen reported.
namestringOptionalsitestringOptionalA brand’s code; empty unlinks.
opencrsRefstringOptionalAn OpenCRS screen ref; empty clears.
skipUnmatchedbooleanOptionalSkip rows that match no screen instead of refusing the batch.
dryRunbooleanOptionalunassignedOnlybooleanOptionalThe screens were picked from the Unassigned pool: a row whose screen has been set up since is
not_unassignedand 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)OptionalNames the batch that was written; empty when nothing was.
appliedbooleanRequireddryRunbooleanOptionalignoredColumnsarray of stringsOptionalOnly from assign-csv: the file’s column headings that were not read.
resultsarray of objectsRequiredShow child attributesHide child attributes
rowintegerRequiredThe item’s 1-based position in the request.
devicestring (uuid)OptionalThe screen the row resolved to.
outcomestringRequiredPossible values
assignedunchangedskippedno_matchduplicate_serialbad_nameunknown_siteunknown_opencrsopencrs_takentwice_in_batchnothing_to_changeon_screensspreadsheet_numbernot_unassignedkey_checkmessagestringOptionalscreenobjectOptionalThe 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
namestringOptionalunassignedbooleanOptionalenrolledAtstring (date-time)OptionalenrolledViaobjectOptionalNullableShow child attributesHide child attributes
idstring (uuid)OptionalnamestringOptional
hardwareobjectOptionalShow child attributesHide child attributes
manufacturerstringOptionalmodelstringOptionalserialstringOptionaltpmbooleanOptional
possibleCopybooleanOptional
Errors
| Status | Code | Meaning |
|---|---|---|
400 | No items ( | |
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_keyscreens_limited |
|
404 | not_connected |
|
409 | api_offintegration_offtoo_many_linksopencrs_takenon_screensunknown_sitenot_unassigned |
|
413 | “body exceeds limit (<n> bytes)”. | |
422 | A row refused the batch; nothing was written. | |
501 | The player is not available on this server. |
Update screens from a CSV
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
csvstringRequiredskipUnmatchedbooleanOptionaldryRunbooleanOptional
Returns
Written, or a dry run that would be written.
An object with:
batchstring (uuid)OptionalNames the batch that was written; empty when nothing was.
appliedbooleanRequireddryRunbooleanOptionalignoredColumnsarray of stringsOptionalOnly from assign-csv: the file’s column headings that were not read.
resultsarray of objectsRequiredShow child attributesHide child attributes
rowintegerRequiredThe item’s 1-based position in the request.
devicestring (uuid)OptionalThe screen the row resolved to.
outcomestringRequiredPossible values
assignedunchangedskippedno_matchduplicate_serialbad_nameunknown_siteunknown_opencrsopencrs_takentwice_in_batchnothing_to_changeon_screensspreadsheet_numbernot_unassignedkey_checkmessagestringOptionalscreenobjectOptionalThe 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
namestringOptionalunassignedbooleanOptionalenrolledAtstring (date-time)OptionalenrolledViaobjectOptionalNullableShow child attributesHide child attributes
idstring (uuid)OptionalnamestringOptional
hardwareobjectOptionalShow child attributesHide child attributes
manufacturerstringOptionalmodelstringOptionalserialstringOptionaltpmbooleanOptional
possibleCopybooleanOptional
Errors
| Status | Code | Meaning |
|---|---|---|
400 | The file is empty, is not valid CSV, has no | |
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_keyscreens_limited |
|
404 | not_connected |
|
409 | api_offintegration_offtoo_many_linkstry_again |
|
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
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
unassignedbooleanOptionalOnly screens nobody has named yet (true), or only the named ones (false).
Returns
The screens, as CSV.
Errors
| Status | Code | Meaning |
|---|---|---|
400 | bad_unassigned |
|
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_keyscreens_limited |
|
404 | not_connected |
|
409 | api_offintegration_off |
|
501 | The player is not available on this server. |
Update a screen to use a new player
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)RequiredThe new player: a screen that joined with an install key and has not been set up.
Body parameters
replacesstring (uuid)RequiredThe screen being replaced; it stays.
evenIfOnlinebooleanOptionalevenIfCopybooleanOptionalevenIfKeybooleanOptionalevenIfHeldbooleanOptional
Returns
The kept screen, now on the new player.
Returns the Screen object.
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_offreplace_not_newreplace_onlinereplace_copyreplace_heldreplace_keytry_againintegration_off |
|
413 | “body exceeds limit (<n> bytes)”. | |
501 | The player is not available on this server. |
Delete many screens
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 stringsRequiredunassignedOnlybooleanOptionalRemove only if every screen is still unassigned; otherwise 409
not_unassignedand nothing is removed.
Returns
Removed.
An object with:
removedintegerRequired
Errors
| Status | Code | Meaning |
|---|---|---|
400 | No devices ( | |
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
404 | unknown_screennot_connected |
|
409 | api_offintegration_offnot_unassigned |
|
413 | “body exceeds limit (<n> bytes)”. | |
501 | The player is not available on this server. |
Update a screen's power
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
powerstringRequiredPossible values
onoffscheduleuntilstring (date-time)OptionalIn the future. Only with
onoroff; without it the hold lasts until changed.
Returns
The screen as it is now.
Returns the Screen object.
Errors
| Status | Code | Meaning |
|---|---|---|
400 | A bad | |
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_keyscreens_limited |
|
404 | unknown_screennot_connected |
|
409 | api_offintegration_off |
|
413 | “body exceeds limit (<n> bytes)”. | |
429 | rate_limited |
|
501 | The player is not available on this server. |