API reference
Loop
A screen’s loop is the playlist it repeats. Loop settings are the rules the loop is built under, and are set at three levels: for all screens, for a site, or for one screen. A setting that is not set means no rule. See Who plays when: customers and the loop for the guide.
The Loop settings object
The loop settings set at one level. A setting that is not set is null, and means no rule: Mestra picks no value.
Attributes
loopMsintegerRequiredNullableHow long a loop is, in milliseconds.
defaultSlotMsintegerRequiredNullableHow long a slot is when a booking doesn’t say, in milliseconds.
maxLoopMsintegerRequiredNullableA hard limit: the longest a loop may be, in milliseconds. At least
loopMs.minSlotMsintegerRequiredNullableA hard limit: the shortest a slot may be, in milliseconds. At most
defaultSlotMs.maxSharePctintegerRequiredNullableA hard limit: the most of a loop any one customer may take, 1 to 100.
orderstringRequiredNullableThe order of turns in a loop.
Possible values
as_bookedspreadshufflednull
Retrieve the loop settings for all screens
Needs the Screens read permission and an owner. A key limited to some screens can’t use it (403 screens_limited). The settings every screen’s loop is built under unless its site or the screen sets its own.
Returns
The organisation’s settings.
Returns the Loop settings object.
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 |
|
Create or update the loop settings for all screens
Needs the Screens write permission and an owner. Sets the loop settings for all screens; they reach every screen of the organisation. A PUT replaces the settings at this level: a setting left out is cleared. A key limited to some screens can’t use it (403 screens_limited).
Body parameters
loopMsintegerOptionalNullableHow long a loop is, in milliseconds.
defaultSlotMsintegerOptionalNullableHow long a slot is when a booking doesn’t say, in milliseconds.
maxLoopMsintegerOptionalNullableA hard limit: the longest a loop may be, in milliseconds. At least
loopMs.minSlotMsintegerOptionalNullableA hard limit: the shortest a slot may be, in milliseconds. At most
defaultSlotMs.maxSharePctintegerOptionalNullableA hard limit: the most of a loop any one customer may take, 1 to 100.
orderstringOptionalNullableThe order of turns in a loop.
Possible values
as_bookedspreadshufflednull
Returns
Saved; the settings as the matching GET answers them.
Returns the Loop settings object.
Errors
| Status | Code | Meaning |
|---|---|---|
400 | loop_longer_than_maxslot_shorter_than_min | A value out of range (with |
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_keyplan_refused |
|
404 | not_connected |
|
409 | api_offintegration_off |
|
Retrieve a site's loop settings
Needs the Screens read permission and an owner. A key limited to some screens can’t use it (403 screens_limited). The settings a site’s screens are built under unless a screen sets its own.
Path parameters
sitestringRequiredThe site’s site code.
Returns
The site’s settings.
Returns the Loop settings 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 |
|
Create or update a site's loop settings
Needs the Screens write permission and an owner. A PUT replaces the settings at this level: a setting left out is cleared. A key limited to some screens can’t use it (403 screens_limited). Sets a site’s loop settings; they reach the screens linked to the site.
Path parameters
sitestringRequiredThe site’s site code.
Body parameters
loopMsintegerOptionalNullableHow long a loop is, in milliseconds.
defaultSlotMsintegerOptionalNullableHow long a slot is when a booking doesn’t say, in milliseconds.
maxLoopMsintegerOptionalNullableA hard limit: the longest a loop may be, in milliseconds. At least
loopMs.minSlotMsintegerOptionalNullableA hard limit: the shortest a slot may be, in milliseconds. At most
defaultSlotMs.maxSharePctintegerOptionalNullableA hard limit: the most of a loop any one customer may take, 1 to 100.
orderstringOptionalNullableThe order of turns in a loop.
Possible values
as_bookedspreadshufflednull
Returns
Saved; the settings as the matching GET answers them.
Returns the Loop settings object.
Errors
| Status | Code | Meaning |
|---|---|---|
400 | loop_longer_than_maxslot_shorter_than_min | A value out of range (with |
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_keyplan_refused |
|
404 | unknown_sitenot_connected |
|
409 | api_offintegration_off |
|
Retrieve a screen's loop settings
Needs the Screens read permission and an editor (a viewer can read the screen’s loop, but not its loop settings). A key limited to some screens can use it for its own screens. A screen’s own loop settings, the ones its loop is built under, and where each came from.
Path parameters
idstring (uuid)Required
Returns
The screen’s settings.
An object with:
ownobjectRequiredThe loop settings set at one level. A setting that is not set is
null, and means no rule: Mestra picks no value.Show child attributesHide child attributes
loopMsintegerRequiredNullableHow long a loop is, in milliseconds.
defaultSlotMsintegerRequiredNullableHow long a slot is when a booking doesn’t say, in milliseconds.
maxLoopMsintegerRequiredNullableA hard limit: the longest a loop may be, in milliseconds. At least
loopMs.minSlotMsintegerRequiredNullableA hard limit: the shortest a slot may be, in milliseconds. At most
defaultSlotMs.maxSharePctintegerRequiredNullableA hard limit: the most of a loop any one customer may take, 1 to 100.
orderstringRequiredNullableThe order of turns in a loop.
Possible values
as_bookedspreadshufflednull
resolvedobjectRequiredWhat the screen’s loop is built under: each setting from the screen, else its site, else the organisation.
Show child attributesHide child attributes
loopMsintegerRequiredNullableHow long a loop is, in milliseconds.
defaultSlotMsintegerRequiredNullableHow long a slot is when a booking doesn’t say, in milliseconds.
maxLoopMsintegerRequiredNullableA hard limit: the longest a loop may be, in milliseconds. At least
loopMs.minSlotMsintegerRequiredNullableA hard limit: the shortest a slot may be, in milliseconds. At most
defaultSlotMs.maxSharePctintegerRequiredNullableA hard limit: the most of a loop any one customer may take, 1 to 100.
orderstringRequiredNullableThe order of turns in a loop.
Possible values
as_bookedspreadshufflednull
fromobjectRequiredThe level each set setting of
resolvedcame from, by its name. A screen in a group is built under its group’s settings:groupis the group’s own level. A setting that is set nowhere is left out.
Errors
| Status | Code | Meaning |
|---|---|---|
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
404 | unknown_screennot_connected |
|
409 | api_offintegration_off |
|
Create or update a screen's loop settings
Needs the Screens write permission and an editor. A PUT replaces the settings at this level: a setting left out is cleared. A key limited to some screens can use it for its own screens. Sets a screen’s own loop settings; they win over its site’s and the organisation’s.
Path parameters
idstring (uuid)Required
Body parameters
loopMsintegerOptionalNullableHow long a loop is, in milliseconds.
defaultSlotMsintegerOptionalNullableHow long a slot is when a booking doesn’t say, in milliseconds.
maxLoopMsintegerOptionalNullableA hard limit: the longest a loop may be, in milliseconds. At least
loopMs.minSlotMsintegerOptionalNullableA hard limit: the shortest a slot may be, in milliseconds. At most
defaultSlotMs.maxSharePctintegerOptionalNullableA hard limit: the most of a loop any one customer may take, 1 to 100.
orderstringOptionalNullableThe order of turns in a loop.
Possible values
as_bookedspreadshufflednull
Returns
Saved; the settings as the matching GET answers them.
An object with:
ownobjectRequiredThe loop settings set at one level. A setting that is not set is
null, and means no rule: Mestra picks no value.Show child attributesHide child attributes
loopMsintegerRequiredNullableHow long a loop is, in milliseconds.
defaultSlotMsintegerRequiredNullableHow long a slot is when a booking doesn’t say, in milliseconds.
maxLoopMsintegerRequiredNullableA hard limit: the longest a loop may be, in milliseconds. At least
loopMs.minSlotMsintegerRequiredNullableA hard limit: the shortest a slot may be, in milliseconds. At most
defaultSlotMs.maxSharePctintegerRequiredNullableA hard limit: the most of a loop any one customer may take, 1 to 100.
orderstringRequiredNullableThe order of turns in a loop.
Possible values
as_bookedspreadshufflednull
resolvedobjectRequiredWhat the screen’s loop is built under: each setting from the screen, else its site, else the organisation.
Show child attributesHide child attributes
loopMsintegerRequiredNullableHow long a loop is, in milliseconds.
defaultSlotMsintegerRequiredNullableHow long a slot is when a booking doesn’t say, in milliseconds.
maxLoopMsintegerRequiredNullableA hard limit: the longest a loop may be, in milliseconds. At least
loopMs.minSlotMsintegerRequiredNullableA hard limit: the shortest a slot may be, in milliseconds. At most
defaultSlotMs.maxSharePctintegerRequiredNullableA hard limit: the most of a loop any one customer may take, 1 to 100.
orderstringRequiredNullableThe order of turns in a loop.
Possible values
as_bookedspreadshufflednull
fromobjectRequiredThe level each set setting of
resolvedcame from, by its name. A screen in a group is built under its group’s settings:groupis the group’s own level. A setting that is set nowhere is left out.
Errors
| Status | Code | Meaning |
|---|---|---|
400 | loop_longer_than_maxslot_shorter_than_min | A value out of range (with |
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_keyplan_refused |
|
404 | unknown_screennot_connected |
|
409 | api_offintegration_off |
|
Retrieve a screen's loop
Needs the Screens read permission; any member’s session (a viewer too) will do. What a screen’s loop will do, planned before it plays: the turns each booking asked for and was given, why they differ, and the order they play in.
Path parameters
idstring (uuid)Required
Query parameters
atstring (date-time)OptionalAn instant in the next 7 days: only the plan that is live then. Leave out for every plan.
Returns
The screen’s loop.
An object with:
modestringRequiredas_before: nothing in force asks for a plan, and the screen loops its bookings in order.Possible values
planas_beforesettingsobjectRequiredThe loop settings the loop is built under.
Show child attributesHide child attributes
loopMsintegerRequiredNullableHow long a loop is, in milliseconds.
defaultSlotMsintegerRequiredNullableHow long a slot is when a booking doesn’t say, in milliseconds.
maxLoopMsintegerRequiredNullableA hard limit: the longest a loop may be, in milliseconds. At least
loopMs.minSlotMsintegerRequiredNullableA hard limit: the shortest a slot may be, in milliseconds. At most
defaultSlotMs.maxSharePctintegerRequiredNullableA hard limit: the most of a loop any one customer may take, 1 to 100.
orderstringRequiredNullableThe order of turns in a loop.
Possible values
as_bookedspreadshufflednull
fromobjectRequiredThe level each set setting came from.
plansarray of objectsRequiredShow child attributesHide child attributes
livearray of objectsRequiredThe bookings that are live together in this plan.
Show child attributesHide child attributes
idstring (uuid)RequirednamestringRequiredcustomerstringOptionalThe customer’s name; left out when the booking has none.
categorystringOptionalThe customer’s category; left out when it has none.
durationMsintegerRequired
fromstring (date-time)RequiredThe first stretch of the next 7 days in which these bookings are live together starts here.
untilstring (date-time)RequiredWhere that stretch ends.
loopMsintegerRequiredHow long the loop is, gaps included.
gapMsintegerRequiredHow long a gap turn shows the stop show.
ordersarray of arraysRequiredThe turns, one booking id each; an empty string is a gap. Played in turn when there are several.
turnsarray of objectsRequiredShow child attributesHide child attributes
entryIdstring (uuid)RequiredaskedintegerRequiredThe turns the booking asked for (its slots).
givenintegerRequiredThe turns it gets in the loop.
whyarray of stringsRequiredIn words, why
givendiffers fromasked.
notesarray of objectsRequiredWhat was done to keep every cap and separation. A fill or gap note stands for a count of turns, one note for each booking.
Show child attributesHide child attributes
kindstringRequiredPossible values
cutleft_outover_bookedfill_paidfill_househousegaptoo_largeentryIdstring (uuid)OptionaltextstringRequired
Errors
| Status | Code | Meaning |
|---|---|---|
400 |
| |
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
404 | unknown_screennot_connected |
|
409 | api_offintegration_off |
|