Skip to content

Player API reference

Mestra Player API

The Mestra Player API lets your own systems work with the screens that run Mestra Player. List your screens and see what each is playing, ask one for a screenshot, stop a screen or take an ad off every screen, read proof of play as JSON or CSV, read uptime, and set up where screen telemetry goes.

It is part of the one API reference, under Mestra Player. It uses the same base URL, keys, errors and rate limits as the rest of the API, but its permissions and webhook events are its own.

Base URL

Text
https://app.withmestra.com/api/v1

Screen calls start /player, such as /player/devices. Monitoring calls start /telemetry. Ids are UUIDs, except a site, which is named by its centre code.

The calls the screens themselves make to Mestra are not part of this API.

To work with screens from an AI agent instead, see the Mestra Player tools in MCP.

Before you start

  • Mestra Player must be turned on for the organisation. Until it is, a call answers 409 with the code integration_off, or 404 with the code not_connected. See Mestra Player.
  • The API itself must be on. A call made while it is off answers 409 with the code api_off. See Authentication.
  • Make a key in Developer > API and MCP. Send it as Authorization: Bearer <key>. A key and a role both apply, as for the core API.

Permissions

Screens has its own permission area with three levels. Each call names the level it needs.

Permission What the key can do
Screens · Read See screens, sites, schedules, health, uptime and proof of play, and read screenshots and log bundles.
Screens · Takedown Read, and also stop a screen or a site and pull an ad off screens. It can’t start them again.
Screens · Write Takedown, and also add, change and remove screens, make install keys, ask a screen for a screenshot, logs, a restart or a reboot, and change hours, brightness, sound and power.

Monitoring uses Screens · Read to see destinations and Settings to change them. See Monitoring.

Only an owner can give a key, a service key or an MCP connection a Screens permission. A key acts at its maker’s role as it is now, so a call needs both the permission and the role, and each call says which: any member, an editor or an owner, or an owner. A call without the permission it needs answers 403 with the code wrong_key.

Roles

A person’s own session and an app token (a plugin’s or the command line’s, which have no key permissions) act at the person’s role, and can use the routes that name it. A viewer-role member can read screens, sites, plays and uptime, and the screenshots screens took. They can’t read the screens waiting to be set up, screen schedules, commands, takedowns, CSV exports, log bundles, or a screen’s panel link, update status and lockdown details, and they change nothing. An owner who is made a viewer or an editor keeps any Screens key they made, but it then acts at their new role and reads only what that role reads.

Screenshots show whatever was on the display at that moment, and log bundles hold what the PC logged. Treat a key that can read them like a view of everything on your screens.

Limit a key to some screens

An owner can limit a key that has a Screens permission to some sites and screen groups when making it. Screens added to those sites and groups later are included. A limited key fails closed:

  • A call about every screen at once answers 403 with the code screens_limited.
  • A screen outside the limit answers 404 with the code unknown_screen, the same as a screen that doesn’t exist.
  • A limit that matches no screen sees nothing.
  • A limit can’t be changed. Make a new key.
  • A limited key stops or switches a site only when it covers every screen at that site.

Errors every call can return

Each call lists only the errors particular to it. These can come from any of them. The error shape is on the Errors page.

Status Code Meaning
401 invalid_token The key is missing, unknown, expired or revoked.
403 wrong_key The key lacks the permission the call needs. The message says which.
403 screens_limited The key is limited to some screens and the call acts on all of them.
404 not_connected Mestra Player isn’t turned on.
404 unknown_screen No such screen, or one the key can’t see.
409 api_off An owner has turned the API off.
409 integration_off Mestra Player is turned off.
429 rate_limited, too_many Too many calls. Wait the seconds in Retry-After.

Add a screen by its pairing code

A screen that has installed Mestra Player shows a pairing code. To add it to your organisation from your own system, send the code to Claim a screen.

Scrape with a telemetry key

To pull your screens’ telemetry into your own Prometheus, Grafana Alloy or monitoring agent, make a telemetry read key and scrape GET /api/v1/telemetry/metrics. The key starts mtk_ and is sent as Authorization: Bearer mtk_…. It is not an API key: it reads this one organisation’s screen telemetry and opens no other route. The answer is OpenMetrics text, at most 60 seconds old, so the route works as a scrape target. Making the key is an owner’s, with Settings; see Monitoring.

The reference

Every call is in the API reference, with its parameters, permission, errors and a request to copy.

Page What it covers
Screens List, read, change, add, replace and remove screens, and read a screen’s schedule.
Screen groups Make a group, place its screens and give them their screen files.
Sites Read a site, and set its hours, brightness, sound and power.
Scheduling Upload content, and make, change, go live with and end bookings and campaigns.
Screen customers Make, change and archive the customers that bookings name, with the loop rules each sets.
Loop Set the loop settings of the organisation, a site or a screen, and read what a screen’s loop will play.
Screen commands Ask a screen for a screenshot, logs, a restart, a refetch or a reboot, and read the results.
Stop and takedowns Stop a screen, take content off screens, and set what stopped screens show.
Install keys Make, change and revoke the keys screens join with.
Plays List plays as JSON or CSV, total them, and read a signed batch.
Uptime Uptime for the organisation, a site or a screen.
Monitoring Send telemetry to your own monitoring, and read it with a key.
Verify plays, batches and uptime Check Mestra’s signatures offline.
Webhooks Be told when a screen goes offline, has a problem, finishes a command, and more.