Skip to content

API reference

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 ready before a server run can use it.

The Saved master object

The saved master object. Its status says whether it can make server runs.

Attributes

  • idstring (uuid)Required

    The master’s id.

  • namestringRequired

    The master’s name, as saved from the design app.

  • brandstringRequired

    The brand code.

  • sourceAppstringRequired

    Where the master was made: the design app it was saved from (indesign, figma, canva), upload for one made from an uploaded file, or mestra for one made in Mestra’s own editor.

    Possible valuesindesignfigmacanvauploadmestra

  • madeInMestrabooleanOptional

    True when any version of the master was made in Mestra’s own editor, so a design app can open it. Stays true after a design app saves a later version.

  • statusstringRequired

    checking: still being checked; ready: can make runs; not_ready: see reasons.

    Possible valuescheckingreadynot_ready

  • reasonsarray of objectsRequired

    Why the master can’t make runs. Empty when it is ready.

    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.

  • savedBystringRequired

    The saver’s name; empty when unknown.

  • runsintegerOptional

    How many server runs the master has had so far (the list only).

  • lastRunAtstring (date-time)Optional

    When the latest run started; absent without any (the list only).

  • savedAtstring (date-time)Required

    When the master was last saved.

  • checkedAtstring (date-time)RequiredNullable

    When the check finished; null while it is still running.

  • pageWidthnumberRequired

    The page width of the design, in its own units.

  • pageHeightnumberRequired

    The page height of the design, in its own units.

  • sizeinteger (int64)Required

    The composition’s and every file’s bytes.

  • replacedbooleanOptional

    Only on a save: true when it replaced the same document’s earlier save.

  • unchangedbooleanOptional

    Only on a save: true when the design matched the master’s latest version, so nothing was stored (200).

  • versionintegerOptional

    The version this save made, or on an unchanged save the version that matched, which is the latest.

Create a saved master

PermissionRuns · Write

Saves a design from a design app so that server runs can build from it. Saving a document that was already saved replaces that master in place (200, replaced: true) and it is checked again; a new master is 201. The organisation must keep its work, or the request is refused with 409 dont_keep. Send the parts in the order shown in the request body.

Body parameters

  • compositionstringRequired

    Required. The design as one JSON object: its version, its page width and height, and its elements (text, images, vectors and shapes, each with an id). Up to 2,000,000 bytes; the request is refused if it isn’t a valid composition. Send it as a text field, before every other part.

  • metastringRequired

    Required. A JSON object, up to 16 KB, describing the save: name (up to 200 characters), docKey (up to 512 characters; your stable id for the source document, which is how a second save finds the master to replace), site (a brand on your account), sourceApp (indesign, figma or canva) and snapshot (mime image/png, plus the picture’s width, height and size in bytes). Send it as a text field, second.

  • assetsstringRequired

    Required. A JSON array, up to 1 MB, with one entry per image or vector file you send: elementId (the composition element it fills), kind (image or vector), mime (image/svg+xml for a vector), width, height, size in bytes and placement (a small JSON object, or null). Each element appears at most once; send [] if the design has no pictures. Send it as a text field, third.

  • snapshotfileRequired

    Required. A PNG picture of the whole design, used as its preview, sent as a file part with exactly the size given in meta.snapshot. At most 95 MB and 16 million pixels.

  • assetsfileOptional

    One file part per entry in assets, named asset:<elementId> (for example asset:el-12), sent after snapshot in the same order as assets. Each must be exactly the size its entry gives, at most 95 MB and 40 million pixels; vectors are SVG files and pictures are PNG, JPEG or WebP.

Returns

Replaced in place.

Returns the Saved master object.

Errors

StatusCodeMeaning
400

“That master couldn’t be read. Save it again.” (a part is missing, repeated, out of order or not what it says, an SVG that isn’t plain, or not a composition) or a field error on site.

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 (saved masters aren’t on for this server, or for this organisation), or “That master isn’t here any more.” (unknown or another organisation’s).

409dont_keepbrand_changedname_takenapi_off

dont_keep: “Saving masters needs the library to keep files. Choose how long to keep work in Settings.”; busy: “That master is being saved. Try again.”; brand_changed: “This document is already saved for another brand.”; or name_taken: “A master with that name is already saved for this brand.” with master (id, name) of the one that holds the name; only when the request sends savedHow. Answer with onClash. With an API key, api_off (“Turn on the API in Developer → API and MCP first.”) when an owner has turned the API off.

411

“Send the master’s size (Content-Length).”

413

“That master is too large to keep.” or a part over its limit.

429

“Too many uploads at once. Try again shortly.”

507

“Your organisation’s cloud storage is full.”

Retrieve a saved master

PermissionRuns · Read

Returns the master, including whether it is checking, ready or not_ready and, if not ready, reasons. A master of another organisation is a 404.

Path parameters

  • idstring (uuid)Required

Returns

The master.

Returns the Saved master 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 (saved masters aren’t on for this server, or for this organisation), or “That master isn’t here any more.” (unknown or another organisation’s).

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.

Update a saved master

PermissionRuns · Write

Saves the master again, replacing it in place. meta.docKey must be the master’s own, or the request is refused with 400. The parts and answers are the same as Create a saved master.

Path parameters

  • idstring (uuid)Required

Body parameters

  • compositionstringRequired

    Required. The design as one JSON object: its version, its page width and height, and its elements (text, images, vectors and shapes, each with an id). Up to 2,000,000 bytes; the request is refused if it isn’t a valid composition. Send it as a text field, before every other part.

  • metastringRequired

    Required. A JSON object, up to 16 KB, describing the save: name (up to 200 characters), docKey (up to 512 characters; your stable id for the source document, which is how a second save finds the master to replace), site (a brand on your account), sourceApp (indesign, figma or canva) and snapshot (mime image/png, plus the picture’s width, height and size in bytes). Send it as a text field, second.

  • assetsstringRequired

    Required. A JSON array, up to 1 MB, with one entry per image or vector file you send: elementId (the composition element it fills), kind (image or vector), mime (image/svg+xml for a vector), width, height, size in bytes and placement (a small JSON object, or null). Each element appears at most once; send [] if the design has no pictures. Send it as a text field, third.

  • snapshotfileRequired

    Required. A PNG picture of the whole design, used as its preview, sent as a file part with exactly the size given in meta.snapshot. At most 95 MB and 16 million pixels.

  • assetsfileOptional

    One file part per entry in assets, named asset:<elementId> (for example asset:el-12), sent after snapshot in the same order as assets. Each must be exactly the size its entry gives, at most 95 MB and 40 million pixels; vectors are SVG files and pictures are PNG, JPEG or WebP.

Returns

Replaced in place.

Returns the Saved master object.

Errors

StatusCodeMeaning
400

“That master couldn’t be read. Save it again.” (a part is missing, repeated, out of order or not what it says, an SVG that isn’t plain, or not a composition) or a field error on site.

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 (saved masters aren’t on for this server, or for this organisation), or “That master isn’t here any more.” (unknown or another organisation’s).

409dont_keepbrand_changedname_takenapi_off

dont_keep: “Saving masters needs the library to keep files. Choose how long to keep work in Settings.”; busy: “That master is being saved. Try again.”; brand_changed: “This document is already saved for another brand.”; or name_taken: “A master with that name is already saved for this brand.” with master (id, name) of the one that holds the name; only when the request sends savedHow. Answer with onClash. With an API key, api_off (“Turn on the API in Developer → API and MCP first.”) when an owner has turned the API off.

411

“Send the master’s size (Content-Length).”

413

“That master is too large to keep.” or a part over its limit.

429

“Too many uploads at once. Try again shortly.”

507

“Your organisation’s cloud storage is full.”

List all saved masters

PermissionRuns · Read

Returns the organisation’s saved masters, newest save first, each with its readiness status and, if it isn’t ready, the reasons.

Returns

The masters.

An object with:

  • mastersarray of objectsRequired
    Show child attributesHide child attributes
    • idstring (uuid)Required

      The master’s id.

    • namestringRequired

      The master’s name, as saved from the design app.

    • brandstringRequired

      The brand code.

    • sourceAppstringRequired

      Where the master was made: the design app it was saved from (indesign, figma, canva), upload for one made from an uploaded file, or mestra for one made in Mestra’s own editor.

      Possible valuesindesignfigmacanvauploadmestra

    • madeInMestrabooleanOptional

      True when any version of the master was made in Mestra’s own editor, so a design app can open it. Stays true after a design app saves a later version.

    • statusstringRequired

      checking: still being checked; ready: can make runs; not_ready: see reasons.

      Possible valuescheckingreadynot_ready

    • reasonsarray of objectsRequired

      Why the master can’t make runs. Empty when it is ready.

      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.

    • savedBystringRequired

      The saver’s name; empty when unknown.

    • runsintegerOptional

      How many server runs the master has had so far (the list only).

    • lastRunAtstring (date-time)Optional

      When the latest run started; absent without any (the list only).

    • savedAtstring (date-time)Required

      When the master was last saved.

    • checkedAtstring (date-time)RequiredNullable

      When the check finished; null while it is still running.

    • pageWidthnumberRequired

      The page width of the design, in its own units.

    • pageHeightnumberRequired

      The page height of the design, in its own units.

    • sizeinteger (int64)Required

      The composition’s and every file’s bytes.

    • replacedbooleanOptional

      Only on a save: true when it replaced the same document’s earlier save.

    • unchangedbooleanOptional

      Only on a save: true when the design matched the master’s latest version, so nothing was stored (200).

    • versionintegerOptional

      The version this save made, or on an unchanged save the version that matched, which is the latest.

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: saved masters aren’t on for this server, or for 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.

Delete a saved master

PermissionRuns · Write

Deletes the master and its files. Server runs already made keep their results.

Path parameters

  • idstring (uuid)Required

Returns

Deleted.

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 (saved masters aren’t on for this server, or for this organisation), or “That master isn’t here any more.” (unknown or another organisation’s).

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.