# Mestra Player API

The Mestra Player API: what it covers, permissions, roles, limited keys and the errors every call can return.

The Mestra Player API lets your own systems work with the screens that run [Mestra Player](https://withmestra.com/docs/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](https://withmestra.com/docs/api/), under **Mestra Player**. It uses the same base URL, keys, [errors](https://withmestra.com/docs/api/errors/) and [rate limits](https://withmestra.com/docs/api/#rate-limits) as the rest of the API, but its permissions and [webhook events](https://withmestra.com/docs/player/webhooks/) 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](https://withmestra.com/docs/mcp/tools/#mestra-player-screens) 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](https://withmestra.com/docs/player/).
- The API itself must be on. A call made while it is off answers `409` with the code `api_off`. See [Authentication](https://withmestra.com/docs/api/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](https://withmestra.com/docs/api/authentication/).

## 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](https://withmestra.com/docs/api/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](https://withmestra.com/docs/api/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](https://withmestra.com/docs/api/screens/#claimmestrascreen).

### 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](https://withmestra.com/docs/api/monitoring/).

## The reference

Every call is in the [API reference](https://withmestra.com/docs/api/), with its parameters, permission, errors and a request to copy.

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