API reference
Sites
A site is a place that screens are linked to, such as a shopping centre or a store. A site has its own time zone, on and off times, brightness and location, and a key can be limited to some sites.
The Site object
A site: its details, a count of its screens by state, and the screens linked to it.
Attributes
siteobjectOptionalShow child attributesHide child attributes
keystringOptionalThe brand code.
namestringOptional
summaryobjectOptionalA site’s screens by state. A stopped screen is also counted online or offline.
Show child attributesHide child attributes
keystringOptionalNullableThe site code; null for the row of screens linked to no site.
namestringOptionalNullablescreensintegerOptionalonlineintegerOptionalofflineintegerOptionalstoppedintegerOptionalplayingintegerOptionalOnline screens that are not stopped and last reported showing an item.
uptimeobjectOptionalThe site’s screens’ last 30 days added up (up seconds over counted seconds, never an average of the screens’ figures). 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
grafanaUrlstringOptionalNullableOpens the site’s dashboard in the organisation’s hosted Grafana, signed in by a hand-off from the viewer. Null unless hosted dashboards are set up, and for the row with no site.
screensarray of objectsOptionalShow child attributesHide child 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 sites
Any member’s session (viewer, editor or owner), or a key with the Screens permission. A site is a brand: the site a screen is linked to. Lists each site with at least one of your Mestra screens, by name, with counts over the screens a key can see, then one row with a null key for screens linked to no site (left out when there are none). online and offline split the screens by the live 3-minute check; stopped counts screens stopped on their own or with the organisation (a stopped screen is also online or offline); playing counts online screens that are not stopped and last reported showing an item.
Returns
The sites.
A list of objects, each with:
keystringOptionalNullableThe site code; null for the row of screens linked to no site.
namestringOptionalNullablescreensintegerOptionalonlineintegerOptionalofflineintegerOptionalstoppedintegerOptionalplayingintegerOptionalOnline screens that are not stopped and last reported showing an item.
uptimeobjectOptionalThe site’s screens’ last 30 days added up (up seconds over counted seconds, never an average of the screens’ figures). 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
grafanaUrlstringOptionalNullableOpens the site’s dashboard in the organisation’s hosted Grafana, signed in by a hand-off from the viewer. Null unless hosted dashboards are set up, and for the row with no site.
Errors
| Status | Code | Meaning |
|---|---|---|
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 site
Any member’s session (viewer, editor or owner), or a key with the Screens permission. One site: its summary, as in the list, and its screens, each as in the screens list. A key limited to some screens sees and counts only those.
Path parameters
sitestringRequiredThe brand code.
Returns
The site.
Returns the Site object.
Errors
| Status | Code | Meaning |
|---|---|---|
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
404 | unknown_sitenot_connected |
|
409 | api_offintegration_off |
|
501 | The player is not available on this server. |
Create a site
Needs the Screens write permission and an editor. Makes a site for screens: the same record as a brand in Mestra, with a name and a code.
Body parameters
codestringRequirednamestringRequired
Returns
The site.
An object with:
codestringOptionalnamestringOptional
Errors
| Status | Code | Meaning |
|---|---|---|
400 | The name or the key isn’t acceptable. | |
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_keyplan_refused |
|
404 | not_connected |
|
409 | api_offintegration_off | The code is taken, or |
Retrieve a site's times, brightness and sound
Needs the Screens read permission and an owner. A site is a brand’s code that Mestra screens are linked to. Returns its time zone, on and off times, brightness steps, at-screen setting, sound, panel volume and location (null means not chosen) and the screens linked to it. A screen’s panel link is not shown. A key limited to some screens gets 403 screens_limited unless it holds every screen linked to the site.
Path parameters
sitestringRequiredA site code with at least one Mestra screen linked to it (URL-encoded).
Returns
The site’s settings and the screens linked to it.
An object with:
timezonestringOptionalNullablehoursarray of valuesOptionalNullableOn intervals in the screen’s zone. An empty list (or none) means no hours: Mestra won’t turn the panel on or off, and the page plays.
brightnessarray of valuesOptionalNullableBrightness steps; each holds until the next, wrapping the day. An empty list never sets brightness.
atScreenstringOptionalNullablePossible values
restoreleavenullsoundstringOptionalNullablenullis not chosen, which plays muted.Possible values
onoffnullpanelVolumeintegerOptionalNullablelocationobjectOptionalNullableWhere the site is;
nullis not set.Show child attributesHide child attributes
latnumberOptionallonnumberOptionalnamestringOptionaladdressstringOptionalcitystringOptionalstatestringOptionalpostcodestringOptional
devicesarray of objectsOptionalThe Mestra screens linked to the site.
Show child attributesHide child 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.
Errors
| Status | Code | Meaning |
|---|---|---|
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_keyscreens_limited |
|
404 | unknown_sitenot_connected |
|
409 | api_offintegration_off |
|
501 | The player is not available on this server. |
Update a site's times, brightness or sound
Needs the Screens write permission and an owner. An absent field is kept; an explicit null clears it; {} changes nothing. Fields: timezone, hours, brightness, atScreen (restore or leave), sound (the string on or off, or null), panelVolume and location (an object, or null to clear). The site’s screens are told at once. A key limited to some screens gets 403 screens_limited unless it holds every screen linked to the site.
Path parameters
sitestringRequiredA site code with at least one Mestra screen linked to it (URL-encoded).
Body parameters
timezonestringOptionalNullableAn IANA zone name, like
Australia/Sydney.hoursarray of valuesOptionalNullableOn intervals in the screen’s zone. An empty list (or none) means no hours: Mestra won’t turn the panel on or off, and the page plays.
brightnessarray of valuesOptionalNullableBrightness steps; each holds until the next, wrapping the day. An empty list never sets brightness.
atScreenstringOptionalNullablePossible values
restoreleavenullsoundstringOptionalNullableSound at the site’s screens. Unset plays muted.
Possible values
onoffnullpanelVolumeintegerOptionalNullableThe panel’s own volume;
nullleaves the panel as set.locationobjectOptionalNullableWhere the site is; its screens use it unless they have their own.
nullclears it.Show child attributesHide child attributes
latnumberOptionallonnumberOptionalnamestringOptionaladdressstringOptionalcitystringOptionalstatestringOptionalpostcodestringOptional
Returns
The site as it is now.
An object with:
timezonestringOptionalNullablehoursarray of valuesOptionalNullableOn intervals in the screen’s zone. An empty list (or none) means no hours: Mestra won’t turn the panel on or off, and the page plays.
brightnessarray of valuesOptionalNullableBrightness steps; each holds until the next, wrapping the day. An empty list never sets brightness.
atScreenstringOptionalNullablePossible values
restoreleavenullsoundstringOptionalNullablenullis not chosen, which plays muted.Possible values
onoffnullpanelVolumeintegerOptionalNullablelocationobjectOptionalNullableWhere the site is;
nullis not set.Show child attributesHide child attributes
latnumberOptionallonnumberOptionalnamestringOptionaladdressstringOptionalcitystringOptionalstatestringOptionalpostcodestringOptional
devicesarray of objectsOptionalThe Mestra screens linked to the site.
Show child attributesHide child 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.
Errors
| Status | Code | Meaning |
|---|---|---|
400 | A setting that is not valid, or not a site setting (with | |
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_keyscreens_limited |
|
404 | unknown_sitenot_connected |
|
409 | api_offintegration_off |
|
413 | “body exceeds limit (<n> bytes)”. | |
501 | The player is not available on this server. |
Update the power of a site's screens
Needs the Screens write permission and an owner. power is on, off or schedule, as for one screen, applied to every screen linked to the site now. until must be in the future. A site’s power may be changed a limited number of times an hour (429). A key limited to some screens gets 403 screens_limited unless it holds every screen linked to the site.
Path parameters
sitestringRequiredA site code with at least one Mestra screen linked to it (URL-encoded).
Body parameters
powerstringRequiredPossible values
onoffscheduleuntilstring (date-time)OptionalIn the future. Only with
onoroff; without it the hold lasts until changed.
Returns
The site as it is now.
An object with:
timezonestringOptionalNullablehoursarray of valuesOptionalNullableOn intervals in the screen’s zone. An empty list (or none) means no hours: Mestra won’t turn the panel on or off, and the page plays.
brightnessarray of valuesOptionalNullableBrightness steps; each holds until the next, wrapping the day. An empty list never sets brightness.
atScreenstringOptionalNullablePossible values
restoreleavenullsoundstringOptionalNullablenullis not chosen, which plays muted.Possible values
onoffnullpanelVolumeintegerOptionalNullablelocationobjectOptionalNullableWhere the site is;
nullis not set.Show child attributesHide child attributes
latnumberOptionallonnumberOptionalnamestringOptionaladdressstringOptionalcitystringOptionalstatestringOptionalpostcodestringOptional
devicesarray of objectsOptionalThe Mestra screens linked to the site.
Show child attributesHide child 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.
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_sitenot_connected |
|
409 | api_offintegration_off |
|
413 | “body exceeds limit (<n> bytes)”. | |
429 | rate_limited |
|
501 | The player is not available on this server. |
Update the site of screens
Needs the Screens write permission and an editor. Links screens to a site, or with an empty site takes them off their site.
Body parameters
framesarray of stringsRequiredsitestringRequired
Returns
How many screens were linked.
An object with:
linkedintegerOptional
Errors
| Status | Code | Meaning |
|---|---|---|
400 | No screens, or an id that isn’t a screen. | |
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_keyplan_refused |
|
404 | not_connected | There’s no such site, or |
409 | api_offintegration_off |
|