API reference
Stop and takedowns
Stopping a screen makes it show a stopped message instead of its content. A takedown stops screens, a site, every screen or one publication in one go, and records it so you can see when each screen has stopped. The settings here say what a stopped screen shows.
The Takedown object
A takedown: a request to stop screens, with what it covers, why, whether it is done, and the state of each screen it names.
Attributes
idstring (uuid)OptionalscopestringOptionalPossible values
publicationscreensitealltargetstringOptionalNullablereasonstringOptionalNullablestatusstringOptionaldonewhen no screen you can see ispendingortold: each isoff,removedorstarted_again. A screenstarted_againmay be showing the content again.Possible values
pendingdonecreatedAtstring (date-time)OptionaldoneAtstring (date-time)OptionalNullablescreensarray of objectsOptionalThe screens your key can see.
Show child attributesHide child attributes
idstring (uuid)OptionalnamestringOptionalThe screen’s name; empty once it was deleted.
statestringOptionalpending: not yet told.told: its manifest no longer plays it.off: its heartbeat shows it off (the screen’s own report).removed: the screen was deleted first.started_again: the screen was started again first.Possible values
pendingtoldoffremovedstarted_againtoldAtstring (date-time)OptionalNullableoffAtstring (date-time)OptionalNullablereasonstringOptionalNullableWhy a
pendingortoldscreen is not moving:offlinewhile it has not called in for 3 minutes. Null otherwise.Possible values
offlinenull
Stop a screen
Needs an editor’s or an owner’s key or session. Stops one screen so it shows its stopped picture, and reaches the screen at once. A key with the Screens Takedown permission may call this; it can’t start, rename or delete a screen. The body is {} or empty. Stopping a screen that is already stopped is not an error: the answer is the same and nothing more is recorded. This call records the stop only; to be told when a screen has stopped showing an ad, use takedowns.
Path parameters
idstring (uuid)Required
Body parameters (optional)
bodyobjectRequired
Returns
The screen, with stopped true.
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 |
|
413 | “body exceeds limit (<n> bytes)”. | |
501 | The player is not available on this server. |
Retrieve what stopped screens show
Needs an owner’s key or session. logos lists the organisation’s PNG and JPEG logos a screen can show, as <site>/<variant>.
Returns
The choice for all screens.
An object with:
stopShowstringOptionalPossible values
blacklogoimagevideotransitionstringOptionalHow every screen moves from one ad to the next.
Possible values
cutfadeimageIdstringOptionalThe picture’s sha256 while
stopShowisimage, else empty.videoIdstringOptionalThe video’s sha256 while
stopShowisvideo, else empty.logoIdstringOptionalThe logo chosen,
<site>/<variant>; empty when none or it has since changed.logosarray of objectsOptionalShow child attributesHide child attributes
idstringOptionalsitestringOptionalvariantstringOptional
updatesPausedbooleanOptionalTrue while updates are paused for every screen, security updates included. In an editor’s or an owner’s signed-in session, or an owner’s key or grant with Screens · Write; left out for any other key, a viewer and an app token. Only an owner can change it.
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 |
|
501 | The player is not available on this server. |
Update what stopped screens show
Needs an owner’s key or session. black; logo with a logoId from the settings’ logos (the logo’s file is copied for the screens); image with the imageId an upload gave; or video with the videoId an upload gave. Screens with a choice of their own keep it. Held screens are told at once. A key limited to some screens can’t change this (403 screens_limited). transition (cut or fade) is how every screen moves from one ad to the next; sent alone, it leaves stopShow as it is.
In a signed-in owner’s session, {"updatesPaused": true} (or false) alone pauses or resumes updates for every screen, security updates included, and the settings carry updatesPaused. An owner’s key or grant with Screens · Write may do it too and sees updatesPaused; a plugin’s app token may not (403 session_only). Each change is in Activity.
Body parameters
stopShowstringOptionalRequired unless
transitionis sent.Possible values
blacklogoimagevideovideoIdstringOptionalThe video’s sha256, for
video.imageIdstringOptionalThe picture’s sha256.
logoIdstringOptionaltransitionstringOptionalPossible values
cutfadeupdatesPausedbooleanOptionaltruepauses updates for every screen, security updates included;falseresumes them. Sent alone it changes nothing else. An owner’s session, or an owner’s key or grant with Screens · Write; a plugin’s app token gets 403session_only.
Returns
Saved; the settings as they are now.
An object with:
stopShowstringOptionalPossible values
blacklogoimagevideotransitionstringOptionalHow every screen moves from one ad to the next.
Possible values
cutfadeimageIdstringOptionalThe picture’s sha256 while
stopShowisimage, else empty.videoIdstringOptionalThe video’s sha256 while
stopShowisvideo, else empty.logoIdstringOptionalThe logo chosen,
<site>/<variant>; empty when none or it has since changed.logosarray of objectsOptionalShow child attributesHide child attributes
idstringOptionalsitestringOptionalvariantstringOptional
updatesPausedbooleanOptionalTrue while updates are paused for every screen, security updates included. In an editor’s or an owner’s signed-in session, or an owner’s key or grant with Screens · Write; left out for any other key, a viewer and an app token. Only an owner can change it.
Errors
| Status | Code | Meaning |
|---|---|---|
400 | A bad | |
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_keyscreens_limitedsession_only |
|
404 | not_connected |
|
409 | api_offintegration_off |
|
413 | “body exceeds limit (<n> bytes)”. | |
422 | The logo can’t be shown (not a PNG or JPEG, or not there), or the image is unknown. | |
501 | The player is not available on this server. |
Create a takedown
Needs an editor’s or an owner’s key or session. Takes screens off and records it so you can be told when they are. scope is screen (target is a screen’s id), site (target is a site code: every screen linked to it), all (no target: every screen the key can see) or publication (target is a Mestra publication’s id: it is put into take-down mode, its Mestra entries end at once so the screens drop it on their next poll, and the screens it played on are the targets; a publication still waiting to be sent is cancelled, and one still being sent is 409 publication_busy, so try again in a moment). A screen, site or all takedown stops each target screen, which a key with only the Screens Takedown permission may do; starting them again needs the Screens Write permission. A key limited to some screens can take down only those screens, and can’t take down a publication, which ends on every screen it plays on (403 screens_limited).
idempotencyKey (a UUID you make) is required. Sending the same key with the same request returns the takedown it made (200, no second stop, no second record); the same key with a different request is 409 idempotency_conflict, and so is a key whose takedown has no screen your key can see.
Each target screen is pending until its next manifest no longer plays the thing (a stopped screen, or a screen without the publication’s entries), told from then, and off once its heartbeat shows it off (stopped, or for a publication takedown anything but one of its entries). off is the screen’s own report: Mestra has no other way to see what a screen shows. A screen that was already stopped starts off only if its last heartbeat said it shows stopped; one stopped while it was away starts pending like any other. A screen that is deleted before it is off becomes removed. A screen that is started again before it is off becomes started_again (a publication takedown is not affected: it does not need the screen stopped), so the takedown can finish. An offline screen stays pending, with reason: offline on it: nothing times out. The takedown is done when no screen is pending or told.
Body parameters
idempotencyKeystring (uuid)RequiredA UUID you make for this takedown. The same key with the same request returns the takedown it made.
scopestringRequiredPossible values
publicationscreensitealltargetstringOptionalNullableThe screen’s id (
screen), the brand code (site) or the publication’s id (publication). Leave it out forall.reasonstringOptionalNullable
Returns
The key was already used for this request. The takedown it made.
Returns the Takedown object.
Errors
| Status | Code | Meaning |
|---|---|---|
400 |
| |
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_keyscreens_limited |
|
404 | unknown_screenunknown_siteunknown_publicationnot_connected |
|
409 | idempotency_conflictpublication_busyapi_offintegration_off |
|
413 | “body exceeds limit (<n> bytes)”. | |
501 | The player is not available on this server. |
List all takedowns
Needs an editor’s or an owner’s key or session. The takedowns that name at least one screen the key can see, newest first. Each lists only the screens the key can see, and its status and doneAt are worked out from those. next is the cursor for the page after, or null on the last page.
Query parameters
cursorstringOptionalThe
nextof the previous response. Leave it out to start from the newest takedown.limitintegerOptionalTakedowns in the page.
Default
25
Returns
A page of takedowns.
Returns a list of Takedown objects.
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 takedown
Needs an editor’s or an owner’s key or session. One takedown and where each of its screens has got to. A key limited to some screens sees only those, and a takedown with none of them is 404 unknown_takedown.
Path parameters
idstring (uuid)Required
Returns
The takedown.
Returns the Takedown object.
Errors
| Status | Code | Meaning |
|---|---|---|
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
404 | unknown_takedownnot_connected |
|
409 | api_offintegration_off |
|
501 | The player is not available on this server. |