Skip to content

API reference

Loop

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

  • loopMsintegerRequiredNullable

    How long a loop is, in milliseconds.

  • defaultSlotMsintegerRequiredNullable

    How long a slot is when a booking doesn’t say, in milliseconds.

  • maxLoopMsintegerRequiredNullable

    A hard limit: the longest a loop may be, in milliseconds. At least loopMs.

  • minSlotMsintegerRequiredNullable

    A hard limit: the shortest a slot may be, in milliseconds. At most defaultSlotMs.

  • maxSharePctintegerRequiredNullable

    A hard limit: the most of a loop any one customer may take, 1 to 100.

  • orderstringRequiredNullable

    The order of turns in a loop.

    Possible valuesas_bookedspreadshufflednull

Retrieve the loop settings for all screens

PermissionScreens · Read

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

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) or a key limited to some screens.

404not_connected

not_connected.

409api_offintegration_off

api_off or integration_off.

Create or update the loop settings for all screens

PermissionScreens · Write

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

  • loopMsintegerOptionalNullable

    How long a loop is, in milliseconds.

  • defaultSlotMsintegerOptionalNullable

    How long a slot is when a booking doesn’t say, in milliseconds.

  • maxLoopMsintegerOptionalNullable

    A hard limit: the longest a loop may be, in milliseconds. At least loopMs.

  • minSlotMsintegerOptionalNullable

    A hard limit: the shortest a slot may be, in milliseconds. At most defaultSlotMs.

  • maxSharePctintegerOptionalNullable

    A hard limit: the most of a loop any one customer may take, 1 to 100.

  • orderstringOptionalNullable

    The order of turns in a loop.

    Possible valuesas_bookedspreadshufflednull

Returns

Saved; the settings as the matching GET answers them.

Returns the Loop settings object.

Errors

StatusCodeMeaning
400loop_longer_than_maxslot_shorter_than_min

A value out of range (with field: loopMs, defaultSlotMs, maxLoopMs, minSlotMs, maxSharePct or order), or loop_longer_than_max, or slot_shorter_than_min.

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 (where it may not) or plan_refused.

404not_connected

not_connected.

409api_offintegration_off

api_off or integration_off.

Retrieve a site's loop settings

PermissionScreens · Read

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

  • sitestringRequired

    The site’s site code.

Returns

The site’s settings.

Returns the Loop settings 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 or role can’t do this) or a key limited to some screens.

404unknown_sitenot_connected

unknown_site, or not_connected.

409api_offintegration_off

api_off or integration_off.

Create or update a site's loop settings

PermissionScreens · Write

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

  • sitestringRequired

    The site’s site code.

Body parameters

  • loopMsintegerOptionalNullable

    How long a loop is, in milliseconds.

  • defaultSlotMsintegerOptionalNullable

    How long a slot is when a booking doesn’t say, in milliseconds.

  • maxLoopMsintegerOptionalNullable

    A hard limit: the longest a loop may be, in milliseconds. At least loopMs.

  • minSlotMsintegerOptionalNullable

    A hard limit: the shortest a slot may be, in milliseconds. At most defaultSlotMs.

  • maxSharePctintegerOptionalNullable

    A hard limit: the most of a loop any one customer may take, 1 to 100.

  • orderstringOptionalNullable

    The order of turns in a loop.

    Possible valuesas_bookedspreadshufflednull

Returns

Saved; the settings as the matching GET answers them.

Returns the Loop settings object.

Errors

StatusCodeMeaning
400loop_longer_than_maxslot_shorter_than_min

A value out of range (with field: loopMs, defaultSlotMs, maxLoopMs, minSlotMs, maxSharePct or order), or loop_longer_than_max, or slot_shorter_than_min.

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 (where it may not) or plan_refused.

404unknown_sitenot_connected

unknown_site, or not_connected.

409api_offintegration_off

api_off or integration_off.

Retrieve a screen's loop settings

PermissionScreens · Read

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:

  • ownobjectRequired

    The 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
    • loopMsintegerRequiredNullable

      How long a loop is, in milliseconds.

    • defaultSlotMsintegerRequiredNullable

      How long a slot is when a booking doesn’t say, in milliseconds.

    • maxLoopMsintegerRequiredNullable

      A hard limit: the longest a loop may be, in milliseconds. At least loopMs.

    • minSlotMsintegerRequiredNullable

      A hard limit: the shortest a slot may be, in milliseconds. At most defaultSlotMs.

    • maxSharePctintegerRequiredNullable

      A hard limit: the most of a loop any one customer may take, 1 to 100.

    • orderstringRequiredNullable

      The order of turns in a loop.

      Possible valuesas_bookedspreadshufflednull

  • resolvedobjectRequired

    What the screen’s loop is built under: each setting from the screen, else its site, else the organisation.

    Show child attributesHide child attributes
    • loopMsintegerRequiredNullable

      How long a loop is, in milliseconds.

    • defaultSlotMsintegerRequiredNullable

      How long a slot is when a booking doesn’t say, in milliseconds.

    • maxLoopMsintegerRequiredNullable

      A hard limit: the longest a loop may be, in milliseconds. At least loopMs.

    • minSlotMsintegerRequiredNullable

      A hard limit: the shortest a slot may be, in milliseconds. At most defaultSlotMs.

    • maxSharePctintegerRequiredNullable

      A hard limit: the most of a loop any one customer may take, 1 to 100.

    • orderstringRequiredNullable

      The order of turns in a loop.

      Possible valuesas_bookedspreadshufflednull

  • fromobjectRequired

    The level each set setting of resolved came from, by its name. A screen in a group is built under its group’s settings: group is the group’s own level. A setting that is set nowhere is left out.

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).

404unknown_screennot_connected

unknown_screen (including one the key doesn’t hold), or not_connected.

409api_offintegration_off

api_off or integration_off.

Create or update a screen's loop settings

PermissionScreens · Write

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

  • loopMsintegerOptionalNullable

    How long a loop is, in milliseconds.

  • defaultSlotMsintegerOptionalNullable

    How long a slot is when a booking doesn’t say, in milliseconds.

  • maxLoopMsintegerOptionalNullable

    A hard limit: the longest a loop may be, in milliseconds. At least loopMs.

  • minSlotMsintegerOptionalNullable

    A hard limit: the shortest a slot may be, in milliseconds. At most defaultSlotMs.

  • maxSharePctintegerOptionalNullable

    A hard limit: the most of a loop any one customer may take, 1 to 100.

  • orderstringOptionalNullable

    The order of turns in a loop.

    Possible valuesas_bookedspreadshufflednull

Returns

Saved; the settings as the matching GET answers them.

An object with:

  • ownobjectRequired

    The 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
    • loopMsintegerRequiredNullable

      How long a loop is, in milliseconds.

    • defaultSlotMsintegerRequiredNullable

      How long a slot is when a booking doesn’t say, in milliseconds.

    • maxLoopMsintegerRequiredNullable

      A hard limit: the longest a loop may be, in milliseconds. At least loopMs.

    • minSlotMsintegerRequiredNullable

      A hard limit: the shortest a slot may be, in milliseconds. At most defaultSlotMs.

    • maxSharePctintegerRequiredNullable

      A hard limit: the most of a loop any one customer may take, 1 to 100.

    • orderstringRequiredNullable

      The order of turns in a loop.

      Possible valuesas_bookedspreadshufflednull

  • resolvedobjectRequired

    What the screen’s loop is built under: each setting from the screen, else its site, else the organisation.

    Show child attributesHide child attributes
    • loopMsintegerRequiredNullable

      How long a loop is, in milliseconds.

    • defaultSlotMsintegerRequiredNullable

      How long a slot is when a booking doesn’t say, in milliseconds.

    • maxLoopMsintegerRequiredNullable

      A hard limit: the longest a loop may be, in milliseconds. At least loopMs.

    • minSlotMsintegerRequiredNullable

      A hard limit: the shortest a slot may be, in milliseconds. At most defaultSlotMs.

    • maxSharePctintegerRequiredNullable

      A hard limit: the most of a loop any one customer may take, 1 to 100.

    • orderstringRequiredNullable

      The order of turns in a loop.

      Possible valuesas_bookedspreadshufflednull

  • fromobjectRequired

    The level each set setting of resolved came from, by its name. A screen in a group is built under its group’s settings: group is the group’s own level. A setting that is set nowhere is left out.

Errors

StatusCodeMeaning
400loop_longer_than_maxslot_shorter_than_min

A value out of range (with field: loopMs, defaultSlotMs, maxLoopMs, minSlotMs, maxSharePct or order), or loop_longer_than_max, or slot_shorter_than_min.

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 (where it may not) or plan_refused.

404unknown_screennot_connected

unknown_screen (including one the key doesn’t hold), or not_connected.

409api_offintegration_off

api_off or integration_off.

Retrieve a screen's loop

PermissionScreens · Read

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

    An 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:

  • modestringRequired

    as_before: nothing in force asks for a plan, and the screen loops its bookings in order.

    Possible valuesplanas_before

  • settingsobjectRequired

    The loop settings the loop is built under.

    Show child attributesHide child attributes
    • loopMsintegerRequiredNullable

      How long a loop is, in milliseconds.

    • defaultSlotMsintegerRequiredNullable

      How long a slot is when a booking doesn’t say, in milliseconds.

    • maxLoopMsintegerRequiredNullable

      A hard limit: the longest a loop may be, in milliseconds. At least loopMs.

    • minSlotMsintegerRequiredNullable

      A hard limit: the shortest a slot may be, in milliseconds. At most defaultSlotMs.

    • maxSharePctintegerRequiredNullable

      A hard limit: the most of a loop any one customer may take, 1 to 100.

    • orderstringRequiredNullable

      The order of turns in a loop.

      Possible valuesas_bookedspreadshufflednull

  • fromobjectRequired

    The level each set setting came from.

  • plansarray of objectsRequired
    Show child attributesHide child attributes
    • livearray of objectsRequired

      The bookings that are live together in this plan.

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

        The customer’s name; left out when the booking has none.

      • categorystringOptional

        The customer’s category; left out when it has none.

      • durationMsintegerRequired
    • fromstring (date-time)Required

      The first stretch of the next 7 days in which these bookings are live together starts here.

    • untilstring (date-time)Required

      Where that stretch ends.

    • loopMsintegerRequired

      How long the loop is, gaps included.

    • gapMsintegerRequired

      How long a gap turn shows the stop show.

    • ordersarray of arraysRequired

      The turns, one booking id each; an empty string is a gap. Played in turn when there are several.

    • turnsarray of objectsRequired
      Show child attributesHide child attributes
      • entryIdstring (uuid)Required
      • askedintegerRequired

        The turns the booking asked for (its slots).

      • givenintegerRequired

        The turns it gets in the loop.

      • whyarray of stringsRequired

        In words, why given differs from asked.

    • notesarray of objectsRequired

      What 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
      • kindstringRequired

        Possible valuescutleft_outover_bookedfill_paidfill_househousegaptoo_large

      • entryIdstring (uuid)Optional
      • textstringRequired

Errors

StatusCodeMeaning
400

at is not a time (with field: at).

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).

404unknown_screennot_connected

unknown_screen (including one the key doesn’t hold), or not_connected.

409api_offintegration_off

api_off or integration_off.