Skip to content

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)Required

    The run’s id.

  • statusstringRequired

    queued, running, done, failed or cancelled.

    Possible valuesqueuedrunningdonefailedcancelled

  • masterIdstringRequired

    The saved master; empty when it was deleted while the run existed.

  • campaignKeystringRequired

    The campaign the run makes sizes for; no-campaign for a run that belongs to none.

  • campaignNamestringOptional

    Only on a run with no campaign: No campaign, the name to show for no-campaign.

  • reasonstringOptional

    Only on a failed run: why, in a fixed line (the master’s own reason when it changed, The master was deleted., or The run couldn't be completed. Run it again.). The sizes that were still open read the same line.

  • sitesarray of objectsRequired

    One entry per brand, in the order asked for.

    Show child attributesHide child attributes
    • sitestringRequired

      The brand.

    • jobIdstringRequired

      The id of the brand’s run (16 hex characters).

    • sizesarray of objectsRequired

      One entry per format, in the order asked for.

      Show child attributesHide child attributes
      • formatstringRequired

        The format key.

      • statusstringRequired

        queued, building, reviewing, done, failed or skipped.

        Possible valuesqueuedbuildingreviewingdonefailedskipped

      • reasonstringOptional

        Why a size is skipped or failed (Needs a design app, Add font: <family>, Cancelled, …). A size left out for one brand is skipped with not-for-site (the brand’s size list doesn’t have it) or unknown-format (no such size is defined).

      • linksobjectOptional

        Only on a size that is done.

        Show child attributesHide child attributes
        • jobstringRequired

          The brand’s run, /jobs/{jobId}.

        • filesstringRequired

          The brand’s kept files as a zip, /library/runs/{jobId}.zip.

Start a server run

PermissionRuns · Write

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)Required

    The saved master to run.

Body parameters

  • campaignKeystringRequired

    The campaign to make sizes for, or no-campaign for a run that belongs to none (then sites is required and every chosen brand gets every chosen size).

  • sitesarray of stringsOptional

    Site codes in the campaign. Defaults to all of the campaign’s brands. Required with campaignKey no-campaign: the organisation’s own brands (400 unknown_site, field sites[i]; none named is 400 on sites).

  • formatsarray of stringsOptional

    Format keys in the campaign’s sizes (its format set and its own formats). Defaults to all of them. With campaignKey no-campaign the organisation’s own format keys (400 unknown_format, field formats[i]).

  • customSizesarray of objectsOptional

    Only with campaignKey no-campaign: typed sizes, [{"w": 300, "h": 250, "unit": "px"}] (px or mm, each side 1 to 20000). Each is made a format of the organisation if it has none like it (as POST /formats/custom does) and joins formats. 400 bad_custom_size (field customSizes[i]) for a size that isn’t valid, and 400 on customSizes with a real campaign. A no-campaign run needs at least one size from formats and customSizes together (400 no_sizes, Choose at least one size.).

    Show child attributesHide child attributes
    • wnumberRequired
    • hnumberRequired
    • unitstringOptional

      Possible valuespxmm

  • idempotencyKeystring (uuid)Optional

    Required unless dryRun is true.

  • dryRunbooleanOptional

    Answer what a run would make and cost; create nothing.

  • choiceobjectOptional

    Picks the copy and colourway from the campaign’s approved rules: copy (role to one of the listed values) and colourway (a listed name). Omit it to take the default. A different choice under a repeated idempotencyKey is 409 idempotency_conflict. 400 (field choice) 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)Optional

    The run’s id. Absent on a dry run.

  • jobsarray of objectsRequired

    One 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
    • jobIdstringRequired

      The id of the brand’s run (16 hex characters).

    • sitestringRequired

      The brand the run is for.

  • skippedarray of objectsRequired

    Sizes that will not be made, each with a reason.

    Show child attributesHide child attributes
    • sitestringRequired

      The brand the size would have been for.

    • formatstringRequired

      The format that is skipped.

    • reasonstringRequired

      Needs a design app or Add font: <family> <style> (for example Add font: Jost Bold).

  • sizesintegerOptional

    Dry run only: how many sizes the run will make (every brand’s sizes that are not skipped, the sample brand’s included).

  • creditsintegerOptional

    Dry run only: what those sizes cost in billable credits (0 on plans that bill none).

  • formatsarray of objectsOptional

    Dry 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
    • formatstringRequired

      The format key.

    • sizesintegerRequired

      Sizes of it the run makes: one for each brand that gets the format and can have it made on the server.

    • skippedstringOptional

      Present when sizes is 0: why (Needs a design app or Add font: <family> <style>). A format with Needs a design app is made in the design app, so a caller should not ask for it here.

  • reasonsarray of objectsOptional

    Dry run only: why the master can’t run (empty when it can).

    Show child attributesHide child attributes
    • codestringRequired

      A short code: font, artwork, snapshot, invalid or resave.

    • elementstringOptional

      The composition element the reason is about, when it is about one.

    • textstringRequired

      What to do, as the apps and the web show it (Add font: Jost Bold).

    • familystringOptional

      A font reason: the family to add, apart from the style in text.

Errors

StatusCodeMeaning
400unknown_siteunknown_formatbad_custom_sizeno_sizes

idempotencyKey missing or not a UUID (a field error), a brand named twice, a brand not in the campaign, or formats outside the campaign’s sizes. With campaignKey no-campaign, field errors (field names the entry): unknown_site, unknown_format, bad_custom_size (with min and max), no_sizes (“Choose at least one size.”) and no brand named; customSizes with a real campaign is refused (field customSizes).

401invalid_token

The key is missing, unknown, revoked or expired (code invalid_token). Send it as Authorization: Bearer <key>.

403wrong_key

403 for a role below the route’s minimum (“Your role (<role>) can’t <action>.”, or “Choose an organisation first.”), or, for an API key without the permission this call needs, code wrong_key with “This key needs the <Area> · <Read|Write> permission.” (for example “This key needs the Reviews · Write permission.”), or “This key can’t do that.” for a call only the Mestra apps make.

404headless_off

headless_off, “That master isn’t here any more.” or “unknown campaign”.

409not_readyno_sizesnothing_to_makedont_keepidempotency_conflictapi_off

not_ready (with reasons), no_sizes (a real campaign has no sizes yet: “This campaign has no sizes yet. Add sizes to the campaign.”), nothing_to_make (every size would be skipped: print sizes, or sites without the fonts; with the skipped list; no run is made and nothing is charged; a dryRun reports the same skips with a 200 instead), dont_keep (the library doesn’t keep work), idempotency_conflict, or a billing refusal with its code (trial sizes used up, trial ended, and so on). With an API key, api_off (“Turn on the API in Developer → API and MCP first.”) when an owner has turned the API off.

501

Runs need the render service, which this server doesn’t have.

Retrieve a server run

PermissionRuns · Read

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

StatusCodeMeaning
401invalid_token

The key is missing, unknown, revoked or expired (code invalid_token). Send it as Authorization: Bearer <key>.

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).

404headless_off

headless_off, or no such run in this organisation.

409api_off

409 with code api_off (“Turn on the API in Developer → API and MCP first.”): an owner hasn’t turned the API on for this organisation, so no API key works yet. An owner turns it on in Settings, then API.

List all server runs for a master

PermissionRuns · Read

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)Required

    The saved master to run.

Query parameters

  • limitintegerOptional

    1 to 200.

    Default10

  • offsetintegerOptional

    Default0

Returns

The runs.

An object with:

  • runsarray of objectsRequired
    Show child attributesHide child attributes
    • runIdstringOptional
    • statusstringOptional
    • campaignKeystringOptional
    • createdAtstring (date-time)Optional
    • versionintegerOptionalNullable

      The master version the run is pinned to; null when unpinned.

    • sitesarray of objectsOptional
    • imagesarray of objectsOptional
      Show child attributesHide child attributes
      • sitestringOptional
      • jobIdstringOptional
      • formatstringOptional
      • thumbIdstringOptional
      • fileIdstringOptional

Errors

StatusCodeMeaning
401invalid_token

The key is missing, unknown, revoked or expired (code invalid_token). Send it as Authorization: Bearer <key>.

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).

409api_off

409 with code api_off (“Turn on the API in Developer → API and MCP first.”): an owner hasn’t turned the API on for this organisation, so no API key works yet. An owner turns it on in Settings, then API.

Cancel a server run

PermissionRuns · Write

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

StatusCodeMeaning
401invalid_token

The key is missing, unknown, revoked or expired (code invalid_token). Send it as Authorization: Bearer <key>.

403wrong_key

403 for a role below the route’s minimum (“Your role (<role>) can’t <action>.”, or “Choose an organisation first.”), or, for an API key without the permission this call needs, code wrong_key with “This key needs the <Area> · <Read|Write> permission.” (for example “This key needs the Reviews · Write permission.”), or “This key can’t do that.” for a call only the Mestra apps make.

404headless_off

headless_off, or “no such run” in this organisation.

409api_off

“That run has already finished.” (done or failed). With an API key, api_off (“Turn on the API in Developer → API and MCP first.”) when an owner has turned the API off.