API reference
Starting a run
You can build a saved master’s sizes from your own code, with no design app open. A run can belong to a campaign, or to none: send campaignKey "no-campaign" and name the brands and sizes yourself. Agents can use the MCP op runs.start.
What you need
- A key with the Runs · Write permission. See Authentication.
- A saved master that is
ready. A master that is stillcheckingornot_readyis refused with409andnot_ready, with itsreasons. - For a campaign: its key. For no campaign: the codes of your brands (the
centres) and at least one size. - To read the brands and sizes you can pick from, Campaigns · Read. With a key that has Runs · Write or Designs · Write and Brand · Read,
GET /api/v1/campaigns/no-campaignalso works without it. It lists only brands and sizes.
Start a run for a campaign
curl -X POST https://app.withmestra.com/api/v1/masters/$MASTER_ID/runs \ -H "Authorization: Bearer $MESTRA_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "campaignKey": "spring-launch", "centres": ["ESP"], "formats": ["social-feed", "social-story"], "idempotencyKey": "6e1f0c2a-4b3d-4a57-9c8e-0d2b4f6a8c10" }'campaignKey: the campaign’s key.centres: brand codes. Left out, every brand of the campaign.formats: format keys from the campaign’s sizes: its format set’s and any formats it lists itself. Left out, all of them.idempotencyKey: a UUID you make. It is required unlessdryRunistrue. Send the same key with the same request and you get the run it made (200, no second run, no second charge). The same key with a different request is409idempotency_conflict.dryRun:truemakes and charges nothing. It answers200withsizes(what it would make),formats,skippedandreasons.
A started run answers 202:
{ "runId": "9b2e7a04-61c5-4f1d-8e3a-2c4d6f8a1b22", "jobs": [{ "jobId": "7d3a9c51e08b42f6", "centre": "ESP" }], "skipped": [{ "centre": "ESP", "format": "poster-a3", "reason": "Needs a design app" }]}A campaign no longer needs a format set. It can list its own formats, or none yet. A campaign with no sizes answers 409 with no_sizes and “This campaign has no sizes yet. Add sizes to the campaign.” Add sizes to the campaign (its formatSet and formats fields) and start again.
Start a run with no campaign
Send campaignKey "no-campaign". It isn’t a stored campaign. Every brand you name gets every size you name, from formats and customSizes together.
curl -X POST https://app.withmestra.com/api/v1/masters/$MASTER_ID/runs \ -H "Authorization: Bearer $MESTRA_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "campaignKey": "no-campaign", "centres": ["ESP", "NTH"], "formats": ["social-feed"], "customSizes": [{ "w": 300, "h": 250, "unit": "px" }], "idempotencyKey": "0f7b3d9e-2a64-4c18-b5e0-91d4a7c3e6f2" }'centresis required: the codes of your own brands.formatsare keys of your organisation’s own formats. They are all optional ifcustomSizeshas an entry.customSizesis a list of{"w", "h", "unit"}.unitispxormm(blank ispx). Each side is from 1 to 20,000. Each size is made a format of your organisation if it has none like it, and joinsformats.customSizesis only forno-campaign.- You need at least one size from
formatsandcustomSizestogether.
This request builds 2 brands by 2 sizes, 4 formats. The answer has the same shape as for a campaign run, one job for each brand. In GET /api/v1/runs and a run’s detail, the run’s campaignKey is no-campaign and campaignName is No campaign.
A run with no campaign can go to review and to motion. It can’t be published to screens: the publish call is refused with 409 and needs_campaign, “Screens need a campaign. Run this design in a campaign to publish it.”
Read the brands and sizes you can pick
GET /api/v1/campaigns/no-campaign answers the same shape as a campaign:
{ "campaign": { "key": "no-campaign", "name": "No campaign", "centres": ["ESP", "NTH"] }, "formats": [{ "key": "social-feed", "name": "Social feed", "width": 1080, "height": 1080, "unit": "px" }], "centres": [{ "code": "ESP", "name": "Eastpark" }]}centres lists every brand with its uploadedLogos, and formats every size your organisation has. There is no centreSizes or extraFormats: each brand gets each size.
Make a format for a typed size
POST /api/v1/formats/custom answers your organisation’s format for a width, height and unit, making one if there is none. It needs Campaigns · Write.
curl -X POST https://app.withmestra.com/api/v1/formats/custom \ -H "Authorization: Bearer $MESTRA_TOKEN" \ -H "Content-Type: application/json" \ -d '{"w": 300, "h": 250, "unit": "px"}'{ "key": "custom-300x250-px", "name": "300 × 250 px", "width": 300, "height": 250, "unit": "px" }wandhare each from 1 to 20,000.unitispxormm; blank ispx.- If your organisation already has a format with the same width, height and unit, you get its key (the lowest key if several match). A print format is never reused.
- Otherwise a format is made. Its key is
custom-<w>x<h>-<unit>(a decimal keeps its dot, for examplecustom-99.5x210-mm), with-2,-3and so on added if that key is a different size’s. Its name is<w> × <h> <unit>. A format in mm is made at 150 dpi. It reviews always and exportsindd,pngandjpg, with no bleed or safe margin. - A run’s
customSizesmakes these formats for you. Call this endpoint when you want the key first, for example to list the size in a campaign’sformats.
When it goes wrong
| You get | What to do |
|---|---|
400 with a field of idempotencyKey |
Send a UUID as idempotencyKey, unless dryRun is true. |
400 unknown_centre, field centres[i] |
A brand code isn’t one of your brands (with no-campaign), or isn’t in the campaign. Check the code. |
400 on centres |
With no-campaign, name at least one brand. |
400 unknown_format, field formats[i] |
The format key isn’t one of your formats. |
400 bad_custom_size, field customSizes[i] (or w, h), with min and max |
Use a unit of px or mm, and sides from 1 to 20,000. |
400 on customSizes |
customSizes is only for no-campaign. For a campaign, add the size to the campaign. |
400 no_sizes, “Choose at least one size.” |
With no-campaign, send at least one entry in formats or customSizes. |
409 no_sizes, “This campaign has no sizes yet. Add sizes to the campaign.” |
Add sizes to the campaign. |
409 not_ready |
The master isn’t ready. Read its reasons, then wait or fix it. |
409 nothing_to_make |
Every size would be skipped (print sizes, or brands without the fonts). Read skipped. Nothing is charged. |
409 needs_campaign |
Screens need a campaign. Run the master in a campaign to publish it. |
409 api_off |
An owner turns the API on in Developer > API and MCP. |
404 unknown campaign |
Check campaignKey. |
The full list of errors is in Errors, and every field is in the API reference.