Player API reference
Verify plays, batches and uptime
Mestra signs three things you can check without calling Mestra: the receipt on a play’s file, the receipt on a batch of plays, and a screen’s uptime statement for a day. All three use the same published keys. This page says what each proves, what it doesn’t, and how to check it.
The public keys are at https://app.withmestra.com/.well-known/mestra-receipt-keys.json. No sign-in is needed and the document can be cached.
{"keys": [{"keyId": "2026-11", "algorithm": "Ed25519", "publicKey": "…", "validFrom": "2026-11-01T00:00:00Z", "retiredAt": "2027-02-01T00:00:00Z", "signing": false}]}publicKey is the 32-byte Ed25519 public key, base64url without padding. Old keys stay listed with signing false and a retiredAt, so a signature made before a key was replaced still checks. The key in use has no retiredAt.
What a play proves
A play row is the screen’s own report that it showed the file with this sha256, starting at playedAt in zone, for durationMs. Mestra stores it as sent, after checking that the entry is the screen’s and the file is one of the organisation’s files.
The play itself is not signed. It is the screen’s claim, sent over its signed-in connection. Nothing proves the screen really showed the file.
A play’s check.state is one of:
| State | Meaning |
|---|---|
signed |
The file passed its checks and has a receipt, which the row includes. Everything below applies. |
checked |
The file passed a check made before receipts began, with no rule set, or while the server had no signing key. There is nothing to verify offline. |
unchecked |
No passing check of that exact file was found when the play arrived. The play is shown, never hidden. Treat it as unapproved until you have looked. |
Check a signature
All three signed things are checked the same way, with a different prefix on the signed message.
- Find the key whose
keyIdequals the signed object’s. No such key: reject. The object’screatedAtmust fall in the key’s window, fromvalidFromup to but not includingretiredAt. - Remove
signaturefrom the object and canonicalize what is left with RFC 8785 (JSON Canonicalization Scheme): members sorted, no spaces, numbers and strings written the one standard way. The order and spacing of the object as sent never matter. - The signed message is the prefix line below, a newline, then those bytes. Verify the Ed25519 signature over it. The signature is base64url with no padding and no line breaks.
| What | Prefix |
|---|---|
A file’s receipt (check.receipt on a play) |
mestra-receipt/1 |
A batch of plays (batch.receipt) |
mestra-plays/1 |
An uptime statement (receipt on a day) |
mestra-uptime-v1 |
Each prefix is different, so a signature for one kind of document never passes as another.
Check a play’s file receipt
A play’s check.receipt is Mestra’s signature over a statement that this exact file passed rule-set version ruleSetVersionId for organisation orgId. It proves the file’s approval, not the play. It is the check Mestra found when the play arrived, so its createdAt can be later than playedAt. A valid receipt does not show the file was approved before it aired.
{ "version": 1, "keyId": "2026-11", "orgId": "…", "jobId": "…", "formatKey": "square", "fileSha256": "…", "ruleSetVersionId": "…", "passed": true, "checksDigest": "…", "createdAt": "2026-11-07T03:04:05.000000Z", "signature": "…"}play.sha256must equalplay.check.receipt.fileSha256.- Check the signature as above, with the prefix
mestra-receipt/1. - Pin what you trust. Check that
orgIdis your organisation and thatruleSetVersionIdis a version you accept. A valid signature on another organisation’s or another version’s receipt proves nothing about yours. - If you hold the file, its SHA-256 must equal
play.sha256.
If any step fails, treat the row as unverified. checksDigest is the hex SHA-256 of the canonical form of the checks the file was measured with, so you can also tie a receipt to checks you hold.
Check a batch
Each play names the batch it arrived in: batch (null for a play stored before batches), whose id names it. GET /player/plays/batches/{id} returns {batch, plays}: the batch’s own plays and batch.receipt. A batch shows once its plays do. Before then, for another organisation’s batch, or for a screen outside a limited key’s scope, it answers 404 with the code unknown_batch. A batch whose booking was deleted afterwards can no longer be rebuilt, because deleting a booking removes its plays: it answers 404 with the code batch_incomplete. That is not tampering.
What it proves. Mestra received exactly these plays from this screen at this time and has not changed them since. It doesn’t prove anyone saw the content, or that the screen’s report is true. Together with the file receipt it shows an approved file, reported played by this screen, kept unaltered since. The play itself is still the screen’s claim.
A batch stored while the server had no signing key has batch.signed false and batch.receipt null. The plays are listed and there is nothing to verify offline.
To check one:
- Fetch the batch.
- Build a line from each row in
plays, with exactly these members and the row’s values:id,screenId,publicationId,itemId,entryId,sha256,playedAtLocal,zone,durationMs, andoutOfSteponly when it is true (leave it out when the row has none or false). - Recompute the digest. Write each line in canonical JSON (RFC 8785), order the lines by
id, join them with a newline and take the hex SHA-256. It must equalbatch.receipt.playsDigest, andbatch.receipt.playsmust equal the number of rows. - Check the signature, with the prefix
mestra-plays/1. The receipt has exactly ten members:version,keyId,orgId,screenId,batchId,receivedAt,plays,playsDigest,createdAtandsignature. One more or fewer is invalid. - Pin the identity.
receipt.orgIdis your organisation,receipt.screenIdis the screen you expect,receipt.batchIdis the batch you asked for, and every row’sscreenIdis that screen.
If any step fails, treat the batch as unverified. If you don’t trust a play, compare it with what the screen reported, not only with Mestra’s copy.
Check an uptime statement
GET /player/devices/{id}/uptime gives each closed day of a screen with a receipt: Mestra’s signed statement of that day.
{"version": 1, "keyId": "...", "kind": "uptime", "orgId": "...", "deviceId": "...", "day": "2027-09-01", "zone": "Australia/Sydney", "revision": 1, "countedS": 86400, "downS": 600, "sitePowerS": 0, "holdingS": 0, "standbyS": 0, "silentS": 0, "offlineUnverifiedS": 0, "disputedMinutes": 0, "lateMinutes": 0, "firstHash": "...", "lastHash": "...", "signedBy": "tpm", "createdAt": "2027-09-02T00:01:00.000000Z", "signature": "..."}- Check the signature, with the prefix
mestra-uptime-v1. - Pin
kindtouptime,orgIdto your organisation anddeviceIdto the screen you mean. - To know you hold the latest statement, fetch the day from the API and compare
revision. A day is signed again, with a higherrevisionand a latercreatedAt, when an hour that belongs to it arrives late. An older statement stays valid as a signature.
What it says. On day, in zone, Mestra counted countedS seconds for the screen, of which downS it wasn’t showing what it should, and sitePowerS of those were lost to the site’s power. Uptime is (countedS - downS) / countedS. Excluding site power it is (countedS - downS) / (countedS - sitePowerS). Totals over days, sites or the organisation add the seconds first and divide once. They are never an average of percentages.
| Field | Meaning |
|---|---|
holdingS |
The part of downS the panel spent showing the stop show from its own storage while it restarted. |
standbyS |
Time the standby player showed a live item. It is counted as up. |
silentS |
The part of downS that comes from Mestra’s own record, not the screen’s: time Mestra heard nothing from the screen and the screen sent no record for, such as a PC off for days. Time the screen later sends signed hours for is never counted here, so an outage on Mestra’s side doesn’t count against a screen. |
offlineUnverifiedS |
Content the screen claimed while Mestra heard nothing from it. It counts as up and rests on the screen’s own signed record. It is reported apart. |
disputedMinutes |
Minutes whose record contradicts what Mestra held (the screen reported content while it was stopped or halted, or called itself halted without a halt Mestra saw), or whose hour was rewritten or didn’t link into the chain. A disputed minute is never up: it is in countedS and downS whatever the screen said. |
lateMinutes |
Minutes that arrived more than two hours after their hour ended: the screen’s own report of time it was offline, reported apart, and no longer a dispute. |
signedBy |
Which device key signed the hours the day rests on: tpm when every hour was signed by a key made in the screen’s TPM and proven by it, software when every hour was signed but not all by a TPM key. Absent when an hour was unsigned. |
firstHash, lastHash |
The hashes of the first and last hourly record the day rests on. Both are empty for a day that rests only on Mestra’s record. |
Each hour is sealed by the screen into a hash chain that Mestra checks when it arrives.
What it doesn’t prove. The minutes are the screen’s own report. Mestra checks the chain and the seal but can’t see the panel. A stolen device key, or a wrongly set clock, can send a clean chain.