API reference
API reference

The Mestra API lets your own systems work with Mestra. It is organised around REST: predictable resource-oriented URLs, JSON in and out, and standard HTTP methods and status codes. Read your campaigns, formats, centres and runs, and, with the right key, change them. Save a master once and you can start runs of it from the API, with no design app open (see Server runs). To connect an AI agent instead, see MCP.
Screens that run Mestra Player are part of this reference, under Mestra Player below. Their permissions, limited keys and webhook events are covered in the Mestra Player API overview.
Base URL
https://app.withmestra.com/api/v1Turn it on
The API and the MCP server are included on every plan, and on for every organisation. An owner can turn it off in Developer > API and MCP; that revokes every key, and while it is off every call made with a key answers 409 with the code api_off. Make a key in the same place; see Authentication.
Your first call
List your campaigns:
curl https://app.withmestra.com/api/v1/campaigns \ -H "Authorization: Bearer $MESTRA_TOKEN"You get a JSON array, sorted by key. A 401 means the key is missing, unknown, expired or revoked. Every error is JSON with a code when a program should react to it; see Errors.
Rate limits
Each key, trusted workload or MCP connection may make 300 calls a minute, and at most 60 of them may change something (POST, PUT or DELETE). The limits hold across all our servers, and a workload or MCP connection keeps its count when its token is renewed. Every response carries X-RateLimit-Limit and X-RateLimit-Remaining. Past a limit you get 429 with the code rate_limited and a Retry-After header in seconds: wait that long, then carry on.
Some work has tighter limits of its own whatever the key, such as how many runs or uploads an organisation can have going at once. Those also answer 429 with Retry-After.
Paging
Lists that can grow take limit and offset. Runs and a master’s server runs page by default. The campaign list returns everything unless you send limit or offset; then it returns that page, and X-Total-Count says how many there are. Events page with a cursor.
OpenAPI
The whole reference is one OpenAPI 3.1 file, for generating your own client: download openapi.yaml.
Permissions
A key can only do what you let it, and a user key also keeps its owner’s role. Each call below shows the permission it needs, such as Runs · Read. A call the key doesn’t cover answers 403 with the code wrong_key.
Versioning
Everything here is version 1. We only add to v1: new endpoints, new optional fields, new values. A change that could break a caller goes into v2, and v1 keeps working. Read responses defensively and ignore fields you don’t know.
Resources
- Campaigns
A campaign is a brief: the copy, the dates, and the brands and formats to make. It points at a format set and one or more brands. Runs make a campaign’s artwork from a master, and reviews follow a campaign’s results.
- Formats
A format is one output size and its rules: width, height, bleed, safe margin, the smallest type allowed, and what must be kept or left out. Formats are grouped into format sets, and a campaign builds every format in its set.
- Format sets
A format set is a named group of formats, such as “Social launch”. A campaign names one format set, and each of its formats is built once for each brand.
- Brands
A site is a brand or site that campaigns run in: its colours, QR address and layout rules. Its logos are uploaded separately (see Logos). Every run is for one brand.
- Logos
A logo is a PNG or SVG file uploaded for a brand, as a primary or a reversed version. Runs use whichever stands out more on the artwork. Logos belong to brands.
- Saved masters
A saved master is a design kept in Mestra, saved once from InDesign, Figma or Canva, so that it can be built into sizes without opening the design app. A master has to be checked and
readybefore a server run can use it. - Server runs
A server run builds a campaign’s sizes from a saved master on Mestra’s servers, with no design app open. This is how you start a run from the API: save a master once, then start server runs from it. Runs started in InDesign, Figma or Canva are listed under App runs.
- App runs
An app run is one go at building a campaign’s formats for one brand, started from inside InDesign, Figma or Canva, with the design app doing the building. Each format has its own outcome and, if the organisation keeps its work, kept files. A server run’s builds are listed here too, with source
headless. To start a run from the API, see Server runs. - Library
The library keeps the finished files of runs, when an owner has turned it on and chosen how long to keep them (30, 90 or 365 days, or Keep everything, which has no time limit). Use it to download a run’s files after the fact.
- Reviews
A review is how a team or a client approves a campaign’s sizes for one brand. The campaign’s results are sent for review in rounds; each size is approved or sent back with comments. Exports collect the approved files.
- Usage
Usage shows what the organisation has used: the work done and the tokens it took, and the cloud storage its kept files take up. It never shows cost.
- Events
An event is a notice that something happened in the organisation: a run finished, a review was decided, billing was paused. The same events are sent to your webhook endpoints; these calls list them, so you can catch up after downtime.
Mestra Player
Screens that run Mestra Player are part of this reference. Start with the Mestra Player API overview for permissions, limited keys and the errors every call can return.
- Screens
A screen is a display running Mestra Player.
- Screen groups
A screen group is several screens that show one picture across them, such as a video wall, and is itself listed and changed as one screen. Make a group from screens that are already paired, then place it so that each screen knows its position; for a wall too big to play one video, give each position its own file. See Screen groups and video walls for the guide.
- Sites
A site is a place that screens are linked to, such as a shopping centre or a store. A site has its own time zone, on and off times, brightness and location, and a key can be limited to some sites.
- Scheduling
Scheduling puts content on screens. Add pictures, videos and HTML5 packages to the content library, then book them on screens, sites or groups for a date range. Bookings can be grouped into campaigns, and each booking can be sent live, retried or ended.
- Screen customers
A screen customer is an advertiser that bookings can name. A customer can set its own loop rules, and is listed with how many bookings and plays it has. A customer that is archived keeps its history and can be restored. See Customers for the guide.
- Loop
A screen’s loop is the playlist it repeats. Loop settings are the rules the loop is built under, and are set at three levels: for all screens, for a site, or for one screen. A setting that is not set means no rule. See Who plays when: customers and the loop for the guide.
- Screen commands
A command asks a screen to do something: take a screenshot, collect its logs, restart the player, download its content again or reboot the PC. The screen carries it out the next time it checks in, and the result is read here. Logs: the way to read and keep screen logs is the monitoring export over OTLP, to any OTLP destination; a log bundle is for a one-off pull. When a command finishes, the
screen.action_donewebhook says so; see Webhooks. - Stop and takedowns
Stopping a screen makes it show a stopped message instead of its content. A takedown stops screens, a site, every screen or one publication in one go, and records it so you can see when each screen has stopped. The settings here say what a stopped screen shows.
- Install keys
An install key is installed on new screens so that they join the organisation without showing a pairing code. One key installs any number of screens until it is revoked. The key’s value is shown once, when it is made. See Install and connect a screen for the guide.
- 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.
- Uptime
Uptime is how much of its counted time a screen was up. It is reported for all screens, for one site or for one screen, with a total and a trend a day at a time. See Monitoring for the guide.
- Monitoring
Monitoring sends the organisation’s own screen telemetry (OpenTelemetry metrics and events) to places it chooses, such as Datadog, New Relic, Honeycomb, Grafana Cloud, Elastic or any OTLP/HTTP endpoint. A destination holds the vendor’s key, sealed: it is never shown again. A telemetry read key lets the organisation’s own Prometheus, Grafana Alloy or monitoring agent pull the same metrics from
/api/v1/telemetry/metrics. The read key startsmtk_and is sent asAuthorization: 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 for Prometheus or Alloy. Seeing and testing destinations and the presets: an editor or an owner, with Screens · Read. Changing destinations and every telemetry key route: an owner, with Settings. See Monitoring for the guide.