Skip to content

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)Optional
  • scopestringOptional

    Possible valuespublicationscreensiteall

  • targetstringOptionalNullable
  • reasonstringOptionalNullable
  • statusstringOptional

    done when no screen you can see is pending or told: each is off, removed or started_again. A screen started_again may be showing the content again.

    Possible valuespendingdone

  • createdAtstring (date-time)Optional
  • doneAtstring (date-time)OptionalNullable
  • screensarray of objectsOptional

    The screens your key can see.

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

      The screen’s name; empty once it was deleted.

    • statestringOptional

      pending: 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 valuespendingtoldoffremovedstarted_again

    • toldAtstring (date-time)OptionalNullable
    • offAtstring (date-time)OptionalNullable
    • reasonstringOptionalNullable

      Why a pending or told screen is not moving: offline while it has not called in for 3 minutes. Null otherwise.

      Possible valuesofflinenull

Stop a screen

PermissionScreens · Takedown

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

StatusCodeMeaning
401invalid_token

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

403wrong_keyscreens_limited

wrong_key: the key lacks the Screens permission this call needs; or screens_limited: the key is limited to some screens and this call acts on all of them. A session below an editor’s gets “Your role (<role>) can’t <action>.”

404unknown_screennot_connected

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

409api_offintegration_off

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

413

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

501

The player is not available on this server.

Retrieve what stopped screens show

PermissionScreens · Read

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:

  • stopShowstringOptional

    Possible valuesblacklogoimagevideo

  • transitionstringOptional

    How every screen moves from one ad to the next.

    Possible valuescutfade

  • imageIdstringOptional

    The picture’s sha256 while stopShow is image, else empty.

  • videoIdstringOptional

    The video’s sha256 while stopShow is video, else empty.

  • logoIdstringOptional

    The logo chosen, <site>/<variant>; empty when none or it has since changed.

  • logosarray of objectsOptional
    Show child attributesHide child attributes
    • idstringOptional
    • sitestringOptional
    • variantstringOptional
  • updatesPausedbooleanOptional

    True 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

StatusCodeMeaning
401invalid_token

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

403wrong_keyscreens_limited

wrong_key: the key lacks the Screens permission this call needs; or screens_limited: the key is limited to some screens and this call acts on all of them. A session below an owner’s gets “Your role (<role>) can’t <action>.”

404not_connected

not_connected.

409api_offintegration_off

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

501

The player is not available on this server.

Update what stopped screens show

PermissionScreens · Write

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

  • stopShowstringOptional

    Required unless transition is sent.

    Possible valuesblacklogoimagevideo

  • videoIdstringOptional

    The video’s sha256, for video.

  • imageIdstringOptional

    The picture’s sha256.

  • logoIdstringOptional
  • transitionstringOptional

    Possible valuescutfade

  • updatesPausedbooleanOptional

    true pauses updates for every screen, security updates included; false resumes 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 403 session_only.

Returns

Saved; the settings as they are now.

An object with:

  • stopShowstringOptional

    Possible valuesblacklogoimagevideo

  • transitionstringOptional

    How every screen moves from one ad to the next.

    Possible valuescutfade

  • imageIdstringOptional

    The picture’s sha256 while stopShow is image, else empty.

  • videoIdstringOptional

    The video’s sha256 while stopShow is video, else empty.

  • logoIdstringOptional

    The logo chosen, <site>/<variant>; empty when none or it has since changed.

  • logosarray of objectsOptional
    Show child attributesHide child attributes
    • idstringOptional
    • sitestringOptional
    • variantstringOptional
  • updatesPausedbooleanOptional

    True 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

StatusCodeMeaning
400

A bad stopShow or imageId (with field).

401invalid_token

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

403wrong_keyscreens_limitedsession_only

wrong_key: the key lacks the Screens permission this call needs; or screens_limited: the key is limited to some screens and this call acts on all of them; or session_only: a plugin’s app token sent updatesPaused. A session below an owner’s gets “Your role (<role>) can’t <action>.”

404not_connected

not_connected.

409api_offintegration_off

api_off (an owner hasn’t turned the API on), or integration_off (Mestra screens are 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

PermissionScreens · 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)Required

    A UUID you make for this takedown. The same key with the same request returns the takedown it made.

  • scopestringRequired

    Possible valuespublicationscreensiteall

  • targetstringOptionalNullable

    The screen’s id (screen), the brand code (site) or the publication’s id (publication). Leave it out for all.

  • reasonstringOptionalNullable

Returns

The key was already used for this request. The takedown it made.

Returns the Takedown object.

Errors

StatusCodeMeaning
400

idempotencyKey, scope, target or reason (with field).

401invalid_token

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

403wrong_keyscreens_limited

wrong_key: the key lacks the Screens permission this call needs; or screens_limited: the key is limited to some screens and this call acts on all of them. A session below an editor’s gets “Your role (<role>) can’t <action>.”

404unknown_screenunknown_siteunknown_publicationnot_connected

unknown_screen (no such screen, or one this key can’t see), unknown_site (no screen this key can see is linked to that site), unknown_publication (no such Mestra publication), or not_connected.

409idempotency_conflictpublication_busyapi_offintegration_off

idempotency_conflict (the key was used for a different takedown), publication_busy (the publication is still being sent to screens, so the ad could still go live: try again in a moment), api_off (an owner hasn’t turned the API on), or integration_off (Mestra screens are off).

413

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

501

The player is not available on this server.

List all takedowns

PermissionScreens · Read

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

  • cursorstringOptional

    The next of the previous response. Leave it out to start from the newest takedown.

  • limitintegerOptional

    Takedowns in the page.

    Default25

Returns

A page of takedowns.

Returns a list of Takedown objects.

Errors

StatusCodeMeaning
400

limit or cursor (with field).

401invalid_token

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

403wrong_key

wrong_key: the key lacks the Screens permission this call needs. A session below an editor’s gets “Your role (<role>) can’t <action>.”

404not_connected

not_connected.

409api_offintegration_off

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

501

The player is not available on this server.

Retrieve a takedown

PermissionScreens · Read

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

StatusCodeMeaning
401invalid_token

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

403wrong_key

wrong_key: the key lacks the Screens permission this call needs. A session below an editor’s gets “Your role (<role>) can’t <action>.”

404unknown_takedownnot_connected

unknown_takedown (no such takedown, or none of its screens is one this key can see), or not_connected.

409api_offintegration_off

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

501

The player is not available on this server.