Skip to content

API reference

Scheduling

The Booking object

A booking: one file from the content library on some screens for a date range and schedule, with its status, counts and whether it can be sent live, retried or ended.

Attributes

  • idstring (uuid)Required
  • namestringRequired
  • sourcestringRequired

    Possible valuesuploadreviewrunmotiondynamicnetwork

  • statusstringRequired
  • campaignobjectRequiredNullable
    Show child attributesHide child attributes
    • idstringOptional
    • namestringOptional
  • contentarray of objectsRequired
    Show child attributesHide child attributes
    • idstringOptional
    • namestringOptional
    • kindstringOptional
    • sha256stringOptional
    • thumbstringOptional
    • durationMsintegerOptional
    • checksstringOptional
  • screensarray of objectsRequired
    Show child attributesHide child attributes
    • idstringOptional
    • namestringOptional
    • siteobjectOptionalNullable
      Show child attributesHide child attributes
      • keystringOptional
      • namestringOptional
    • kindstringOptional

      Possible valuessinglegroup

    • statestringOptional

      Possible valuespendingdraftlivereplacedfailedended

    • cantPlaybooleanOptional
  • startDatestringRequired
  • endDatestringRequired
  • scheduleobjectRequiredNullable
  • slotsintegerRequired
  • countsobjectRequired
    Show child attributesHide child attributes
    • pendingintegerOptional
    • draftintegerOptional
    • liveintegerOptional
    • replacedintegerOptional
    • failedintegerOptional
    • endedintegerOptional
  • livebooleanRequired
  • canGoLivebooleanRequired
  • canEndbooleanRequired
  • canRetrybooleanRequired
  • createdAtstring (date-time)Required
  • createdBystringRequired
  • playsobjectRequiredNullable

    With plays=1, once a play is stored.

  • linksobjectRequired

    Main-app paths of a publish made there: published, and review when it came from a review. Empty for content booked here.

    Show child attributesHide child attributes
    • publishedstringOptional
    • reviewstringOptional
  • customerobjectRequiredNullable

    Who the booking is for.

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

    Possible valuespaidhouse

  • policyobjectRequired

    Loop rules; a rule that is null or left out is not set.

    Show child attributesHide child attributes
    • sharePctintegerOptionalNullable
    • playsPerHourintegerOptionalNullable
    • playsPerDayintegerOptionalNullable
  • outsideCampaignstringRequiredNullable

    In words, why its campaign’s dates or hours keep it from playing, for example Outside its campaign's hours: won't play until 14 Dec. null when it is inside them, or in no campaign.

  • zonesarray of stringsRequired

    The time zones its screens keep, sorted (for example Australia/Sydney); its days and hours run on those clocks. Empty before it is made.

Add content

PermissionScreens · Write

Needs the Screens write permission and an editor. Adds a picture (PNG or JPEG), an MP4 video or an HTML5 package (a .zip) to the organisation’s content library, to book on screens. The body is the file’s bytes, sent with its Content-Type and its name in X-Mestra-File-Name (percent-encoded). An HTML5 package may send its length in milliseconds in X-Mestra-Duration-Ms. Names are unique in the library, in any case: a name already used is 409 name_taken. Mestra screens must be on and connected, and the plan must include scheduling (403 plan_refused).

Headers

  • X-Mestra-File-NamestringRequired

    The file’s name, percent-encoded. Unique in the library.

  • X-Mestra-Duration-MsintegerOptional

    An HTML5 package’s length in milliseconds.

Body parameters

The request body is image/png.

Returns

The file was added.

An object with:

  • idstring (uuid)Required
  • namestringRequired
  • kindstringRequired

    Possible valuesimagevideohtml5

  • mimestringRequired
  • sha256stringRequired
  • sizeinteger (int64)Required
  • widthintegerRequired

    0 when unknown.

  • heightintegerRequired

    0 when unknown.

  • durationMsintegerRequired

    A video’s or package’s length; 0 for a picture.

  • checksstringRequired

    Possible valuesnone

  • uploadedBystringRequired

    The user who added it; empty when none.

  • createdAtstring (date-time)Required
  • thumbstringRequired

    The address of a picture’s small preview, or empty.

  • bookedOnintegerRequired

    Live or draft bookings that use it.

Errors

StatusCodeMeaning
400

The name is missing or not usable, or the package’s length is not valid.

401invalid_token

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

403wrong_keyplan_refused

wrong_key (the key or role can’t add content), or plan_refused.

409name_takenintegration_offapi_off

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

413

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

415

The file is not a PNG, JPEG, MP4 or HTML5 package.

501

The player is not available on this server.

List all content

PermissionScreens · Read

Needs the Screens read permission; any member’s session (a viewer too) will do. The organisation’s content library, newest first. kind narrows it to image, video or html5. next is the after value for the following page, or empty on the last.

Query parameters

  • kindstringOptional

    Possible valuesimagevideohtml5

  • afterstring (uuid)Optional

    The next of the page before.

  • limitintegerOptional

    Default50

Returns

The files.

A list of objects, each with:

  • idstring (uuid)Required
  • namestringRequired
  • kindstringRequired

    Possible valuesimagevideohtml5

  • mimestringRequired
  • sha256stringRequired
  • sizeinteger (int64)Required
  • widthintegerRequired

    0 when unknown.

  • heightintegerRequired

    0 when unknown.

  • durationMsintegerRequired

    A video’s or package’s length; 0 for a picture.

  • checksstringRequired

    Possible valuesnone

  • uploadedBystringRequired

    The user who added it; empty when none.

  • createdAtstring (date-time)Required
  • thumbstringRequired

    The address of a picture’s small preview, or empty.

  • bookedOnintegerRequired

    Live or draft bookings that use it.

Errors

StatusCodeMeaning
400

kind, after or limit is not valid.

401invalid_token

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

403wrong_key

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

404not_connected

not_connected.

409api_offintegration_off

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

501

The player is not available on this server.

Retrieve content

PermissionScreens · Read

Needs the Screens read permission; any member’s session (a viewer too) will do. One file of the content library.

Path parameters

  • idstring (uuid)Required

Returns

The file.

An object with:

  • idstring (uuid)Required
  • namestringRequired
  • kindstringRequired

    Possible valuesimagevideohtml5

  • mimestringRequired
  • sha256stringRequired
  • sizeinteger (int64)Required
  • widthintegerRequired

    0 when unknown.

  • heightintegerRequired

    0 when unknown.

  • durationMsintegerRequired

    A video’s or package’s length; 0 for a picture.

  • checksstringRequired

    Possible valuesnone

  • uploadedBystringRequired

    The user who added it; empty when none.

  • createdAtstring (date-time)Required
  • thumbstringRequired

    The address of a picture’s small preview, or empty.

  • bookedOnintegerRequired

    Live or draft bookings that use it.

  • bookingsarray of objectsRequired

    The draft and live bookings that use the file, newest first. bookedOn is their number.

    Show child attributesHide child attributes
    • idstring (uuid)Required
    • namestringRequired
    • statestringRequired

      Possible valuesdraftlive

Errors

StatusCodeMeaning
401invalid_token

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

403wrong_key

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

404not_connected

No such file in this organisation, or not_connected.

409api_offintegration_off

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

501

The player is not available on this server.

Delete content

PermissionScreens · Write

Needs the Screens write permission and an editor. Removes the file from the library. A booking that already plays it keeps playing it until the booking ends; bookedOn says how many bookings that is.

Path parameters

  • idstring (uuid)Required

Returns

The file was deleted.

An object with:

  • deletedbooleanRequired
  • bookedOnintegerRequired

Errors

StatusCodeMeaning
401invalid_token

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

403wrong_keyplan_refused

wrong_key (the key or role can’t delete content), or plan_refused.

404not_connected

No such file in this organisation, or not_connected.

409api_offintegration_off

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

501

The player is not available on this server.

Create a booking

PermissionScreens · Write

Needs the Screens write permission and an editor. Books files from the content library on screens, sites and groups for a date range and schedule. One booking is made for each file.

Body parameters

  • idempotencyKeystring (uuid)Required
  • namestringOptional

    Empty takes the file’s name.

  • campaignstringOptional

    A campaign id to put the booking in, or empty for none. An unknown or archived campaign is 409 campaign_gone.

  • contentarray of objectsRequired
    Show child attributesHide child attributes
    • idstring (uuid)Required
    • playLengthSecondsintegerOptional
  • screensarray of stringsOptional
  • sitesarray of stringsOptional

    Site codes.

  • groupsarray of stringsOptional
  • startDatestring (date)Required
  • endDatestring (date)Required
  • scheduleobjectOptionalNullable
  • slotsintegerOptional
  • goLivebooleanOptional
  • customerstring (uuid)Optional

    The customer it is for, from listMestraCustomers. Empty for none: a booking in a campaign that has a customer is for it. An unknown customer is 404 unknown_customer, an archived one 409 customer_archived.

  • prioritystringOptional

    paid (the default), or house for content that fills what paid bookings leave in a loop. A house booking needs no customer.

    Possible valuespaidhouse

  • scalearray of objectsOptional

    Where Scale to fit is ticked. A place that is the same shape as the file but another size (the check lists it with scalable: true) is booked only for a tick; the booking records who ticked it and when. A tick on a place the file already fits, or on one of another shape, is refused (cant_play). Needs a signed-in person.

    Show child attributesHide child attributes
    • contentstring (uuid)Required

      The library file’s id, as in content.

    • framestring (uuid)Required

      The place: a frame’s id, or the screen’s id for its whole window.

  • policyobjectOptional

    Loop rules; a rule that is null or left out is not set.

    Show child attributesHide child attributes
    • sharePctintegerOptionalNullable
    • playsPerHourintegerOptionalNullable
    • playsPerDayintegerOptionalNullable

Returns

A repeat of an earlier request: the same bookings.

An object with:

  • bookingsarray of objectsRequired
    Show child attributesHide child attributes
    • idstring (uuid)Required
    • namestringRequired
    • sourcestringRequired

      Possible valuesuploadreviewrunmotiondynamicnetwork

    • statusstringRequired
    • campaignobjectRequiredNullable
      Show child attributesHide child attributes
      • idstringOptional
      • namestringOptional
    • contentarray of objectsRequired
      Show child attributesHide child attributes
      • idstringOptional
      • namestringOptional
      • kindstringOptional
      • sha256stringOptional
      • thumbstringOptional
      • durationMsintegerOptional
      • checksstringOptional
    • screensarray of objectsRequired
      Show child attributesHide child attributes
      • idstringOptional
      • namestringOptional
      • siteobjectOptionalNullable
        Show child attributesHide child attributes
        • keystringOptional
        • namestringOptional
      • kindstringOptional

        Possible valuessinglegroup

      • statestringOptional

        Possible valuespendingdraftlivereplacedfailedended

      • cantPlaybooleanOptional
    • startDatestringRequired
    • endDatestringRequired
    • scheduleobjectRequiredNullable
    • slotsintegerRequired
    • countsobjectRequired
      Show child attributesHide child attributes
      • pendingintegerOptional
      • draftintegerOptional
      • liveintegerOptional
      • replacedintegerOptional
      • failedintegerOptional
      • endedintegerOptional
    • livebooleanRequired
    • canGoLivebooleanRequired
    • canEndbooleanRequired
    • canRetrybooleanRequired
    • createdAtstring (date-time)Required
    • createdBystringRequired
    • playsobjectRequiredNullable

      With plays=1, once a play is stored.

    • linksobjectRequired

      Main-app paths of a publish made there: published, and review when it came from a review. Empty for content booked here.

      Show child attributesHide child attributes
      • publishedstringOptional
      • reviewstringOptional
    • customerobjectRequiredNullable

      Who the booking is for.

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

      Possible valuespaidhouse

    • policyobjectRequired

      Loop rules; a rule that is null or left out is not set.

      Show child attributesHide child attributes
      • sharePctintegerOptionalNullable
      • playsPerHourintegerOptionalNullable
      • playsPerDayintegerOptionalNullable
    • outsideCampaignstringRequiredNullable

      In words, why its campaign’s dates or hours keep it from playing, for example Outside its campaign's hours: won't play until 14 Dec. null when it is inside them, or in no campaign.

    • zonesarray of stringsRequired

      The time zones its screens keep, sorted (for example Australia/Sydney); its days and hours run on those clocks. Empty before it is made.

Errors

StatusCodeMeaning
400

A field is missing or not usable (idempotencyKey, content, screens, campaign, name, groups).

401invalid_token

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

403wrong_keyplan_refusedsales_paused

wrong_key (the key or role can’t do this), plan_refused, or sales_paused (new bookings are paused until an overdue invoice is paid).

404unknown_customernot_connected

No such booking, screen or site in this key’s reach, unknown_customer (the customer named is not one of the organisation’s), or not_connected.

409customer_archivedapi_offintegration_offplay_lengthpublish_changedcant_play

customer_archived (the customer named is archived), api_off, integration_off, or the publish engine’s own refusal (play_length, publish_changed, cant_play (a file the screen can’t play, is another size to, or can’t decode: a video that would need more pictures a second than the screen has measured, with its decoding in words), a date or capacity refusal).

List all bookings

PermissionScreens · Read

Needs the Screens read permission; any member’s session (a viewer too) will do. Every publication to Mestra screens, newest first: bookings made here and publishes from the main app.

Query parameters

  • beforestringOptional

    The next of the previous page.

  • playsstringOptional

    1 for each booking’s plays.

    Possible values1

  • statusstringOptional

    Only bookings with this status; live is any booking with a live item.

    Possible valuesqueuedrunningdonepartialfailedlive

  • campaignstring (uuid)Optional

    Only bookings in this campaign.

  • customerstring (uuid)Optional

    Only bookings for this customer.

  • screenstringOptional

    Only bookings with an item on this screen. A screen outside the key’s reach is 404 unknown_screen.

  • sitestringOptional

    Only bookings with an item on a screen of this site (a site code). An unknown site is 404 unknown_site.

Returns

The bookings.

Returns a list of Booking objects.

Errors

StatusCodeMeaning
401invalid_token

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

403wrong_keyplan_refused

wrong_key (the key or role can’t do this), or plan_refused.

404not_connected

No such booking, screen or site in this key’s reach, or not_connected.

409api_offintegration_offplay_lengthpublish_changedcant_play

api_off, integration_off, or the publish engine’s own refusal (play_length, publish_changed, cant_play (a file the screen can’t play, or is another size to), a date or capacity refusal).

Retrieve a booking

PermissionScreens · Read

Needs the Screens read permission; any member’s session (a viewer too) will do. One booking.

Path parameters

  • idstring (uuid)Required

Returns

The booking.

Returns the Booking object.

Errors

StatusCodeMeaning
401invalid_token

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

403wrong_keyplan_refused

wrong_key (the key or role can’t do this), or plan_refused.

404not_connected

No such booking, screen or site in this key’s reach, or not_connected.

409api_offintegration_offplay_lengthpublish_changedcant_play

api_off, integration_off, or the publish engine’s own refusal (play_length, publish_changed, cant_play (a file the screen can’t play, or is another size to), a date or capacity refusal).

Update a booking

PermissionScreens · Write

Needs the Screens write permission and an editor. Renames a booking made from content, or moves it into a campaign or out of one. customer (a customer id, or null to take the customer off), priority (paid, the default, or house for content that fills what paid bookings leave in a loop; a house booking needs no customer) and policy (the booking’s own caps: sharePct, playsPerHour and playsPerDay) change who it is for and how it takes its place in the loop. In policy, a rule left out stays as it is and null clears it. An unknown customer is 404 unknown_customer; an archived one is 409 customer_archived, though a booking keeps the archived customer it already has.

Path parameters

  • idstring (uuid)Required

Body parameters

  • namestringOptional
  • campaignstringOptional
  • customerstring (uuid)OptionalNullable

    The customer it is for, by id; null takes the customer off. An unknown customer is 404 unknown_customer, an archived one 409 customer_archived.

  • prioritystringOptional

    paid (the default), or house for content that fills what paid bookings leave in a loop. A house booking needs no customer.

    Possible valuespaidhouse

  • policyobjectOptional

    The booking’s own caps (sharePct, playsPerHour, playsPerDay). A rule left out stays as it is; null clears it.

    Show child attributesHide child attributes
    • sharePctintegerOptionalNullable
    • playsPerHourintegerOptionalNullable
    • playsPerDayintegerOptionalNullable

Returns

The booking.

Returns the Booking object.

Errors

StatusCodeMeaning
401invalid_token

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

403wrong_keyplan_refused

wrong_key (the key or role can’t do this), or plan_refused.

404unknown_customernot_connected

No such booking, screen or site in this key’s reach, unknown_customer (the customer named is not one of the organisation’s), or not_connected.

409customer_archivedapi_offintegration_offplay_lengthpublish_changedcant_play

customer_archived (the customer named is archived), api_off, integration_off, or the publish engine’s own refusal (play_length, publish_changed, cant_play (a file the screen can’t play, or is another size to), a date or capacity refusal).

Start a booking on its screens

PermissionScreens · Write

Needs the Screens write permission and an editor. Sends the booking’s drafts to the screens.

Path parameters

  • idstring (uuid)Required

Returns

Accepted: the runner will do it.

An object with:

  • idstringOptional
  • sendingintegerOptional
  • itemsintegerOptional

Errors

StatusCodeMeaning
401invalid_token

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

403wrong_keyplan_refusedsales_paused

wrong_key (the key or role can’t do this), plan_refused, or sales_paused (new bookings are paused until an overdue invoice is paid).

404not_connected

No such booking, screen or site in this key’s reach, or not_connected.

409api_offintegration_offplay_lengthpublish_changedcant_play

api_off, integration_off, or the publish engine’s own refusal (play_length, publish_changed, cant_play (a file the screen can’t play, or is another size to), a date or capacity refusal).

Start a booking again

PermissionScreens · Write

Needs the Screens write permission and an editor. Tries a booking’s failed screens again.

Path parameters

  • idstring (uuid)Required

Returns

Accepted: the runner will do it.

An object with:

  • idstringOptional
  • sendingintegerOptional
  • itemsintegerOptional

Errors

StatusCodeMeaning
401invalid_token

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

403wrong_keyplan_refused

wrong_key (the key or role can’t do this), or plan_refused.

404not_connected

No such booking, screen or site in this key’s reach, or not_connected.

409api_offintegration_offplay_lengthpublish_changedcant_play

api_off, integration_off, or the publish engine’s own refusal (play_length, publish_changed, cant_play (a file the screen can’t play, or is another size to), a date or capacity refusal).

Stop a booking

PermissionScreens · Write

Needs the Screens write permission and an editor. Takes a booking off every screen it plays on, and answers the takedown that confirms each screen.

Path parameters

  • idstring (uuid)Required

Returns

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

Returns the Takedown object.

Errors

StatusCodeMeaning
400

idempotencyKey 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 or role can’t do this), or a key limited to some screens (screens_limited).

404not_connected

No such booking, screen or site in this key’s reach, or not_connected.

409idempotency_conflictpublication_busyapi_offintegration_off

idempotency_conflict, publication_busy, api_off or integration_off.

List all screen campaigns

PermissionScreens · Read

Needs the Screens read permission; any member’s session (a viewer too) will do. The campaigns that group bookings, with how many bookings each holds.

Query parameters

  • customerstring (uuid)Optional

    Only the campaigns that are for this customer.

Returns

The campaigns.

An object with:

  • campaignsarray of objectsRequired
    Show child attributesHide child attributes
    • idstring (uuid)Required
    • namestringRequired
    • startDatestringRequired

      A note, YYYY-MM-DD, or empty. It gates nothing.

    • endDatestringRequired

      A note, YYYY-MM-DD, or empty.

    • archivedbooleanRequired
    • bookingsintegerRequired

      Bookings in the campaign.

    • liveintegerRequired

      Those with a file on a screen now.

    • customerobjectRequiredNullable

      Who the campaign is for. Its bookings with no customer of their own are for it.

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

      Loop rules; a rule that is null or left out is not set.

      Show child attributesHide child attributes
      • sharePctintegerOptionalNullable
      • playsPerHourintegerOptionalNullable
      • playsPerDayintegerOptionalNullable
    • windowobjectRequiredNullable

      The daily window its bookings play in (null for none).

      Show child attributesHide child attributes
      • startstringOptional
      • endstringOptional
      • daysarray of stringsOptional

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 or role can’t do this).

404not_connected

not_connected.

409api_offintegration_off

api_off or integration_off.

Create a screen campaign

PermissionScreens · Write

Needs the Screens write permission and an editor. A named group of bookings. Its dates are a note and gate nothing.

Body parameters

  • namestringRequired
  • startDatestringOptional
  • endDatestringOptional
  • customerstring (uuid)Optional
  • policyobjectOptional

    Loop rules; a rule that is null or left out is not set.

    Show child attributesHide child attributes
    • sharePctintegerOptionalNullable
    • playsPerHourintegerOptionalNullable
    • playsPerDayintegerOptionalNullable
  • windowobjectOptional

    The daily window its bookings play in; its dates and window keep them from playing outside them. start and end are HH:MM (empty clears them); days are mon to sun (empty is every day).

    Show child attributesHide child attributes
    • startstringOptional
    • endstringOptional
    • daysarray of stringsOptional

Returns

The campaign.

An object with:

  • idstring (uuid)Required
  • namestringRequired
  • startDatestringRequired

    A note, YYYY-MM-DD, or empty. It gates nothing.

  • endDatestringRequired

    A note, YYYY-MM-DD, or empty.

  • archivedbooleanRequired
  • bookingsintegerRequired

    Bookings in the campaign.

  • liveintegerRequired

    Those with a file on a screen now.

  • customerobjectRequiredNullable

    Who the campaign is for. Its bookings with no customer of their own are for it.

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

    Loop rules; a rule that is null or left out is not set.

    Show child attributesHide child attributes
    • sharePctintegerOptionalNullable
    • playsPerHourintegerOptionalNullable
    • playsPerDayintegerOptionalNullable
  • windowobjectRequiredNullable

    The daily window its bookings play in (null for none).

    Show child attributesHide child attributes
    • startstringOptional
    • endstringOptional
    • daysarray of stringsOptional

Errors

StatusCodeMeaning
401invalid_token

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

403wrong_keyplan_refused

wrong_key (the key or role can’t do this), a key limited to some screens, or plan_refused.

404not_connected

not_connected.

409name_takenapi_offintegration_off

name_taken, api_off or integration_off.

Retrieve a screen campaign

PermissionScreens · Read

Needs the Screens read permission; any member’s session (a viewer too) will do. One campaign, archived or not.

Path parameters

  • idstring (uuid)Required

Returns

The campaign.

An object with:

  • idstring (uuid)Required
  • namestringRequired
  • startDatestringRequired

    A note, YYYY-MM-DD, or empty. It gates nothing.

  • endDatestringRequired

    A note, YYYY-MM-DD, or empty.

  • archivedbooleanRequired
  • bookingsintegerRequired

    Bookings in the campaign.

  • liveintegerRequired

    Those with a file on a screen now.

  • customerobjectRequiredNullable

    Who the campaign is for. Its bookings with no customer of their own are for it.

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

    Loop rules; a rule that is null or left out is not set.

    Show child attributesHide child attributes
    • sharePctintegerOptionalNullable
    • playsPerHourintegerOptionalNullable
    • playsPerDayintegerOptionalNullable
  • windowobjectRequiredNullable

    The daily window its bookings play in (null for none).

    Show child attributesHide child attributes
    • startstringOptional
    • endstringOptional
    • daysarray of stringsOptional

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 or role can’t do this).

404

No such campaign.

409api_offintegration_off

api_off or integration_off.

Update a screen campaign

PermissionScreens · Write

Needs the Screens write permission and an editor. Renames a campaign or changes its dates.

Path parameters

  • idstring (uuid)Required

Body parameters

  • namestringOptional
  • startDatestringOptional
  • endDatestringOptional
  • customerstring (uuid)OptionalNullable
  • policyobjectOptional

    Loop rules; a rule set to null is cleared and one left out is kept.

    Show child attributesHide child attributes
    • sharePctintegerOptionalNullable
    • playsPerHourintegerOptionalNullable
    • playsPerDayintegerOptionalNullable
  • windowobjectOptional

    Send only what changes: start and end are HH:MM (empty clears them); days are mon to sun (empty is every day).

    Show child attributesHide child attributes
    • startstringOptional
    • endstringOptional
    • daysarray of stringsOptional

Returns

The campaign.

An object with:

  • idstring (uuid)Required
  • namestringRequired
  • startDatestringRequired

    A note, YYYY-MM-DD, or empty. It gates nothing.

  • endDatestringRequired

    A note, YYYY-MM-DD, or empty.

  • archivedbooleanRequired
  • bookingsintegerRequired

    Bookings in the campaign.

  • liveintegerRequired

    Those with a file on a screen now.

  • customerobjectRequiredNullable

    Who the campaign is for. Its bookings with no customer of their own are for it.

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

    Loop rules; a rule that is null or left out is not set.

    Show child attributesHide child attributes
    • sharePctintegerOptionalNullable
    • playsPerHourintegerOptionalNullable
    • playsPerDayintegerOptionalNullable
  • windowobjectRequiredNullable

    The daily window its bookings play in (null for none).

    Show child attributesHide child attributes
    • startstringOptional
    • endstringOptional
    • daysarray of stringsOptional

Errors

StatusCodeMeaning
401invalid_token

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

403wrong_keyplan_refused

wrong_key (the key or role can’t do this), a key limited to some screens, or plan_refused.

404

No such campaign.

409name_takenapi_offintegration_off

name_taken, api_off or integration_off.

Update a screen campaign to archived

PermissionScreens · Write

Needs the Screens write permission and an editor. Takes a campaign off the pick-list; its bookings stay in it.

Path parameters

  • idstring (uuid)Required

Returns

The campaign, archived.

An object with:

  • idstring (uuid)Required
  • namestringRequired
  • startDatestringRequired

    A note, YYYY-MM-DD, or empty. It gates nothing.

  • endDatestringRequired

    A note, YYYY-MM-DD, or empty.

  • archivedbooleanRequired
  • bookingsintegerRequired

    Bookings in the campaign.

  • liveintegerRequired

    Those with a file on a screen now.

  • customerobjectRequiredNullable

    Who the campaign is for. Its bookings with no customer of their own are for it.

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

    Loop rules; a rule that is null or left out is not set.

    Show child attributesHide child attributes
    • sharePctintegerOptionalNullable
    • playsPerHourintegerOptionalNullable
    • playsPerDayintegerOptionalNullable
  • windowobjectRequiredNullable

    The daily window its bookings play in (null for none).

    Show child attributesHide child attributes
    • startstringOptional
    • endstringOptional
    • daysarray of stringsOptional

Errors

StatusCodeMeaning
401invalid_token

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

403wrong_keyplan_refused

wrong_key (the key or role can’t do this), a key limited to some screens, or plan_refused.

404

No such campaign.

409api_offintegration_off

api_off or integration_off.

Update a booking's volume

PermissionScreens · Write

Needs the Screens write permission and an owner. volume is 0 to 100, or null to play the booking muted. It is heard only at a screen whose sound is on. A key limited to some screens may set it only for a booking that plays on its own screens alone (403 screens_limited).

Path parameters

  • idstring (uuid)Required

Body parameters

  • volumeintegerRequiredNullable

Returns

The booking’s volume as it is now.

An object with:

  • idstringOptional
  • volumeintegerOptionalNullable

Errors

StatusCodeMeaning
400

A volume that is not 0 to 100 or null (with field).

401invalid_token

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

403wrong_keyscreens_limited

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

404unknown_bookingnot_connected

unknown_booking (not a booking of the organisation), or not_connected.

409api_offintegration_off

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

413

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

501

The player is not available on this server.

Retrieve a content preview

PermissionScreens · Read

Needs the Screens read permission; any member’s session (a viewer too) will do. The small PNG preview of a content picture or video, at the address in its thumb.

Path parameters

  • idstring (uuid)Required

Returns

The PNG.

Errors

StatusCodeMeaning
401invalid_token

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

403

“Your role (<role>) can’t <action>.” (the role is below the route’s minimum) or “Choose an organisation first.” (the session has no organisation).

404not_connected

No such file in this organisation, no preview, or not_connected.

409api_offintegration_off

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