Skip to content

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 still checking or not_ready is refused with 409 and not_ready, with its reasons.
  • 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-campaign also works without it. It lists only brands and sizes.

Start a run for a campaign

Shell
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 unless dryRun is true. 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 is 409 idempotency_conflict.
  • dryRun: true makes and charges nothing. It answers 200 with sizes (what it would make), formats, skipped and reasons.

A started run answers 202:

JSON
{
"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.

Shell
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"
}'
  • centres is required: the codes of your own brands.
  • formats are keys of your organisation’s own formats. They are all optional if customSizes has an entry.
  • customSizes is a list of {"w", "h", "unit"}. unit is px or mm (blank is px). Each side is from 1 to 20,000. Each size is made a format of your organisation if it has none like it, and joins formats. customSizes is only for no-campaign.
  • You need at least one size from formats and customSizes together.

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:

JSON
{
"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.

Shell
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"}'
JSON
{ "key": "custom-300x250-px", "name": "300 × 250 px", "width": 300, "height": 250, "unit": "px" }
  • w and h are each from 1 to 20,000. unit is px or mm; blank is px.
  • 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 example custom-99.5x210-mm), with -2, -3 and 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 exports indd, png and jpg, with no bleed or safe margin.
  • A run’s customSizes makes these formats for you. Call this endpoint when you want the key first, for example to list the size in a campaign’s formats.

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.