Skip to content

API reference

Plays

A play is the proof that a screen showed a booked item at a time. Plays are listed, totalled and exported as CSV, and a batch is the set of plays a screen uploaded together, signed by Mestra. To check a proof-of-play row or a play batch against Mestra’s public keys, see Verify plays, batches and uptime. See Proof of play for the guide.

The Play object

One play: a screen showing a booked item at a moment, with the screen, site, booking and length, and a hash and check that tie it to Mestra’s signed receipt.

Attributes

  • idstringOptional

    A stable id for the play.

  • sourcestringOptional

    Possible valuesmestra

  • playedBystringOptional

    Which player showed the play: standby when the screen’s backup player showed any part of it while the main player was being repaired, else main. Plays stored before this existed read main. source is the kind of screen, not this.

    Possible valuesmainstandby

  • screenIdstring (uuid)Optional
  • screenNamestringOptional

    Empty when the screen has been removed.

  • frameobjectOptionalNullable

    The frame of the screen the play was in; null for a play of the whole window.

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

    The site the screen was linked to when it played, the same {key, name} a screen’s site has; null when it had none. Plays stored before this was recorded show the screen’s current link.

    Show child attributesHide child attributes
    • keystringOptional

      The brand code.

    • namestringOptional
  • batchobjectOptionalNullable

    The signed batch of plays this play arrived in; read it with GET /player/plays/batches/{id}. Null for a play stored before batches.

    Show child attributesHide child attributes
    • idstring (uuid)Required
  • publicationIdstring (uuid)Optional
  • itemIdstring (uuid)Optional
  • entryIdstring (uuid)Optional
  • playedAtLocalstringOptional

    The play’s start on the screen’s own clock, YYYY-MM-DDTHH:MM:SS.mmm.

  • outOfStepbooleanOptional

    True when a member of a group played this item out of step: it was in step for less than the in-step floor (95%) of its slot. The play is kept and listed, never counted in totals or the CSV. Absent when false.

  • inStepPctintegerOptional

    For a group item’s play: the share of the slot the member was in step, in percent. Absent for a single screen’s play.

  • stepP95MsintegerOptional

    For a group item’s play: the 95th percentile of the member’s offset from the group’s step, in milliseconds. Absent for a single screen’s play.

  • zonestringOptional

    The screen’s time zone.

  • playedAtstring (date-time)Optional

    The start as a UTC time.

  • durationMsintegerOptional
  • sha256stringOptional
  • checkobjectOptional
    Show child attributesHide child attributes
    • statestringOptional

      Possible valuessignedcheckedunchecked

    • renderCheckIdstring (uuid)OptionalNullable
    • receiptobjectOptionalNullable

      The signed receipt when state is signed, else null.

List all plays

PermissionScreens · Read

Any member’s session (viewer, editor or owner), or a key with the Screens permission. The proof of play of your Mestra Player screens, in the order Mestra stored them. Every play has source mestra. A play shows a minute after Mestra stores it. check.state is signed (the file passed its checks and has a signed receipt, which is included), checked (it passed, no receipt) or unchecked. A page holds up to limit plays. next is the cursor to resume from: that of the page’s last play, or, when the page is empty, the cursor you sent. more is true while another page is ready now. To follow the feed, keep the last next and ask again with it later: a play that a screen uploaded late then appears after it. next is null only when you sent no cursor and there are no plays yet. A play never moves between pages, so reading with the cursor sees each play once. A screen that has since been removed keeps its plays.

Query parameters

  • cursorstringOptional

    The next of the previous response. Leave it out to start from the oldest play.

  • limitintegerOptional

    Plays in the page, 1 to 1000.

    Default200

  • screenstring (uuid)Optional

    Only this screen’s plays, or a frame’s when a frame id is given. A group id gives the plays of the group: those recorded under the group (a screen that has since left the group keeps them in it), and, for a play whose record carries no group (a screen’s own booking, or one stored before records carried it), those of the group’s members now. A key limited to a group may name the group or any of its members.

  • sitestringOptional

    Only the plays at this site code: the site the screen was linked to when it played. A play stored before that was recorded, or while the screen had no link, counts at the screen’s current link.

  • publicationstring (uuid)Optional

    Only this publication’s plays.

  • rowIdstringOptional

    Only the plays that showed this row of a Dynamic booking’s table (the row id the table names it by). A play of an ordinary booking has no row.

  • customerstring (uuid)Optional

    Only the plays of this customer’s bookings. A play names no customer: its booking does, read when you ask, so a booking moved to another customer takes its plays with it. A customer that isn’t yours is 404 unknown_customer.

  • playedFromstring (date)Optional

    First day, on the screen’s own clock, inclusive.

  • playedTostring (date)Optional

    Last day, on the screen’s own clock, inclusive.

Returns

A page of plays.

An object with:

  • playsarray of objectsOptional
    Show child attributesHide child attributes
    • idstringOptional

      A stable id for the play.

    • sourcestringOptional

      Possible valuesmestra

    • playedBystringOptional

      Which player showed the play: standby when the screen’s backup player showed any part of it while the main player was being repaired, else main. Plays stored before this existed read main. source is the kind of screen, not this.

      Possible valuesmainstandby

    • screenIdstring (uuid)Optional
    • screenNamestringOptional

      Empty when the screen has been removed.

    • frameobjectOptionalNullable

      The frame of the screen the play was in; null for a play of the whole window.

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

      The site the screen was linked to when it played, the same {key, name} a screen’s site has; null when it had none. Plays stored before this was recorded show the screen’s current link.

      Show child attributesHide child attributes
      • keystringOptional

        The brand code.

      • namestringOptional
    • batchobjectOptionalNullable

      The signed batch of plays this play arrived in; read it with GET /player/plays/batches/{id}. Null for a play stored before batches.

      Show child attributesHide child attributes
      • idstring (uuid)Required
    • publicationIdstring (uuid)Optional
    • itemIdstring (uuid)Optional
    • entryIdstring (uuid)Optional
    • playedAtLocalstringOptional

      The play’s start on the screen’s own clock, YYYY-MM-DDTHH:MM:SS.mmm.

    • outOfStepbooleanOptional

      True when a member of a group played this item out of step: it was in step for less than the in-step floor (95%) of its slot. The play is kept and listed, never counted in totals or the CSV. Absent when false.

    • inStepPctintegerOptional

      For a group item’s play: the share of the slot the member was in step, in percent. Absent for a single screen’s play.

    • stepP95MsintegerOptional

      For a group item’s play: the 95th percentile of the member’s offset from the group’s step, in milliseconds. Absent for a single screen’s play.

    • zonestringOptional

      The screen’s time zone.

    • playedAtstring (date-time)Optional

      The start as a UTC time.

    • durationMsintegerOptional
    • sha256stringOptional
    • checkobjectOptional
      Show child attributesHide child attributes
      • statestringOptional

        Possible valuessignedcheckedunchecked

      • renderCheckIdstring (uuid)OptionalNullable
      • receiptobjectOptionalNullable

        The signed receipt when state is signed, else null.

  • nextstringOptionalNullable

    The cursor to resume from: the last play’s, or the one you sent when the page is empty. Null only when you sent none and there are no plays.

  • morebooleanOptional

    True while another page is ready now; false on the last. Ask again later with next to follow the feed.

Errors

StatusCodeMeaning
400

A bad cursor, a limit outside 1 to 1000, a bad date, or a bad id (field names it).

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.

404not_connectedunknown_screenunknown_customerunknown_site

not_connected, unknown_screen (with ?screen=), unknown_customer (with ?customer=), or unknown_site (with ?site=, only for a key limited to some screens and none of them linked to that site; a key for every screen gets an empty list).

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 play totals

PermissionScreens · Read

Any member’s session (viewer, editor or owner), or a key with the Screens permission. Counts the plays the list returns over the same filters, except those a group member played out of step (outOfStep true in the list): they stay in the record and are never counted here or in the CSV. Rows are by publication, screen, site, customer or day, in key order. A play counts at the site it was linked to when it played, so moving a screen to another centre leaves its earlier plays where they were. Each row has the plays, their airtime in milliseconds, the screens that played, and how many plays are signed, checked and unchecked.

Query parameters

  • groupBystringRequired

    What to count by. day is the screen’s own date. customer is the customer of the booking now, named as it is named now; plays of a booking with no customer are key empty, label “No customer”.

    Possible valuespublicationscreensitecustomerday

  • screenstring (uuid)Optional

    Only this screen’s plays. A group id gives the plays of the group: those recorded under the group (a screen that has since left the group keeps them in it), and, for a play whose record carries no group (a screen’s own booking, or one stored before records carried it), those of the group’s members now. A key limited to a group may name the group or any of its members.

  • sitestringOptional

    Only the plays at this site code: the site the screen was linked to when it played. A play stored before that was recorded, or while the screen had no link, counts at the screen’s current link.

  • publicationstring (uuid)Optional

    Only this publication’s plays.

  • rowIdstringOptional

    Only the plays that showed this row of a Dynamic booking’s table (the row id the table names it by). A play of an ordinary booking has no row.

  • customerstring (uuid)Optional

    Only the plays of this customer’s bookings. A play names no customer: its booking does, read when you ask, so a booking moved to another customer takes its plays with it. A customer that isn’t yours is 404 unknown_customer.

  • playedFromstring (date)Optional

    First day, on the screen’s own clock, inclusive.

  • playedTostring (date)Optional

    Last day, on the screen’s own clock, inclusive.

Returns

The totals.

An object with:

  • groupBystringOptional

    Possible valuespublicationscreensitecustomerday

  • rowsarray of objectsOptional
    Show child attributesHide child attributes
    • keystringOptional

      The group: a publication id, a screen id, a site code (empty for no site) or a date.

    • labelstringOptional

      The publication’s campaign key, the screen’s name, the site code, or the date.

    • playsintegerOptional
    • durationMsintegerOptional
    • screensintegerOptional

      Screens that played.

    • signedintegerOptional

      Plays whose file’s check has a signed receipt stored. In the rare case a stored receipt can’t be read back, the play itself shows checked, so this can be more than the signed plays the feed and export show.

    • checkedintegerOptional

      Plays whose file passed a check with no signed receipt stored.

    • uncheckedintegerOptional

      Plays whose file had no check.

Errors

StatusCodeMeaning
400

A missing or unknown groupBy, a bad date, or a bad id (field names it).

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.

404not_connectedunknown_screenunknown_customerunknown_site

not_connected, unknown_screen (with ?screen=), unknown_customer (with ?customer=), or unknown_site (with ?site=, only for a key limited to some screens and none of them linked to that site; a key for every screen gets an empty list).

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.

Download plays as CSV

PermissionScreens · Read

Needs an editor’s or an owner’s key or session. Every play the filters match except those a group member played out of step (outOfStep true in the list), as a CSV download with no page limit. The header row is (the order is fixed; columns are only ever added at the end) play_id,screen_id,screen_name,site_key,site_name,publication_id,item_id,entry_id,played_at_local,zone,played_at_utc,duration_ms,sha256,played_by,check_state,render_check_id,receipt_key_id,receipt_json,batch_id,customer,row. site_key and site_name are the two parts of the JSON site object, both empty when the play has no site. batch_id is the JSON batch.id, empty for a play stored before batches. customer is the name of the customer its booking is for now, empty when it has none. row is the id of the row of a Dynamic booking’s table that the play showed (the value the rowId filter takes), empty for an ordinary booking. A cell that starts with =, +, -, @, a tab or a carriage return begins with ' so a spreadsheet won’t run it. The export is the plays stored a minute or more before it started. It streams: if it fails part-way the connection is cut without a clean end, so treat a download that ends in an error as incomplete.

Query parameters

  • screenstring (uuid)Optional

    Only this screen’s plays. A group id gives the plays of the group: those recorded under the group (a screen that has since left the group keeps them in it), and, for a play whose record carries no group (a screen’s own booking, or one stored before records carried it), those of the group’s members now. A key limited to a group may name the group or any of its members.

  • sitestringOptional

    Only the plays at this site code: the site the screen was linked to when it played. A play stored before that was recorded, or while the screen had no link, counts at the screen’s current link.

  • publicationstring (uuid)Optional

    Only this publication’s plays.

  • rowIdstringOptional

    Only the plays that showed this row of a Dynamic booking’s table (the row id the table names it by). A play of an ordinary booking has no row.

  • customerstring (uuid)Optional

    Only the plays of this customer’s bookings. A play names no customer: its booking does, read when you ask, so a booking moved to another customer takes its plays with it. A customer that isn’t yours is 404 unknown_customer.

  • playedFromstring (date)Optional

    First day, on the screen’s own clock, inclusive.

  • playedTostring (date)Optional

    Last day, on the screen’s own clock, inclusive.

Returns

The plays, as CSV.

Errors

StatusCodeMeaning
400

A bad date or id (field names it).

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_connectedunknown_screenunknown_customerunknown_site

not_connected, unknown_screen (with ?screen=), unknown_customer (with ?customer=), or unknown_site (with ?site=, only for a key limited to some screens and none of them linked to that site; a key for every screen gets an empty list).

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 signed batch of plays

PermissionScreens · Read

Needs an editor’s or an owner’s key or session. A batch is one upload of plays from one screen, as Mestra stored it, with the receipt Mestra signed as it arrived. Each play in the list carries batch.id. plays are the batch’s own plays (at most 500), exactly as the plays list shows them. A third party checks the batch with only this response and the public keys at /.well-known/mestra-receipt-keys.json: see the guide Verify plays, batches and uptime. The receipt says Mestra received exactly these plays from this screen at this time, and has not changed them since. It does not prove that anyone saw the content, or that the screen’s report is true. signed is false, and receipt null, for a batch stored while the server had no signing key. A batch shows once its plays do (a minute after Mestra stores them).

Path parameters

  • idstring (uuid)Required

Returns

The batch and its plays.

An object with:

  • batchobjectRequired
    Show child attributesHide child attributes
    • idstring (uuid)Required
    • screenIdstring (uuid)Required
    • receivedAtstring (date-time)Required

      When Mestra received the upload, to the microsecond.

    • playsintegerRequired

      How many plays the batch holds; the length of plays.

    • signedbooleanRequired
    • receiptobjectRequiredNullable

      Mestra’s signature over the batch: version, keyId, orgId, screenId, batchId, receivedAt, plays, playsDigest, createdAt and signature. Null when signed is false.

  • playsarray of objectsRequired
    Show child attributesHide child attributes
    • idstringOptional

      A stable id for the play.

    • sourcestringOptional

      Possible valuesmestra

    • playedBystringOptional

      Which player showed the play: standby when the screen’s backup player showed any part of it while the main player was being repaired, else main. Plays stored before this existed read main. source is the kind of screen, not this.

      Possible valuesmainstandby

    • screenIdstring (uuid)Optional
    • screenNamestringOptional

      Empty when the screen has been removed.

    • frameobjectOptionalNullable

      The frame of the screen the play was in; null for a play of the whole window.

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

      The site the screen was linked to when it played, the same {key, name} a screen’s site has; null when it had none. Plays stored before this was recorded show the screen’s current link.

      Show child attributesHide child attributes
      • keystringOptional

        The brand code.

      • namestringOptional
    • batchobjectOptionalNullable

      The signed batch of plays this play arrived in; read it with GET /player/plays/batches/{id}. Null for a play stored before batches.

      Show child attributesHide child attributes
      • idstring (uuid)Required
    • publicationIdstring (uuid)Optional
    • itemIdstring (uuid)Optional
    • entryIdstring (uuid)Optional
    • playedAtLocalstringOptional

      The play’s start on the screen’s own clock, YYYY-MM-DDTHH:MM:SS.mmm.

    • outOfStepbooleanOptional

      True when a member of a group played this item out of step: it was in step for less than the in-step floor (95%) of its slot. The play is kept and listed, never counted in totals or the CSV. Absent when false.

    • inStepPctintegerOptional

      For a group item’s play: the share of the slot the member was in step, in percent. Absent for a single screen’s play.

    • stepP95MsintegerOptional

      For a group item’s play: the 95th percentile of the member’s offset from the group’s step, in milliseconds. Absent for a single screen’s play.

    • zonestringOptional

      The screen’s time zone.

    • playedAtstring (date-time)Optional

      The start as a UTC time.

    • durationMsintegerOptional
    • sha256stringOptional
    • checkobjectOptional
      Show child attributesHide child attributes
      • statestringOptional

        Possible valuessignedcheckedunchecked

      • renderCheckIdstring (uuid)OptionalNullable
      • receiptobjectOptionalNullable

        The signed receipt when state is signed, else null.

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_batchbatch_incompletenot_connected

unknown_batch: no such batch, another organisation’s, a screen outside a limited key’s scope, or its plays are not shown yet. batch_incomplete: some of its plays were deleted afterwards with their booking, so it can’t be rebuilt (not tampering). 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.