API reference
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.
The Server run object
The server run object. It has one entry per brand and, in each, one per size.
Attributes
runIdstring (uuid)RequiredThe run’s id.
statusstringRequiredqueued,running,done,failedorcancelled.Possible values
queuedrunningdonefailedcancelledmasterIdstringRequiredThe saved master; empty when it was deleted while the run existed.
campaignKeystringRequiredThe campaign the run makes sizes for;
no-campaignfor a run that belongs to none.campaignNamestringOptionalOnly on a run with no campaign:
No campaign, the name to show forno-campaign.reasonstringOptionalOnly on a failed run: why, in a fixed line (the master’s own reason when it changed,
The master was deleted., orThe run couldn't be completed. Run it again.). The sizes that were still open read the same line.sitesarray of objectsRequiredOne entry per brand, in the order asked for.
Show child attributesHide child attributes
sitestringRequiredThe brand.
jobIdstringRequiredThe id of the brand’s run (16 hex characters).
sizesarray of objectsRequiredOne entry per format, in the order asked for.
Show child attributesHide child attributes
formatstringRequiredThe format key.
statusstringRequiredqueued,building,reviewing,done,failedorskipped.Possible values
queuedbuildingreviewingdonefailedskippedreasonstringOptionalWhy a size is skipped or failed (
Needs a design app,Add font: <family>,Cancelled, …). A size left out for one brand is skipped withnot-for-site(the brand’s size list doesn’t have it) orunknown-format(no such size is defined).linksobjectOptionalOnly on a size that is done.
Show child attributesHide child attributes
jobstringRequiredThe brand’s run,
/jobs/{jobId}.filesstringRequiredThe brand’s kept files as a zip,
/library/runs/{jobId}.zip.
Start a server run
Builds a campaign’s sizes from a saved master on Mestra’s servers, one run per brand. Only a ready master can run; one that is checking or not_ready is refused with 409 not_ready and its reasons. A site that is not marked as a Studio brand (one Mestra Network staff added) is refused with 409 not_studio_brand: Mark this site as a Studio brand to use it in Studio.
Print sizes and sizes of a brand whose fonts are missing are not built: they come back in skipped with a reason (Needs a design app, Add font: <family>). Each size that will be built counts as a size made.
idempotencyKey (a UUID) is required unless dryRun is true. Sending the same key with the same request returns the run it made (200, no second run, no second charge); the same key with a different request is 409 idempotency_conflict. Keys are per organisation. dryRun: true creates and charges nothing: it answers 200 with sizes (the sizes it would make), credits, formats (per format: its sizes and, when none, why), skipped and reasons.
Path parameters
idstring (uuid)RequiredThe saved master to run.
Body parameters
campaignKeystringRequiredThe campaign to make sizes for, or
no-campaignfor a run that belongs to none (thensitesis required and every chosen brand gets every chosen size).sitesarray of stringsOptionalSite codes in the campaign. Defaults to all of the campaign’s brands. Required with
campaignKeyno-campaign: the organisation’s own brands (400unknown_site, fieldsites[i]; none named is400onsites).formatsarray of stringsOptionalFormat keys in the campaign’s sizes (its format set and its own
formats). Defaults to all of them. WithcampaignKeyno-campaignthe organisation’s own format keys (400unknown_format, fieldformats[i]).customSizesarray of objectsOptionalOnly with
campaignKeyno-campaign: typed sizes,[{"w": 300, "h": 250, "unit": "px"}](pxormm, each side 1 to 20000). Each is made a format of the organisation if it has none like it (asPOST /formats/customdoes) and joinsformats.400bad_custom_size(fieldcustomSizes[i]) for a size that isn’t valid, and400oncustomSizeswith a real campaign. A no-campaign run needs at least one size fromformatsandcustomSizestogether (400no_sizes,Choose at least one size.).Show child attributesHide child attributes
wnumberRequiredhnumberRequiredunitstringOptionalPossible values
pxmm
idempotencyKeystring (uuid)OptionalRequired unless
dryRunis true.dryRunbooleanOptionalAnswer what a run would make and cost; create nothing.
choiceobjectOptionalPicks the copy and colourway from the campaign’s approved rules:
copy(role to one of the listed values) andcolourway(a listed name). Omit it to take the default. A differentchoiceunder a repeatedidempotencyKeyis409 idempotency_conflict.400(fieldchoice) when the campaign has no approved rules or a value is not listed.
Returns
A dry run’s estimate, or a repeat of a run already made under the key.
An object with:
runIdstring (uuid)OptionalThe run’s id. Absent on a dry run.
jobsarray of objectsRequiredOne entry per brand the run makes sizes for, each with the id of that brand’s run. Empty on a dry run.
Show child attributesHide child attributes
jobIdstringRequiredThe id of the brand’s run (16 hex characters).
sitestringRequiredThe brand the run is for.
skippedarray of objectsRequiredSizes that will not be made, each with a reason.
Show child attributesHide child attributes
sitestringRequiredThe brand the size would have been for.
formatstringRequiredThe format that is skipped.
reasonstringRequiredNeeds a design apporAdd font: <family> <style>(for exampleAdd font: Jost Bold).
sizesintegerOptionalDry run only: how many sizes the run will make (every brand’s sizes that are not skipped, the sample brand’s included).
creditsintegerOptionalDry run only: what those sizes cost in billable credits (0 on plans that bill none).
formatsarray of objectsOptionalDry run only: for each format the run could make, how many sizes it makes of it and, when it makes none, why.
Show child attributesHide child attributes
formatstringRequiredThe format key.
sizesintegerRequiredSizes of it the run makes: one for each brand that gets the format and can have it made on the server.
skippedstringOptionalPresent when
sizesis 0: why (Needs a design apporAdd font: <family> <style>). A format withNeeds a design appis made in the design app, so a caller should not ask for it here.
reasonsarray of objectsOptionalDry run only: why the master can’t run (empty when it can).
Show child attributesHide child attributes
codestringRequiredA short code:
font,artwork,snapshot,invalidorresave.elementstringOptionalThe composition element the reason is about, when it is about one.
textstringRequiredWhat to do, as the apps and the web show it (
Add font: Jost Bold).familystringOptionalA
fontreason: the family to add, apart from the style intext.
Errors
| Status | Code | Meaning |
|---|---|---|
400 | unknown_siteunknown_formatbad_custom_sizeno_sizes |
|
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
404 | headless_off |
|
409 | not_readyno_sizesnothing_to_makedont_keepidempotency_conflictapi_off |
|
501 | Runs need the render service, which this server doesn’t have. |
Retrieve a server run
Returns the run and the status of each size: queued, building, reviewing, done, failed (with a reason) or skipped. A finished size has links to its run and its files. Poll this until status is done, failed or cancelled. A run of another organisation is a 404.
Path parameters
runIdstring (uuid)Required
Returns
The run.
Returns the Server run object.
Errors
| Status | Code | Meaning |
|---|---|---|
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | “Your role (<role>) can’t <action>.” (the role is below the route’s minimum) or “Choose an organisation first.” (the session has no organisation). | |
404 | headless_off |
|
409 | api_off |
|
List all server runs for a master
Returns the master’s latest server runs, newest first: 10 unless you send limit (up to 200), and offset for the next page. Each has the same fields as Retrieve a server run, plus createdAt and images: for every site and format with a kept thumbnail, its thumbId and, when kept, the PNG or JPG fileId. Fetch either with Download a kept file. An unknown master gives an empty list.
Path parameters
idstring (uuid)RequiredThe saved master to run.
Query parameters
limitintegerOptional1 to 200.
Default
10offsetintegerOptionalDefault
0
Returns
The runs.
An object with:
runsarray of objectsRequiredShow child attributesHide child attributes
runIdstringOptionalstatusstringOptionalcampaignKeystringOptionalcreatedAtstring (date-time)OptionalversionintegerOptionalNullableThe master version the run is pinned to; null when unpinned.
sitesarray of objectsOptionalimagesarray of objectsOptionalShow child attributesHide child attributes
sitestringOptionaljobIdstringOptionalformatstringOptionalthumbIdstringOptionalfileIdstringOptional
Errors
| Status | Code | Meaning |
|---|---|---|
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | “Your role (<role>) can’t <action>.” (the role is below the route’s minimum) or “Choose an organisation first.” (the session has no organisation). | |
409 | api_off |
|
Cancel a server run
Stops a queued or running server run. It then reads cancelled, its open sizes read failed with the reason Cancelled, and sizes already built stay. Cancelling a run that is already cancelled answers 204 again.
Path parameters
runIdstring (uuid)Required
Returns
Cancelled (or already cancelled).
Errors
| Status | Code | Meaning |
|---|---|---|
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
404 | headless_off |
|
409 | api_off | “That run has already finished.” (done or failed). With an API key, |