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)RequiredThe master’s id.
namestringRequiredThe master’s name, as saved from the design app.
brandstringRequiredThe brand code.
sourceAppstringRequiredWhere the master was made: the design app it was saved from (
indesign,figma,canva),uploadfor one made from an uploaded file, ormestrafor one made in Mestra’s own editor.Possible values
indesignfigmacanvauploadmestramadeInMestrabooleanOptionalTrue 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.
statusstringRequiredchecking: still being checked;ready: can make runs;not_ready: seereasons.Possible values
checkingreadynot_readyreasonsarray of objectsRequiredWhy the master can’t make runs. Empty when it is ready.
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.
savedBystringRequiredThe saver’s name; empty when unknown.
runsintegerOptionalHow many server runs the master has had so far (the list only).
lastRunAtstring (date-time)OptionalWhen the latest run started; absent without any (the list only).
savedAtstring (date-time)RequiredWhen the master was last saved.
checkedAtstring (date-time)RequiredNullableWhen the check finished; null while it is still running.
pageWidthnumberRequiredThe page width of the design, in its own units.
pageHeightnumberRequiredThe page height of the design, in its own units.
sizeinteger (int64)RequiredThe composition’s and every file’s bytes.
replacedbooleanOptionalOnly on a save: true when it replaced the same document’s earlier save.
unchangedbooleanOptionalOnly on a save: true when the design matched the master’s latest version, so nothing was stored (
200).versionintegerOptionalThe version this save made, or on an unchanged save the version that matched, which is the latest.
Create a saved master
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
compositionstringRequiredRequired. The design as one JSON object: its
version, its pagewidthandheight, and itselements(text, images, vectors and shapes, each with anid). 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.metastringRequiredRequired. 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,figmaorcanva) andsnapshot(mimeimage/png, plus the picture’swidth,heightandsizein bytes). Send it as a text field, second.assetsstringRequiredRequired. A JSON array, up to 1 MB, with one entry per image or vector file you send:
elementId(the composition element it fills),kind(imageorvector),mime(image/svg+xmlfor a vector),width,height,sizein bytes andplacement(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.snapshotfileRequiredRequired. A PNG picture of the whole design, used as its preview, sent as a file part with exactly the
sizegiven inmeta.snapshot. At most 95 MB and 16 million pixels.assetsfileOptionalOne file part per entry in
assets, namedasset:<elementId>(for exampleasset:el-12), sent aftersnapshotin the same order asassets. Each must be exactly thesizeits 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
| Status | Code | Meaning |
|---|---|---|
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 | |
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
404 | headless_off |
|
409 | dont_keepbrand_changedname_takenapi_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
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
| 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 |
|
Update a saved master
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
compositionstringRequiredRequired. The design as one JSON object: its
version, its pagewidthandheight, and itselements(text, images, vectors and shapes, each with anid). 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.metastringRequiredRequired. 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,figmaorcanva) andsnapshot(mimeimage/png, plus the picture’swidth,heightandsizein bytes). Send it as a text field, second.assetsstringRequiredRequired. A JSON array, up to 1 MB, with one entry per image or vector file you send:
elementId(the composition element it fills),kind(imageorvector),mime(image/svg+xmlfor a vector),width,height,sizein bytes andplacement(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.snapshotfileRequiredRequired. A PNG picture of the whole design, used as its preview, sent as a file part with exactly the
sizegiven inmeta.snapshot. At most 95 MB and 16 million pixels.assetsfileOptionalOne file part per entry in
assets, namedasset:<elementId>(for exampleasset:el-12), sent aftersnapshotin the same order asassets. Each must be exactly thesizeits 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
| Status | Code | Meaning |
|---|---|---|
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 | |
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
404 | headless_off |
|
409 | dont_keepbrand_changedname_takenapi_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
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 objectsRequiredShow child attributesHide child attributes
idstring (uuid)RequiredThe master’s id.
namestringRequiredThe master’s name, as saved from the design app.
brandstringRequiredThe brand code.
sourceAppstringRequiredWhere the master was made: the design app it was saved from (
indesign,figma,canva),uploadfor one made from an uploaded file, ormestrafor one made in Mestra’s own editor.Possible values
indesignfigmacanvauploadmestramadeInMestrabooleanOptionalTrue 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.
statusstringRequiredchecking: still being checked;ready: can make runs;not_ready: seereasons.Possible values
checkingreadynot_readyreasonsarray of objectsRequiredWhy the master can’t make runs. Empty when it is ready.
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.
savedBystringRequiredThe saver’s name; empty when unknown.
runsintegerOptionalHow many server runs the master has had so far (the list only).
lastRunAtstring (date-time)OptionalWhen the latest run started; absent without any (the list only).
savedAtstring (date-time)RequiredWhen the master was last saved.
checkedAtstring (date-time)RequiredNullableWhen the check finished; null while it is still running.
pageWidthnumberRequiredThe page width of the design, in its own units.
pageHeightnumberRequiredThe page height of the design, in its own units.
sizeinteger (int64)RequiredThe composition’s and every file’s bytes.
replacedbooleanOptionalOnly on a save: true when it replaced the same document’s earlier save.
unchangedbooleanOptionalOnly on a save: true when the design matched the master’s latest version, so nothing was stored (
200).versionintegerOptionalThe version this save made, or on an unchanged save the version that matched, which is the latest.
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 |
|
Delete a saved master
Deletes the master and its files. Server runs already made keep their results.
Path parameters
idstring (uuid)Required
Returns
Deleted.
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 |
|