API reference
Library
The library keeps the finished files of runs, when an owner has turned it on and chosen how long to keep them (30, 90 or 365 days, or Keep everything, which has no time limit). Use it to download a run’s files after the fact.
The Library run object
The library run object is a run summary plus what the library has kept for it.
Attributes
idstringRequiredThe run’s id (16 hex characters).
campaignKeystringRequiredThe campaign the run was for.
siteCodestringRequiredThe brand the run was for.
statusstringRequiredPossible values
planningplannedfailedcancelledsourcestringRequiredThe app the run came from;
headlessfor a run made on the server from a saved master.Possible values
indesignfigmacanvaheadlesscreatedBystringOptionalThe creating user’s id; omitted when unknown.
createdByNamestringRequiredThe member’s name; “Member” when they have none, or “Canva user” on a Canva run; “Removed member” when they have left (or no creator was recorded). Never an email.
createdAtstring (date-time)RequiredWhen the run started.
runIdstringOptionalThe run this belongs to; brands started together share it. Omitted when there is none.
appVersionstringOptionalThe app build the run came from; omitted when unknown.
formatCountsobjectRequiredThe run’s formats, each counted once - failed, else flagged (any flag), else built.
Show child attributesHide child attributes
builtintegerRequiredFormats made with no flags.
flaggedintegerRequiredFormats made, but with at least one flag worth a look.
failedintegerRequiredFormats that could not be made.
hasFilesbooleanRequiredThe library keeps files (not just a thumbnail) for the run.
notesintegerRequiredHow many issues and distinct flags (element flags once per code) the run’s kept review notes hold, across its formats.
brandsarray of stringsOptionalWith
grouped=1: the brand codes of the run’s brands.jobIdsarray of stringsOptionalWith
grouped=1: the ids of the run’s brands, by brand code.filesintegerRequiredKept files, not thumbnails.
bytesintegerRequiredTheir size, not thumbnails.
keptUntilstring (date-time)RequiredNullableWhen the first of them expires; null under Keep everything.
thumbsarray of objectsRequiredA thumbnail for each format that has one.
Show child attributesHide child attributes
formatKeystringRequiredThe format the thumbnail shows.
idstring (uuid)RequiredThe thumbnail’s file id: fetch it with
GET /library/files/{id}.
sourceLinkobjectOptionalWhere a Canva or Figma run’s work lives, until it expires with the run’s files.
Show child attributesHide child attributes
appstringRequiredcanvaorfigma: the app the run was made in.Possible values
canvafigmaurlstring (uri)RequiredA link to the work in that app.
expiresAtstring (date-time)RequiredNullableWhen the link stops being kept; null under Keep everything.
List all library runs
Returns the runs whose finished files the organisation has kept, newest first. It takes the same filters as List all runs. Only runs with at least one kept file (not just a thumbnail) are listed.
Query parameters
campaignstringOptionalFilter by campaign key.
sitestringOptionalFilter by brand code.
statusstringOptionalPossible values
planningplannedfailedcancelledsourcestringOptionalFilter by the app the run came from (
headlessfor a run made on the server).Possible values
indesignfigmacanvaheadlessoutcomestringOptionalAs
/jobs’ outcome.Possible values
builtflaggedfailedfromstring (date)OptionalFirst UTC day the run was started, inclusive.
tostring (date)OptionalLast UTC day the run was started, inclusive.
limitintegerOptional1 to 200.
Default
50offsetintegerOptionalDefault
0
Returns
The runs, and how many match in all.
An object with:
runsarray of objectsRequiredShow child attributesHide child attributes
idstringRequiredThe run’s id (16 hex characters).
campaignKeystringRequiredThe campaign the run was for.
siteCodestringRequiredThe brand the run was for.
statusstringRequiredPossible values
planningplannedfailedcancelledsourcestringRequiredThe app the run came from;
headlessfor a run made on the server from a saved master.Possible values
indesignfigmacanvaheadlesscreatedBystringOptionalThe creating user’s id; omitted when unknown.
createdByNamestringRequiredThe member’s name; “Member” when they have none, or “Canva user” on a Canva run; “Removed member” when they have left (or no creator was recorded). Never an email.
createdAtstring (date-time)RequiredWhen the run started.
runIdstringOptionalThe run this belongs to; brands started together share it. Omitted when there is none.
appVersionstringOptionalThe app build the run came from; omitted when unknown.
formatCountsobjectRequiredThe run’s formats, each counted once - failed, else flagged (any flag), else built.
Show child attributesHide child attributes
builtintegerRequiredFormats made with no flags.
flaggedintegerRequiredFormats made, but with at least one flag worth a look.
failedintegerRequiredFormats that could not be made.
hasFilesbooleanRequiredThe library keeps files (not just a thumbnail) for the run.
notesintegerRequiredHow many issues and distinct flags (element flags once per code) the run’s kept review notes hold, across its formats.
brandsarray of stringsOptionalWith
grouped=1: the brand codes of the run’s brands.jobIdsarray of stringsOptionalWith
grouped=1: the ids of the run’s brands, by brand code.filesintegerRequiredKept files, not thumbnails.
bytesintegerRequiredTheir size, not thumbnails.
keptUntilstring (date-time)RequiredNullableWhen the first of them expires; null under Keep everything.
thumbsarray of objectsRequiredA thumbnail for each format that has one.
Show child attributesHide child attributes
formatKeystringRequiredThe format the thumbnail shows.
idstring (uuid)RequiredThe thumbnail’s file id: fetch it with
GET /library/files/{id}.
sourceLinkobjectOptionalWhere a Canva or Figma run’s work lives, until it expires with the run’s files.
Show child attributesHide child attributes
appstringRequiredcanvaorfigma: the app the run was made in.Possible values
canvafigmaurlstring (uri)RequiredA link to the work in that app.
expiresAtstring (date-time)RequiredNullableWhen the link stops being kept; null under Keep everything.
totalintegerRequiredEvery run the filters match, limit and offset aside.
Errors
| Status | Code | Meaning |
|---|---|---|
400 | As | |
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 |
|
500 | “could not list jobs”, “could not read the library” or “could not check token”. | |
501 | “The library isn’t set up on this server.” |
Download a kept file
Downloads one kept file as an attachment, in the type it was saved in. It is never cached. Add ?thumb=1 to show a run’s thumbnail inline instead. A file that can’t be read part-way ends the connection, so you never receive a truncated file that looks complete.
Path parameters
idstring (uuid)RequiredThe kept file’s id. A file of another organisation is a
404.
Query parameters
thumbstringOptional1: the file is a format’s thumbnail, to show inline; any other file is404.Possible values
1
Returns
The file’s bytes.
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 | “That file isn’t in the library.” (including another organisation’s, an expired one, and a file whose stored object is gone). | |
409 | api_off |
|
500 | “could not read the library” or “could not check token”. | |
501 | “The library isn’t set up on this server.” |
Download a run's kept files
Downloads all of a run’s kept files in one zip, each as <format>/<name>. Images and PDFs are stored as they are; SVGs and InDesign documents are compressed. A file deleted since the zip began is left out; one that can’t be read part-way ends the connection.
Path parameters
jobIdstringRequiredThe id of the server run’s run for one brand (16 hex characters).
Returns
The zip.
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 | “No files are kept for this run.” (including another organisation’s run). | |
409 | api_off |
|
500 | “could not read the library” or “could not check token”. | |
501 | “The library isn’t set up on this server.” |
Download one size's kept files
Downloads one size’s kept files (not thumbnails) in one zip, flat, each as <name>. A size with no kept file is a 404.
Path parameters
jobIdstringRequiredThe id of the server run’s run for one brand (16 hex characters).
filestringRequiredThe size’s format key and
.zip(<key>.zip). A key that matches no kept file, or a name without.zip, is a404.
Returns
The zip.
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 | “No files are kept for this run.” (including another organisation’s run). | |
409 | api_off |
|
500 | “could not read the library” or “could not check token”. | |
501 | “The library isn’t set up on this server.” |
Download a group's kept files
Downloads the kept files of every brand run that shares a runId in one zip, a folder per brand holding what that brand’s own zip holds. Another organisation’s runs are never in it. A group with no kept file is a 404.
Path parameters
runIdstringRequiredThe group’s run id (the
runIdits runs were created with).
Returns
The zip.
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 | “No files are kept for this run.” (including another organisation’s run). | |
409 | api_off |
|
500 | “could not read the library” or “could not check token”. | |
501 | “The library isn’t set up on this server.” |
Start editing a size
Opens one size of a run for editing and answers the session: its id, the size’s elements (what each is, where it sits and what it says), the check of the design rules and the checkpoint loaded. Send the session id in X-Mestra-Edit-Session on every later call. A session belongs to the key that opened it, ends after an hour unused and is lost if the service restarts: a later call that answers 404 (session_gone) means open the size again. Only sizes that List all editable sizes of a run marks editable can be opened. Needs the Designs · Read permission, and a key that opens must also hold a Write permission somewhere: a key whose only permission is Designs · Read cannot open.
Path parameters
idstringRequiredThe run’s id. A run of another organisation is a
404.keystringRequiredThe format’s key.
Query parameters
warmstringOptional1opens a warm session, held briefly ahead of a click.Possible values
1
Returns
The session, the size’s format and the plan’s check.
An object with:
sessionstringRequiredThe session id, 32 hex characters.
runstringRequiredThe run the size belongs to, as the path named it.
sizestringRequiredThe size’s key, as the path named it.
elementsarray of objectsRequiredThe design’s elements in words, in plan order.
Show child attributesHide child attributes
refstringRequiredThe element’s ref, for
ref(orid) in an edit’s input.rolestringRequiredThe element’s role as an edit may send it: lower case, words joined by
_. Empty when it has none.namestringRequiredkindstringRequiredtext,image,shape,grouporvector; empty for an element the design adds.keptbooleanRequiredFalse when the element has been dropped.
frameobjectRequiredThe element’s box in the design’s own units.
Show child attributesHide child attributes
xnumberOptionalynumberOptionalwnumberOptionalhnumberOptional
textstringRequiredNullableA text element’s copy as it stands, paragraphs joined by a line break; null for any other element, and for every element in an answer that refuses an edit (a refusal carries no copy).
rotationnumberOptionalA turned element only (one its master turns): its angle in degrees, as the master holds it. On a size it does not change.
ownFrameobjectOptionalA turned element only, and only when the master stores its own size. The unturned frame its copy sets in, in the design’s own units: the rectangle
frame(the box round it) is the turned box of. It is whatset_frametakes and gives for the element’sx,y,wandh, so send numbers from this, not fromframe. Within about 3 degrees of 45 the size draws the master’s aspect, and this is that frame.Show child attributesHide child attributes
xnumberOptionalynumberOptionalwnumberOptionalhnumberOptional
roleChosenbooleanOptionalA master’s element only. True when the role is the person’s choice; false when it is the one Mestra suggested (Auto), which a later save of the master may suggest differently. A master saved before Mestra kept this answers true for every element.
zintegerOptionalA master’s element only. Its place in the stacking: a higher z is in front. A group’s is its topmost member’s.
groupstringOptionalA master’s element only, and only when it is a member of a group: the group’s ref.
membersarray of stringsOptionalA group’s entry only (
kindisgroup): the refs of its members, back to front. A master’s groups are listed beside its elements, each with the box around its members, soset_orderandungrouphave a ref to name. A master’s nested groups (a clip group’s clip is on one) are listed the same way, each withgroupset to the group or nested group it is under and its members the elements under it; the id is whatset_order,set_rotation,move_unit,scale_unitandungrouptake for it.lookobjectOptionalA master’s element only, and only when it has an effect or a paint. Its look in words:
effectsare the effect types in order (a level’s after the look’s own) andpaintsis how many fills and strokes it has.Show child attributesHide child attributes
effectsarray of stringsOptionalpaintsintegerOptional
suggestedRolestringOptionalA master’s element only. The role Mestra suggests for the element, in the same form as
role: what choosing Auto would give it. For an element whose role is suggested it is its own role.
formatobjectRequiredShow child attributesHide child attributes
keystringOptionalnamestringOptionalThe format’s name.
widthnumberOptionalheightnumberOptionalunitstringOptionalPossible values
pxmm
checkobjectRequiredThe plan’s check.
resultsis every rule the check judged, with the number it measured; a client that gets none shows the failures and warnings alone.Show child attributesHide child attributes
failuresarray of stringsRequiredwarningsarray of stringsRequiredobjectiveintegerRequiredresultsarray of objectsOptionalShow child attributesHide child attributes
sourcestringRequiredbrandfor the brand’s rules,specfor the screen spec.Possible values
brandspeccodestringRequiredrefstringOptionalNullableThe element the rule judged, or null for a whole-size rule.
passbooleanRequiredmeasurednumberOptionalNullablelimitnumberOptionalNullableunitstringOptionalNullablePossible values
ptpxmmratiosharewordsnullatstringRequiredWhat the result was judged on: the drawing, the plan’s boxes, or an earlier state that an edit has since changed.
Possible values
renderplanstalefixobjectOptionalOn a failing result only, and only when Mestra knows an edit that clears it: the edit’s
nameandinput, exactly as the edit call takes them, so applying it is one op and one undo step. It was tried on a copy of the session first: the copy took it, the rule is met on that element afterwards, and no failure appeared that the current state lacks. That check covers only what the plan can show (the boxes and sizes of the elements); the copy is never rendered, so a failure that only a drawing shows, such as contrast or a picture’s content, is not ruled out. Offered for a text under its type floor (type-min), which getsset_textwith the size that meets it; for a legal line under the legal size (rule-legal-size), which getsset_textwithparasnaming its paragraphs under the limit and the size that meets it; and for an element outside the safe area (crs-safe-area), which getsmove_unitto the nearest place that puts the element, its lockup and the units grouped with it inside the safe area (none when they are together bigger than it). Its numbers are in the edit’s own units, page units for a place and points for a size. It is computed on the state the answer shows: apply it to that state, not a later one. A master gets none (its type size is only ever a warning), and neither does a result judged on an earlier state (atisstale). This is not the answer’sfixes, which lists what Mestra already did on its own.Show child attributesHide child attributes
namestringRequiredAn edit the apply call takes, such as
set_textormove_unit.inputobjectRequiredThe edit’s input.
sizeDriftarray of stringsRequiredElement refs whose stored text sizes differ from the plan’s own scaling.
labelstringRequiredThe first checkpoint,
loaded.sceneHashstringRequired
Errors
| Status | Code | Meaning |
|---|---|---|
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
404 | “job not found” or “format <key> is not in the job’s campaign.” | |
409 | not_editableapi_off | “This size can’t be opened in the editor” (code |
500 | The master or its fonts could not be read. | |
503 | editor_unavailable | “The editor isn’t available right now.” (code |
Update a size being edited
Makes one edit, or several, on an open session. Send the session id in X-Mestra-Edit-Session. The body is {"name", "input"}, where name is set_frame, move_unit, scale_unit, set_text, set_style, set_colour, set_copy, swap_picture, crop, keep or drop; any other name answers 400 (field: name). Send {"edits": [{"name", "input"}, ...]} to make several in one request: every name is checked first, the edits are made in order and stop at the first refusal, and the changes made share one checkpoint. Address the element by ref (id for move_unit and scale_unit), or send role in its place when exactly one kept element has that role: {"name": "set_colour", "input": {"role": "headline", "colour": "#ff0000"}}. A role that no kept element has is refused as unknown_role; a role several have is refused as ambiguous_role with candidates listing them by ref, role and name, and nothing is applied (a batch is refused whole). A refusal is a 200 with refused set and nothing applied for that edit. An edit that changed something is checkpointed e1, e2, … in label; noChange says nothing moved. Needs the Designs · Write permission.
Making the design itself, on a master or a new design (a session opened with Start editing a master, or with Start a new design), the session also takes these, which change the composition and never a size: add_element {"id": "m1a2b3c4d5e", "kind": "text", "frame": {"x": 40, "y": 30, "w": 600, "h": 120}} adds an element on top of the stacking (or on top inside the group parent), where id is made by the caller and reads m and ten of 0-9a-z (bad-id when it does not, id-taken when the composition holds it), kind is text, shape (shape is rect, ellipse or path) or image, and frame is x, y, w, h in the page’s units; a text takes text {"paragraphs": [...]} (each paragraph the composition’s own: content, font, size, leading, tracking, align, fill, capitalization and the like, each left out one taking the brand’s face, the palette’s darkest colour, left alignment, a size that sets one line in the frame and leading 1.2 times it), a shape takes fill (a colour of the brand’s palette, else the brand’s first colour) and, for a rect, radius (0 to half the shorter side of the frame, as set_shape’s: bad-number with the field in limit outside it, bad-input on an ellipse or any other kind) and, for a path, radius too (0 to 20000, the renderer’s side limit: it rounds the corners of each closed subpath, and a corner is limited per vertex as it is drawn; bad-number with the field in limit outside it, bad-input for a path with no closed subpath), and for path the outline as path (the composition’s own: subpaths {closed, points: [{x, y, in?, out?}]} as fractions of the frame, with fillRule nonzero or left out for even-odd; bad-input with limit.field path without one) and for an ellipse optionally arc {start, end, inner} (degrees clockwise from +x, inner the hole as a fraction of the radius; bad-number with the field when out of range), an image names image {"asset": sha256} of a picture uploaded into the session (or the organisation’s) and is placed to cover its frame, or logo {"variant": "primary"} for the brand’s own logo, a PNG or an SVG, which is added as a picture with the role logo (unknown_logo 404 when there is none; an SVG is placed as an SVG picture whose size is its viewBox, each side rounded to a whole number from 1 to 100000, and svg-viewbox 422 with field logo.variant refuses one whose root has no viewBox of four finite numbers with a width and height above 0, or a side outside that range; logo_format 422 for a file that cannot be read as a picture). role is optional: without one the element is saved with the role Mestra suggests, and its roleChosen says false until one is chosen. set_order {"ref": ..., "to": "front" | "back" | "forward" | "backward" | {"above": ref}} moves an element, or a group whole, in the stacking among its siblings (the other members of its group, or the other elements and groups), changing z and nothing else; order-split refuses an order that would take a member out of its group. ref may also be a nested group’s id (a group inside a group; the elements list gives each one an entry of its own, with group the group or nested group it is under): the elements under it move together among its siblings, the other units of the group or nested group it is under, in one undo step, and a clip group’s frame stays its bottom member (clip-frame-back). {"above": ref} names a sibling; an element or nested group that exists but is not one (one of the nested group’s own members, or something outside its group) is order-split, and an id that is none of them is unknown-ref. make_group {"id": ..., "refs": [...]} makes a group of elements (already-grouped for one that is in a group; members apart in the stacking are brought together at the topmost one’s place; a clip is refused as not-supported) and ungroup {"ref": group} dissolves one (group-holds for a group that has an opacity, fade, look or nested group of its own). ref may be a nested group’s id: that nested group alone goes, its elements stay where they are in the group it was under (z is not changed) and any nested group under it moves up with them; one with an opacity, fade, look, mask or clip of its own is group-holds (release a clip with release_clip first). An element a session added is removed with drop. Every answer after the first of these carries comp, the working composition as a change to the one the open answer sent: upsert (each element that is new or changed, as the composition holds it), remove (ids that are gone) and groups (all of them); a restore carries it too. Each element in elements says its z, the group it is in when it is in one and, when it has effects or paints, its look in words ({"effects": [type...], "paints": n}); each group is an entry of its own (kind group, its members, the box around them and the z of its topmost member), the ref set_order and ungroup take. set_look {"ref": ..., "look": {...}} replaces an element’s whole look with the composition’s own (blend, effects, fills, stroke, strokeWidth, strokeAlign, strokeOver, the text stroke’s strokeDash, strokeDashOffset, strokeCap, strokeJoin and strokeMiterLimit, arc, levels with fill, stroke and content); an empty look removes it, and nothing but that element’s look changes. It is checked before it is written and refused with limit.field naming the field of the look (look.effects[1], look.levels.fill.effects[0], look.fills[0], look.blend): too-many-effects for more than 8 effects in a look or level (limit.max 8, measured) or more than 64 in the design (limit.field effects, max 64, measured the total it would have; a progressive blur and a glass each count 8, and a look that lowers a total already over is let through), glass-conflict for a glass beside a background blur or a linear-burn or linear-dodge blend, or on a level (a level has no glass or background blur), and bad-look for anything else the composition refuses, an unknown field, or picture, notes and reach (the server’s, for a look drawn from a saved picture: replacing such a look drops the picture). set_shape also takes the composition’s own shape fields, each only when sent and null clearing it, all written to the composition together: radii [topLeft, topRight, bottomRight, bottomLeft] (0 to half the shorter side), cornerStyle (rounded, bevel, inset, inverse or fancy, for every corner), cornerStyles (four of those, one per corner in radii’s order, null for every corner rounded; sent with cornerStyle it is refused as bad-input, limit {"field": "cornerStyles"}; side weights go with no cut corner), dash (at most 16 lengths), dashOffset, dashFit, cap (butt, round, square), join (miter, round, bevel), miterLimit (1 to 100), gap (a colour of the brand’s palette, style-refused otherwise), stripes (at most 8 {from, to} bands, 0 to 1), sides (the four side weights of a plain rectangle, not beside a cut corner) and ends ({start, end} line ends of a path shape, each {type, scale?}) and strokeAlign (center, inside or outside: where the stroke sits on the edge; null for the default, centre); a number out of range is bad-number with the field in limit (radii[3], dash[1]), a field the shape cannot take (corners on an ellipse, radii, cornerStyle and cornerStyles on a path, ends on a shape with no path) bad-input or not-supported. A path shape (a polygon, a star or any path) takes radius alone: one size, 0 to 20000 (the renderer’s side limit; each corner is limited per vertex as it is drawn), that rounds the corners of every closed subpath (an absent closed is closed, with 3 or more points) and is written to the composition, with a decorative too; bad-number with the field in limit outside the range, bad-input with limit.field radius for a path with no closed subpath (an open path or a line is never rounded). With polygon or star in the same call the radius rounds the new outline. On a size these are refused with 400, code master_only.
Lines, polygons, stars, turning and text paints (the same sessions). add_element kind text may leave frame.h out (or send 0): the box is then one line high at the size the text takes (its leading, 1.2 times the size, unless a paragraph gives one), kept inside the safe area, so a click or a dragged width makes the box in one add and one undo step; an explicit h is kept as sent, and any other kind still needs all four numbers. add_element also takes kind line, polygon and star, each stored as a shape of type path. A line takes from and to ({"x", "y"} in the page’s units; two different points, else bad-number) and no frame (bad-input): its frame is the box round the two points grown by half the stroke weight on every side, so a level or upright line has a width and a height, and its points are fractions of that frame. A line has no fill (fill is bad-input) and always a stroke: stroke (a colour of the brand’s palette, default the brand’s first colour, style-refused outside it) and strokeWidth (page units, above 0, default 0.4% of the page’s shorter side and never below 1 pt, about 4 px on a 1080 px page, bad-number with limit.field), and it takes ends ({start, end}, each {type, scale?}), cap, join and dash as set_shape’s. A polygon takes frame and sides (a whole number from 3 to 1000), a star takes frame, points (3 to 500) and innerRatio (0 to 1, default 0.5: the inner vertices’ share of the outer radius); the outline is made on the server (a vertex at the top, filling the frame) and stored as points, with no parameters kept. They take fill as a shape does, and optionally stroke and strokeWidth (giving either gives the other its default), cap, join and dash; ends is bad-input on them. radius is bad-input on a line (it has no corners), and a polygon and a star take it as a closed path does (0 to 20000, rounding each corner; bad-number with the field in limit outside it), as from, to, sides, points, innerRatio and the stroke fields on any other kind. set_shape takes polygon {"sides"} or star {"points", "innerRatio"?} to make the outline of a path shape again in the same frame (bad-input on a rectangle or ellipse or when both are sent, bad-number out of range; its line ends are dropped; a decorative may take it alone). set_rotation {"ref": ..., "degrees": 30} turns a text or shape to degrees (-360 to 360, counter-clockwise as the composition holds it, 0 unturns it; bad-number outside that): the composition’s element gets rotation, size (the frame’s own unturned width and height) and bounds (the box round the turned frame, about the same centre), and at 0 the size goes and bounds are the frame; a later move shifts the box and keeps the size, and a turned element is resized by its own frame (set_frame, scale_unit; see below). For a group ref names the group and degrees is the turn applied to every member about the centre of the box round them (a group holds no angle of its own), each member’s angle growing by it. ref may also be a nested group’s id, which turns the elements under it the same way; a group or nested group holding plain nested groups (no fade, look or mask, and no clip unless Mestra made it) turns, and its elements under them with it. A button (a text and the shape that backs it, as the editor’s button tool makes them) turns as a group does: ref may be its label, its pill or its group, and degrees is a turn by (relative), applied to both about the centre of the box round them; a single element’s degrees stays an angle to take. A picture, the background, a member of a lockup that is not a button, a text with pinned lines, a group or nested group with its own fade or look, a group or nested group holding (at any depth) a nested group with a fade, a look, a mask or a clip that Mestra did not make, and a turned element whose own size is not stored are refused as not-supported; an unknown ref as unknown-ref. set_paras_paint {"ref": ..., "paras": [0], "fills": [...], "stroke": [...], "strokeWidth": 1.5, "strokeOver": true} writes the glyph paints of a text’s paragraphs (paras index the drawn paragraphs, as set_colour’s do, paragraphs split from one source sharing its paints; left out, every paragraph): fills is the paint stack that draws the text, bottom first, and stroke the outline’s paints with strokeWidth (page units, above 0) and strokeOver (true: over the fill); each is read only when sent and an empty list or null removes it (removing the stroke removes its width and strokeOver). A paint is the composition’s own (solid, linear, radial, angular or diamond; at most 8 to a list, bad-number; no image paint, bad-input); every colour and gradient stop must be of the brand’s palette (style-refused), bad-input for a colour that is not #RRGGBB or a stroke without a width above 0 (or a width or strokeOver with no stroke), bad-number for a width outside 0 to 20000, unknown-ref for an element that is not a text. The paragraph’s plain colour is kept in step with the first solid fill. set_colour with paras on a paragraph that has fills makes it that one plain colour and drops the fills (on a size it is still refused as bad-input). set_page {"width": 1200, "height": 628, "margins": {"top": 20, "right": 20, "bottom": 20, "left": 20}} (a master or new-design session only; each field only when sent and at least one, page units) changes the master’s page size and margins after it is made: every element keeps its box (nothing is moved or scaled, as in InDesign with no layout adjustment), so an element may stand past the new edge, and the answer’s comp carries the new page. A width or height under the least or past the most that can be drawn (1 to 20000 in the page’s unit), a margin below 0, or margins that leave no page inside them (left and right at or over the width, top and bottom at or over the height) is bad-number with the field in limit (width, height, margins.top … or margins); nothing sent is bad-input; the same page as it is now is noChange; on a size it is 400 master_only.
Paragraph indents and list markers (a master’s session). set_paras_indent {"ref": ..., "paras": [0], "indent": 24, "firstIndent": -24, "marker": "1."} writes the indents and the list marker of a text’s paragraphs (paras index the drawn paragraphs, as set_colour’s do, paragraphs split from one source sharing them; left out, every paragraph): indent is the inset of every line’s start edge from the box’s left edge (0 or more, page units), firstIndent the extra inset of the first line only (negative hangs it out) and marker the literal list marker drawn on the first line (a bullet, 1. or a): not empty, without a line break). Each is read only when sent; null removes one (and 0 an indent). indent plus firstIndent must be 0 or more as each paragraph ends up. An indent or a first-line indent outside its range, or one that takes the first line left of the box, is bad-number with the field in limit; an empty marker or one with a line break is bad-input. A size session answers 400, code master_only.
Underline and strikethrough (a master’s session). set_paras_decoration {"ref": ..., "paras": [0], "underline": true, "strike": false} underlines and strikes through the whole of a text’s paragraphs (paras index the drawn paragraphs, as set_colour’s do; left out, every paragraph); each of underline and strike is read only when sent, false takes it away, and a paragraph’s own style runs lose their underline and strike so that the paragraph follows the call. With range {"para": 0, "start": 4, "end": 9} it sets them on those graphemes of one drawn paragraph alone (extended grapheme clusters, the unit of breaks and style runs; 0 <= start < end <= the paragraph’s count; paras is then left out or [para]), written as style runs that are split and merged as needed. The composition holds underline and strike as booleans: the line’s weight, offset and colour are the renderer’s own for now. Nothing to set, a paragraph that is part of a longer paragraph of the master (for a range), or paras naming another paragraph than the range’s is bad-input; a range outside the paragraph is bad-number with limit.field range. A size session answers 400, code master_only.
Flipping a picture (a master’s session). set_flip {"ref": ..., "flipX": true, "flipY": false} mirrors the picture of a picture frame across (flipX) or down (flipY), each only when sent; false takes one away. The picture is mirrored about its frame’s centre before the element’s turn, so a zoomed and panned picture is the mirror of what it was; the logo and a vector picture can be flipped too. Nothing to set, or a flag that is not true or false, is bad-input; a ref that is not a picture is unknown-ref. A size session answers 400, code master_only.
Paths from the pen (a master’s session). add_element kind path {"id": ..., "kind": "path", "path": [{"closed": false, "points": [{"x": 100, "y": 200}, {"x": 300, "y": 200, "in": {"x": 250, "y": 120}, "out": {"x": 350, "y": 280}}, {"x": 300, "y": 500}]}], "stroke": "#1A2B3C", "strokeWidth": 4} adds a path shape from subpaths of anchor points. Every number is in page units, on the page (not relative to the element): a point’s x and y, and its optional cubic handles in (toward the previous point) and out (toward the next; an open subpath’s first in and last out lead nowhere and are not stored), each the handle’s own place on the page and not an offset from the point; a segment with no handle at either end is a straight line, and one with a handle at one end only is curved by that handle. closed is true or left out for a closed subpath (it needs 3 points) and false for an open one (2 points); a subpath that is shorter is bad-input, as is a point or handle with no x or y and a key that is not closed, points, x, y, in or out, and more than 32 subpaths or 1000 points in all, or a number that is not finite or is past 1000000, is bad-number with the field and the limit. A path may reach into the bleed, but one wholly off the page is bad-number (“off the page”) with the field path. There is no frame: the element’s frame is the box round the drawn curve (a side with no extent, as a level path has, takes the stroke weight), and the stored points are fractions of it. An open path has no fill, as a line has none (fill on a path with no closed subpath is bad-input); a closed one has a fill only when fill (a colour of the brand’s palette) is sent. With no fill the path is stroked, stroke (a palette colour, the brand’s first by default) and strokeWidth (page units above 0, by default a line’s: 0.4% of the page’s shorter side, never below 1 pt), as a line is; with a fill, a stroke only when sent. fillRule is nonzero, or left out or null for even-odd, which decides what a path that crosses itself or holds another subpath fills. cap, join, dash and ends (open subpaths only) take what set_shape takes, and radius rounds the closed subpaths as for a polygon (bad-input on a path with none). set_path {"ref": ..., "path": [...]} replaces the outline of any path shape (made as a line, polygon, star or with the pen; after it the element is just a path) with subpaths as above, and the element’s frame, in the design and in the plan, becomes the box round the new outline, so it is drawn where it was given. An outline with no open subpath takes the line ends away; one with no closed subpath takes the fill and the radius away and, if there was no stroke, gets the default one so it can be seen; nothing else of the shape changes. The same outline is noChange; a ref that is not a path, rectangle or ellipse shape is unknown-ref; a turned path keeps its angle: the points are given on the page, and its own frame is the box round the outline turned back by that angle (the stored frame is the box round that, as for any turned element). On a decorative, the fill, stroke and radius it was given and where it was moved are cleared where the new outline would undo them, so an open curve is not drawn filled and the new frame holds. With no path, a rectangle or an ellipse (also a picture frame of either) is made a path with the outline it has, drawn where the shape was and turned with it when it is turned (set_path {"ref": ...}; Edit shape in the editor). A rectangle with one radius on every corner becomes its four corners and that radius, which the renderer rounds in page units (capped at half the shorter side, as a rectangle’s is), so the corners stay circular on every size; a radius the plan holds and the design does not yet (a decorative’s included) is taken in. Corners that differ are drawn as the renderer draws them: rounded and inverse ones as quarter circles (cubics), bevelled and inset ones as straight segments, a fancy one as its staircase with the island as a closed subpath of its own, and a Figma design’s corners by Figma’s size rule. An ellipse becomes four cubics with the standard handle length; an arc or ring becomes its sector or annulus, the ring with an even-odd fill, and the look’s arc goes. Fitted dashes (dashFit) keep their pattern without the fit, which a path does not have, and the answer’s fixes has dash-fit-dropped:<ref>. Its fill, stroke, look and picture stay. Refused with not-supported: strokes of a different weight on each side (a path has one stroke weight), and a turned shape whose own size is not stored. A picture frame stays a picture frame, its picture clipped to the path and laid out again in the new frame at the zoom and focal it had (a turned frame’s by the turned-frame resize, in its own unturned frame; not-supported when its picture’s own box is not stored); its outline stays closed, and so does that of the frame of a clip group (bad-input for an open one). A lockup anchor’s riders follow its new box (bad-input when the lockup would leave the page); a container or backing panel keeps the box given, held to its copy as set_frame is (text-off-panel); a background’s outline is kept in the page box, so it is drawn on every size as it was given. A closed pen path takes a picture (place_picture) and can be the frame of a clip group (make_group with clip, the group’s mask). set_shape also takes fillRule (nonzero, or null for even-odd; bad-input for anything else and for a shape that is not a path) and, on a path, strokeWidth, stroke, cap, join, dash and ends. A size session answers 400, code master_only.
Text on a path (a master’s session; render 0.40.0, InDesign’s Type on a Path). set_text_path {"ref": ..., "onPath": {"effect": "rainbow", "align": "baseline", "toPath": "center", "flip": false, "start": 0, "end": 1, "spacing": 0}, "text": "Along the line"} sets the text of a path shape on its outline, changes how it sits there, or takes it off. ref is a path shape (a line, a pen path, a polygon or a star: a shape of type path) or a text that is on a path already: one element with its path as its shape, as InDesign holds it, so set_path and the pen move the text with the outline and the outline’s stroke is the stroke toPath refers to. onPath is the whole set of options, replaced as one ({} is the defaults), or null: effect is rainbow (default), skew, ribbon, stair or gravity; align is which line of the text lies on the path, baseline (default), ascender, descender or center; toPath is where that line sits on the outline’s stroke, center (default), top or bottom; flip puts the text on the path’s other side; start and end are the brackets, fractions 0 to 1 of the path’s length in the direction the unflipped text travels (defaults 0 and 1; on an open path end is after start); spacing is InDesign’s Spacing, -1000 to 1000, in the text’s units; justify is all to stretch the spaces to fill the span (a paragraph’s own justify sets one line at its left); ascent and descent are the face’s lines as fractions of the em (0 to 2), for a measured pair. A key sent as null or at its default is not written. On a path shape onPath makes it a text and text is the copy, required (the first paragraph, in the session’s face, size and colour as add_element gives a new text; the path keeps its fill, stroke, frame and place in the stacking); on a text, text is bad-input (set_text and set_copy change the words) and null takes the type off the path: the element is a path shape again, as InDesign’s Delete Type from Path leaves it (its text is gone; the path, fill, stroke and look stay). The same options are noChange. It is unknown-ref for anything that is not a path shape or a text on a path, bad-number with limit.field onPath.<key> for a number out of range (never clamped), bad-input for an onPath that is not an object or null, an unknown key or word, or a missing or blank text on a path shape. Only the element’s kind, text and onPath change. A size whose text on a path does not fit between its brackets is reported as a text that does not fit. A size session answers 400, code master_only.
Pinned line ends (a master’s session). set_paras_breaks {"ref": ..., "paras": [0], "breaks": [12, 30]} pins the line ends of the one paragraph paras names (indices of the drawn paragraphs, as set_colour’s are) at those grapheme offsets of its text (extended grapheme clusters, the unit the layout wraps by: each above 0 and below the paragraph’s count, in increasing order, none beside a line feed, which already ends a line): the paragraph is then broken at those places and nowhere else while its copy, size, face and box width are the master’s. A pinned paragraph is broken only at its pins and never wrapped again, so a line wider than the box overflows it: breaks is every line end the paragraph should have, the places it wraps at now included. "breaks": null (or []) releases the pins of paras (every paragraph when left out): breaks, lineWidths and lineXs all go, as they go together. A paragraph that has pinned line widths or letter positions (one per pinned line) refuses a different list until they are released. A list outside its range is bad-number with limit.field breaks; a list for more or fewer than one paragraph, a paragraph that is not its master’s whole (part of a longer paragraph, or copy a size changed), or one with widths or positions is bad-input. A size session answers 400, code master_only.
Masking a picture (a master’s session). set_mask {"ref": ..., "asset": "<hash>", "mode": "alpha", "bind": "frame"} sets, replaces or removes a picture’s own mask (render 0.30.0): another picture, read as its alpha or its luminosity, that hides parts of this one. asset is the mask picture, an upload or a library picture the session holds, by hash (a PNG, JPEG or SVG). On a picture with no mask it makes one over the whole frame, mode alpha and bind frame unless sent; on a picture that has one it replaces the mask’s picture and keeps its mode, box and binding. asset null removes the mask. mode is alpha or luminosity; bind is frame (the mask stays put when the picture is panned or zoomed) or picture (the mask moves with the picture). Each of mode and bind is read only when sent, and a change of bind carries the mask’s box over so the mask stays where it is (a turned picture’s box is carried in its own unturned space, and a flipped picture’s is mirrored, since a mask tied to the picture mirrors with it; the answer’s fixes has mask-mirrored:<ref> then; only a picture with no known placement has its box become the whole of what it is now tied to, with mask-box-reset:<ref>). Refused: bad-input for nothing to set, a mode or bind with no mask and no asset, a mode or bind sent with asset null, a value that is not one of theirs, a picture the session does not hold or one that is not a PNG, JPEG or SVG; unknown-ref for a ref that is not a picture of the composition; not-supported (detail picture_no_mask) for a picture drawn from the design app’s saved picture, and bind picture on a picture with no known placement (limit.field bind). ref may also be a nested group’s own id (a clip group’s nested id, as set_rotation and ungroup take): the group’s soft mask is then set, replaced or removed the same way, with a first mask alpha over the whole group and the same mode; a group’s mask has no binding, so bind is bad-input. A group with a mask moves and scales as one rigid piece when sizes are made. The mask picture is saved with the master and a save that replaces or removes it leaves no other. A size session answers 400, code master_only.
Adding a colour to the brand’s palette. add_palette_colour {"hex": "#1A2B3C"} works on any session, a size or a master. It adds the colour to the brand’s own colour list, the one Setup edits, and takes it into the session’s palette, so a set_colour (or any paint) with it is accepted afterwards; a colour the palette already holds (white and black always are) writes nothing. It is not an edit of the design: it answers noChange true with no label, is never an undo step, and an undo leaves the colour in the palette. The brand’s list is the brand’s, not the design’s, so it needs the permission that changes a brand in Setup, the editor role, and for an API key Brand · Write as well as Designs · Write (403, code wrong_key, without it). A colour that is not #RRGGBB answers 400 (field: hex); a design that is not for a brand yet answers 400, code no_brand. Read the brand’s palette back with the brand (GET /centres/{key}, brandColours) or its styles.
Picture frames and clip groups (the same sessions). add_element kind image also takes an outline, which makes the picture a picture frame: shape (rect, ellipse, path, polygon or star; a line, an open path and arc are bad-input), radius (a rect’s corner radius, as for a shape, bad-number with the field in limit outside 0 to half the shorter side; bad-input with limit.field radius on an ellipse; on a path, polygon or star frame it is 0 to 20000 and rounds the closed subpaths, bad-number with the field in limit outside that), path and fillRule (shape path: closed subpaths of at least 3 points), sides (polygon), points and innerRatio (star), and the border: stroke (a colour of the brand’s palette, style-refused outside it) and strokeWidth (page units, 0 to the stroke limit, bad-number with limit.field; either gives the other its default). The picture covers the frame, centred (image.placement.bounds), and the frame is clipped to the outline, which is the element’s shape, with no fill. place_picture {"ref": ..., "asset": "<sha256 of an upload>"} makes the shape ref a picture frame in place: it keeps its id, bounds, z, group, role and outline, and loses its fill, fill inks and look fills (unknown-ref for a text or an element the plan does not hold, bad-input for a picture already, with the picture swapped by swap_picture, or an upload the session does not hold, not-supported for a decorative, a lockup’s member, a turned shape whose own size is not stored and an outline that is not closed). set_picture {"ref": ..., "zoom": 2.5, "focal": {"x": 0.3, "y": 0.6}} zooms (1 to 20, the frame always covered; bad-number with limit.field zoom) and pans (focal is where the frame sits in the picture, 0 to 1 on each axis; bad-number with limit.field focal.x or focal.y) the picture of a picture frame, each only when sent (bad-input when neither is); it writes image.placement.bounds (and, for a turned picture, placement.own, the graphic’s box in the frame’s own unturned space) and removes the scale, and the fold at save keeps it. It is unknown-ref for anything but a picture the plan holds and not-supported for the logo, a QR code, a vector, a picture drawn from the design app and a picture with no placed graphic. set_adjust {"ref": ..., "adjust": {"exposure": 0.2, "contrast": -0.1, "saturation": 0, "temperature": 0, "tint": 0}} sets a picture’s colour adjustment (the five of Figma’s image filters, each a number from -1 to 1, 0 neutral; the editor shows them times 100): the whole adjust is replaced, a key left out, null or 0 is not written, and an empty adjust, an all-neutral one or null removes it. It writes image.adjust alone. It is unknown-ref for anything but a picture of the composition, bad-number with limit.field adjust.<key> for a value that is not a number from -1 to 1 (never clamped), bad-input for an adjust that is not an object or has a key that is not one of the five, and not-supported for a picture drawn from the design app. make_group also takes clip {"nested": "m...", "frame": "<ref>"}: the group becomes a clip group, a nested group nested (a new id made as the others are, other than the group’s own: bad-id, id-taken, bad-input) under it whose children are the frame, then the other members back to front, and whose clip is the frame’s outline as fractions of the box round the members as they are drawn (a turned member counts as its own size about its centre). frame is the lowest of refs unless named and must be one of them (bad-input); it must be a closed shape, a rectangle with plain corners (not bevel, inset, inverse or fancy), an ellipse, a closed path, or a picture with an outline of its own (not-supported); a clip group has two or more refs (bad-input). The clip is derived again from where the members are after every edit and in the fold (a move, a resize, a turn, an added or a removed member), so it stays on the frame; only for ids Mestra made. release_clip {"ref": ...} (the group or its nested group) removes the clip and leaves a plain group, except a group that make_group with clip made in this same session, which goes with the clip (its members are as they were before it; a group from an earlier session or one that has since gained a look, fade, opacity or another nested group stays) (unknown-ref for neither, bad-input when it holds no clip). ungroup of a clip group is still group-holds. set_order is refused as clip-frame-back when it would put a clip group’s frame above any of its content or content below it; add_element with parent the group joins the clip group; dropping the frame, or all the content, ends the clip group at save (the group stays). set_rotation now turns a picture (its graphic with it; a photo or the background, a vector and a picture drawn from the design app are not-supported) and a group holding clip groups (members about the centre of the box round them, the clip derived from the turned frame). The answer’s comp.nested is every nested group of the working composition, as comp.groups is every group, and a master session’s answer carries foldNested, the nested groups of the folded composition, when the fold changes them (a clip derived again from a member the plan moved or removed).
On a master (a session opened with Start editing a master) the session also takes these, and set_text and set_style take more. set_opacity {"ref": ..., "opacity": 0.5} sets a kept element’s opacity, 0 (clear) to 1 (opaque); out of range is refused as bad-number with limit {"field": "opacity"}. set_shape {"ref": ..., "stroke": "#1A2B3C", "strokeWidth": 2, "radius": 8} sets a kept shape’s stroke colour (a colour of the brand’s palette, or an empty string for no stroke), stroke width and corner radius, each only when sent and at least one of them; a colour outside the palette is refused as style-refused, a width or radius out of range as bad-number with the field in limit, and an element that is neither a shape nor a picture frame as unknown-ref. A rectangle picture frame (a picture made with shape rect) takes set_shape too, for its corners alone: radius, radii, cornerStyle and cornerStyles, as a rectangle shape does, in one undo step; its border and the rest of its outline are not set that way (bad-input with limit.field naming the field). A path, polygon or star frame takes radius alone (0 to 20000, rounding its closed subpaths; radii, cornerStyle and cornerStyles are bad-input), and an ellipse frame has no corners to set (bad-input with limit.field radius or radii). The element’s caps.radius is true for exactly the frames that take them. set_role {"ref": ..., "role": "headline"} sets a kept element’s role to one of headline, subhead, body, cta, legal, logo, icon, photo, background or decorative, or null for Auto (the role Mestra would give it, as suggestedRole in the answer’s elements says); the element’s roleChosen is then true, and carried names each element that joined (lockup-formed) or left (lockup-broken) a lockup because of it. set_opacity and set_shape may send role in place of ref, as above; set_role takes ref alone, its role being the value. set_text also takes verticalAlign (top, center, bottom or justify) and caps (normal, allCaps, smallCaps or capToSmallCaps, on the paragraphs in paras, or on every paragraph), set_text with align (left, center, right or justify) and paras (or align justify alone, every paragraph) sets the paragraphs’ own alignment in the master with no alignReason, sent without size, maxLines, leading, tracking, verticalAlign or caps (a value that is not an alignment, inherit, or a paras index out of range is refused as bad-input), and set_style also takes paras (the font goes on those paragraphs alone). drop on a master takes the element out of the master when it is saved (fixes has removed:<ref>), and a turned element is resized as an unturned one is, keeping its angle: set_frame with w or h on a turned element takes its own frame (x, y, w, h are the unturned rectangle whose centre is the centre it turns about, page units; a field left out keeps the element’s own size or centre; the box round it follows), with neither it moves the box as before; scale_unit on a turned element, on any group id (turned or not; a group nested in it scales as part of it) or on a button with turned members takes w as the new width of the box round the unit, its top-left fixed, and scales every member’s own size and centre about that corner, each keeping its angle and every text’s type size scaling with it; move_unit on a group id takes x and y as where the top-left of the box round its members goes, and moves every member by the same amount in one edit. A resize that cannot be made is not-supported with a detail that starts resize_kind:, resize_background:, resize_lockup:, resize_pinned_text:, resize_no_size: or resize_no_own_box: (a lockup scales as one with scale_unit). A turned photo (a design app can draw one; set_rotation never turns one) resizes with its picture covering the new own frame at the same zoom and focal, as an unturned photo does, and a turned picture drawn from the design app scales with its frame. On a size, set_frame with w or h on a turned element takes its own frame in the same way (x, y, w, h are the unturned rectangle whose centre is the centre it turns about; a field left out keeps the own size or centre; a client that sent the box’s numbers for a turned element before now gets the own frame’s instead): the size holds the box round that frame, which follows, and the master’s angle stays, so (reading ownFrame and rotation from the answer’s elements) a width alone leaves the own height as it was, except within about 3 degrees of 45 (where the size cannot tell the own frame from its box and draws it in the master’s aspect): there a w or h alone scales the other side with it in that aspect, and w leads when both are sent; with neither w nor h it moves the box. On a size these are refused: set_opacity, set_shape and set_role answer 400 with code master_only (field: name), and set_text’s verticalAlign and caps and set_style’s paras are a 200 with refused bad-input and a detail that starts master_only:. They are not part of Update many sizes either (400, code master_only, field: edit.name).
What a session may hold. The revisions of the composition a session keeps for an undo, and the states of its history, are charged to the same memory as its held pictures: the session’s share (100 MiB with the pictures), the organisation’s and the editing class’s. An edit that would pass a limit is refused and changes nothing: pictures_too_large_together when the session is full (save it and open it again), org_pictures_held when the organisation’s open designs are full (save or close one, then try again), or, with a detail that starts memory_busy:, when the server’s memory for editing is in use for the moment (try again shortly). A revision no state of the history can come back to is dropped and its memory given back, and all of it is given back when the session ends. An op that would make the composition larger than a master may be (2,000,000 bytes) is refused as too-large. Dashes the renderer would not draw as sent are refused by set_shape and add_element, so a stroke is never drawn other than as set: dash-too-fine when the pattern’s period (its sum, an odd list taken twice) is under 1 page unit (limit {"field": "dash", "min": 1, "measured": ...}), dash-odd-too-long when an odd list has more than 8 entries (limit {"field": "dash", "max": 8, "measured": n}; an even list has up to 16), and dash-with-sides when the shape would have a dash, side stroke weights of its own and rounded corners (limit {"field": "dash"}). place_picture on the background is not-supported with a detail that starts frame_background:.
Headers
X-Mestra-Edit-SessionstringRequiredThe session id the open call answered. It travels in this header, never in the path.
Body parameters
namestringRequiredinputobjectOptional
Returns
The size after the edit.
An object with:
elementsarray of objectsRequiredThe design’s elements in words, in plan order.
Show child attributesHide child attributes
refstringRequiredThe element’s ref, for
ref(orid) in an edit’s input.rolestringRequiredThe element’s role as an edit may send it: lower case, words joined by
_. Empty when it has none.namestringRequiredkindstringRequiredtext,image,shape,grouporvector; empty for an element the design adds.keptbooleanRequiredFalse when the element has been dropped.
frameobjectRequiredThe element’s box in the design’s own units.
Show child attributesHide child attributes
xnumberOptionalynumberOptionalwnumberOptionalhnumberOptional
textstringRequiredNullableA text element’s copy as it stands, paragraphs joined by a line break; null for any other element, and for every element in an answer that refuses an edit (a refusal carries no copy).
rotationnumberOptionalA turned element only (one its master turns): its angle in degrees, as the master holds it. On a size it does not change.
ownFrameobjectOptionalA turned element only, and only when the master stores its own size. The unturned frame its copy sets in, in the design’s own units: the rectangle
frame(the box round it) is the turned box of. It is whatset_frametakes and gives for the element’sx,y,wandh, so send numbers from this, not fromframe. Within about 3 degrees of 45 the size draws the master’s aspect, and this is that frame.Show child attributesHide child attributes
xnumberOptionalynumberOptionalwnumberOptionalhnumberOptional
roleChosenbooleanOptionalA master’s element only. True when the role is the person’s choice; false when it is the one Mestra suggested (Auto), which a later save of the master may suggest differently. A master saved before Mestra kept this answers true for every element.
zintegerOptionalA master’s element only. Its place in the stacking: a higher z is in front. A group’s is its topmost member’s.
groupstringOptionalA master’s element only, and only when it is a member of a group: the group’s ref.
membersarray of stringsOptionalA group’s entry only (
kindisgroup): the refs of its members, back to front. A master’s groups are listed beside its elements, each with the box around its members, soset_orderandungrouphave a ref to name. A master’s nested groups (a clip group’s clip is on one) are listed the same way, each withgroupset to the group or nested group it is under and its members the elements under it; the id is whatset_order,set_rotation,move_unit,scale_unitandungrouptake for it.lookobjectOptionalA master’s element only, and only when it has an effect or a paint. Its look in words:
effectsare the effect types in order (a level’s after the look’s own) andpaintsis how many fills and strokes it has.Show child attributesHide child attributes
effectsarray of stringsOptionalpaintsintegerOptional
suggestedRolestringOptionalA master’s element only. The role Mestra suggests for the element, in the same form as
role: what choosing Auto would give it. For an element whose role is suggested it is its own role.
candidatesarray of objectsOptionalWith
refusedambiguous_role: every kept element that has the role, by ref, role and name. Withunknown_role: empty.Show child attributesHide child attributes
refstringRequiredrolestringRequirednamestringRequired
fixesarray of stringsRequiredcarriedobjectRequiredcompobjectOptionalA master’s session that has had
add_element,place_picture,set_picture,set_adjust,set_mask,set_order,make_group,release_clip,ungroup,set_rotation,set_paras_paint,set_paras_indent,set_paras_decoration,set_paras_breaks,set_flip,set_path,set_text_pathorset_page: the working composition as a change to the composition the open answer sent. A restore answers it too.Show child attributesHide child attributes
upsertarray of objectsOptionalEach element that is new or changed, as the composition holds it.
removearray of stringsOptionalIds of the open composition’s elements that are gone.
groupsarray of objectsOptionalEvery group of the composition.
nestedarray of objectsOptionalEvery nested group of the composition (a clip group’s clip is on one).
pageobjectOptionalPresent only when
set_pagehas changed the page from the one the open answer sent: the page as it now is, as the composition holds it.Show child attributesHide child attributes
widthnumberOptionalThe page width, in the page’s unit.
heightnumberOptionalThe page height, in the page’s unit.
unitstringOptionalThe page’s unit, which
set_pageleaves as it was.marginsobjectOptionalThe margins, in the page’s unit.
Show child attributesHide child attributes
topnumberOptionalleftnumberOptionalbottomnumberOptionalrightnumberOptional
checkobjectRequiredThe plan’s check.
resultsis every rule the check judged, with the number it measured; a client that gets none shows the failures and warnings alone.Show child attributesHide child attributes
failuresarray of stringsRequiredwarningsarray of stringsRequiredobjectiveintegerRequiredresultsarray of objectsOptionalShow child attributesHide child attributes
sourcestringRequiredbrandfor the brand’s rules,specfor the screen spec.Possible values
brandspeccodestringRequiredrefstringOptionalNullableThe element the rule judged, or null for a whole-size rule.
passbooleanRequiredmeasurednumberOptionalNullablelimitnumberOptionalNullableunitstringOptionalNullablePossible values
ptpxmmratiosharewordsnullatstringRequiredWhat the result was judged on: the drawing, the plan’s boxes, or an earlier state that an edit has since changed.
Possible values
renderplanstalefixobjectOptionalOn a failing result only, and only when Mestra knows an edit that clears it: the edit’s
nameandinput, exactly as the edit call takes them, so applying it is one op and one undo step. It was tried on a copy of the session first: the copy took it, the rule is met on that element afterwards, and no failure appeared that the current state lacks. That check covers only what the plan can show (the boxes and sizes of the elements); the copy is never rendered, so a failure that only a drawing shows, such as contrast or a picture’s content, is not ruled out. Offered for a text under its type floor (type-min), which getsset_textwith the size that meets it; for a legal line under the legal size (rule-legal-size), which getsset_textwithparasnaming its paragraphs under the limit and the size that meets it; and for an element outside the safe area (crs-safe-area), which getsmove_unitto the nearest place that puts the element, its lockup and the units grouped with it inside the safe area (none when they are together bigger than it). Its numbers are in the edit’s own units, page units for a place and points for a size. It is computed on the state the answer shows: apply it to that state, not a later one. A master gets none (its type size is only ever a warning), and neither does a result judged on an earlier state (atisstale). This is not the answer’sfixes, which lists what Mestra already did on its own.Show child attributesHide child attributes
namestringRequiredAn edit the apply call takes, such as
set_textormove_unit.inputobjectRequiredThe edit’s input.
refusedstringRequiredA refusal code, or empty when the edit was made.
detailstringRequiredRefs, field names and numbers; never copy.
limitobjectRequiredNullableThe bound a refusal or clamp ran into.
noChangebooleanRequiredlabelstringRequiredThe checkpoint a committed edit made (
e1,e2, …), the label restored, or empty.
Errors
| Status | Code | Meaning |
|---|---|---|
400 | master_only | “Send the editing session’s id in X-Mestra-Edit-Session.” ( |
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
404 | session_gone | “This editing session has ended. Reopen the size.” (code |
409 | api_off |
|
503 | editor_unavailable | “The editor isn’t available right now.” (code |
Update a size to an earlier checkpoint
Puts an open session back on a checkpoint: loaded, an e<n> label an edit answered, current or best. Send the session id in X-Mestra-Edit-Session. Keep the list of labels to step back and forward. Needs the Designs · Write permission.
Headers
X-Mestra-Edit-SessionstringRequiredThe session id the open call answered. It travels in this header, never in the path.
Body parameters
labelstringRequired
Returns
The size at that checkpoint.
An object with:
elementsarray of objectsRequiredThe design’s elements in words, in plan order.
Show child attributesHide child attributes
refstringRequiredThe element’s ref, for
ref(orid) in an edit’s input.rolestringRequiredThe element’s role as an edit may send it: lower case, words joined by
_. Empty when it has none.namestringRequiredkindstringRequiredtext,image,shape,grouporvector; empty for an element the design adds.keptbooleanRequiredFalse when the element has been dropped.
frameobjectRequiredThe element’s box in the design’s own units.
Show child attributesHide child attributes
xnumberOptionalynumberOptionalwnumberOptionalhnumberOptional
textstringRequiredNullableA text element’s copy as it stands, paragraphs joined by a line break; null for any other element, and for every element in an answer that refuses an edit (a refusal carries no copy).
rotationnumberOptionalA turned element only (one its master turns): its angle in degrees, as the master holds it. On a size it does not change.
ownFrameobjectOptionalA turned element only, and only when the master stores its own size. The unturned frame its copy sets in, in the design’s own units: the rectangle
frame(the box round it) is the turned box of. It is whatset_frametakes and gives for the element’sx,y,wandh, so send numbers from this, not fromframe. Within about 3 degrees of 45 the size draws the master’s aspect, and this is that frame.Show child attributesHide child attributes
xnumberOptionalynumberOptionalwnumberOptionalhnumberOptional
roleChosenbooleanOptionalA master’s element only. True when the role is the person’s choice; false when it is the one Mestra suggested (Auto), which a later save of the master may suggest differently. A master saved before Mestra kept this answers true for every element.
zintegerOptionalA master’s element only. Its place in the stacking: a higher z is in front. A group’s is its topmost member’s.
groupstringOptionalA master’s element only, and only when it is a member of a group: the group’s ref.
membersarray of stringsOptionalA group’s entry only (
kindisgroup): the refs of its members, back to front. A master’s groups are listed beside its elements, each with the box around its members, soset_orderandungrouphave a ref to name. A master’s nested groups (a clip group’s clip is on one) are listed the same way, each withgroupset to the group or nested group it is under and its members the elements under it; the id is whatset_order,set_rotation,move_unit,scale_unitandungrouptake for it.lookobjectOptionalA master’s element only, and only when it has an effect or a paint. Its look in words:
effectsare the effect types in order (a level’s after the look’s own) andpaintsis how many fills and strokes it has.Show child attributesHide child attributes
effectsarray of stringsOptionalpaintsintegerOptional
suggestedRolestringOptionalA master’s element only. The role Mestra suggests for the element, in the same form as
role: what choosing Auto would give it. For an element whose role is suggested it is its own role.
fixesarray of stringsRequiredcarriedobjectRequiredcompobjectOptionalA master’s session that has had composition edits: the working composition of the checkpoint restored, as a change to the composition the open answer sent (see Update).
Show child attributesHide child attributes
upsertarray of objectsOptionalremovearray of stringsOptionalgroupsarray of objectsOptionalnestedarray of objectsOptionalpageobjectOptionalPresent only when the restored page is not the one the open answer sent (a restore of a
set_page): the page as it now is,width,height,unitandmarginsas the composition holds it.
checkobjectRequiredThe plan’s check.
resultsis every rule the check judged, with the number it measured; a client that gets none shows the failures and warnings alone.Show child attributesHide child attributes
failuresarray of stringsRequiredwarningsarray of stringsRequiredobjectiveintegerRequiredresultsarray of objectsOptionalShow child attributesHide child attributes
sourcestringRequiredbrandfor the brand’s rules,specfor the screen spec.Possible values
brandspeccodestringRequiredrefstringOptionalNullableThe element the rule judged, or null for a whole-size rule.
passbooleanRequiredmeasurednumberOptionalNullablelimitnumberOptionalNullableunitstringOptionalNullablePossible values
ptpxmmratiosharewordsnullatstringRequiredWhat the result was judged on: the drawing, the plan’s boxes, or an earlier state that an edit has since changed.
Possible values
renderplanstalefixobjectOptionalOn a failing result only, and only when Mestra knows an edit that clears it: the edit’s
nameandinput, exactly as the edit call takes them, so applying it is one op and one undo step. It was tried on a copy of the session first: the copy took it, the rule is met on that element afterwards, and no failure appeared that the current state lacks. That check covers only what the plan can show (the boxes and sizes of the elements); the copy is never rendered, so a failure that only a drawing shows, such as contrast or a picture’s content, is not ruled out. Offered for a text under its type floor (type-min), which getsset_textwith the size that meets it; for a legal line under the legal size (rule-legal-size), which getsset_textwithparasnaming its paragraphs under the limit and the size that meets it; and for an element outside the safe area (crs-safe-area), which getsmove_unitto the nearest place that puts the element, its lockup and the units grouped with it inside the safe area (none when they are together bigger than it). Its numbers are in the edit’s own units, page units for a place and points for a size. It is computed on the state the answer shows: apply it to that state, not a later one. A master gets none (its type size is only ever a warning), and neither does a result judged on an earlier state (atisstale). This is not the answer’sfixes, which lists what Mestra already did on its own.Show child attributesHide child attributes
namestringRequiredAn edit the apply call takes, such as
set_textormove_unit.inputobjectRequiredThe edit’s input.
refusedstringRequiredA refusal code, or empty when the checkpoint was restored.
detailstringRequiredRefs, field names and numbers; never copy.
limitobjectRequiredNullableThe bound a refusal ran into.
noChangebooleanRequiredlabelstringRequiredThe checkpoint the session stands on.
Errors
| Status | Code | Meaning |
|---|---|---|
400 | “Send the editing session’s id in X-Mestra-Edit-Session.” ( | |
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
404 | session_gone | “This editing session has ended. Reopen the size.” (code |
409 | api_off |
|
503 | editor_unavailable | “The editor isn’t available right now.” (code |
Retrieve the check of a size being edited
Checks the open session’s current design against the rules. Send the session id in X-Mestra-Edit-Session. The body is optional. With {"render": true} the size is also drawn and the full rule gate and the screen spec run on the drawing, so the answer adds standIns, lossy, hash and current; without it only the boxes are judged and those are not sent. A drawing the worker refuses for what the design holds is not a failure to check: the answer still comes, with a failing row of source render and code cannot_draw whose detail is the worker’s own code when it gave one (lossy, asset-type, font, …; lossy in the answer is then true). An edit made meanwhile never waits for the drawing; a drawing of a state the session has moved on from is dropped (current: false). Needs the Designs · Read permission.
Headers
X-Mestra-Edit-SessionstringRequiredThe session id the open call answered. It travels in this header, never in the path.
Body parameters (optional)
renderbooleanOptionalDraw the plan and judge the drawing.
Returns
The plan’s check.
An object with:
checkobjectRequiredThe plan’s check.
resultsis every rule the check judged, with the number it measured; a client that gets none shows the failures and warnings alone.Show child attributesHide child attributes
failuresarray of stringsRequiredwarningsarray of stringsRequiredobjectiveintegerRequiredresultsarray of objectsOptionalShow child attributesHide child attributes
sourcestringRequiredbrandfor the brand’s rules,specfor the screen spec.Possible values
brandspeccodestringRequiredrefstringOptionalNullableThe element the rule judged, or null for a whole-size rule.
passbooleanRequiredmeasurednumberOptionalNullablelimitnumberOptionalNullableunitstringOptionalNullablePossible values
ptpxmmratiosharewordsnullatstringRequiredWhat the result was judged on: the drawing, the plan’s boxes, or an earlier state that an edit has since changed.
Possible values
renderplanstalefixobjectOptionalOn a failing result only, and only when Mestra knows an edit that clears it: the edit’s
nameandinput, exactly as the edit call takes them, so applying it is one op and one undo step. It was tried on a copy of the session first: the copy took it, the rule is met on that element afterwards, and no failure appeared that the current state lacks. That check covers only what the plan can show (the boxes and sizes of the elements); the copy is never rendered, so a failure that only a drawing shows, such as contrast or a picture’s content, is not ruled out. Offered for a text under its type floor (type-min), which getsset_textwith the size that meets it; for a legal line under the legal size (rule-legal-size), which getsset_textwithparasnaming its paragraphs under the limit and the size that meets it; and for an element outside the safe area (crs-safe-area), which getsmove_unitto the nearest place that puts the element, its lockup and the units grouped with it inside the safe area (none when they are together bigger than it). Its numbers are in the edit’s own units, page units for a place and points for a size. It is computed on the state the answer shows: apply it to that state, not a later one. A master gets none (its type size is only ever a warning), and neither does a result judged on an earlier state (atisstale). This is not the answer’sfixes, which lists what Mestra already did on its own.Show child attributesHide child attributes
namestringRequiredAn edit the apply call takes, such as
set_textormove_unit.inputobjectRequiredThe edit’s input.
standInsarray of stringsOptionalOnly with
render: the families drawn as stand-ins because the brand and pack hold no face for them.lossybooleanOptionalOnly with
render: the drawing holds something the apps can’t carry back.hashstringOptionalOnly with
render: the plan hash of the state that was drawn and measured.currentbooleanOptionalOnly with
render: false when the session moved on while the drawing ran, so the drawing was dropped andcheckis the current state’s as it stands.
Errors
| Status | Code | Meaning |
|---|---|---|
400 | “Send the editing session’s id in X-Mestra-Edit-Session.” ( | |
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
404 | session_gone | “This editing session has ended. Reopen the size.” (code |
409 | api_off |
|
502 | render_failedcheck_unavailable | “The size couldn’t be drawn just now. Try again.” (code |
503 | editor_unavailable | “The editor isn’t available right now.” (code |
Retrieve a picture of a size being edited
Draws the open session’s current design and answers the picture with its check, so you can see the result of your edits before you save. Send the session id in X-Mestra-Edit-Session; there is no body. The picture is a PNG in image.data (base64), at most 1568 pixels on its long side, with its own width and height. It is the drawing the render check makes: a design already drawn is answered again without drawing it a second time, and an edit made meanwhile never waits for it. current: false says the session moved on while it was drawn, so the picture is of an earlier state. Works on a size and on a master. A design the preview worker cannot draw for its effects (too much filter work) is answered 409 with code too_heavy and the check, whose results hold a failing row with source render and code too_heavy (no numbers: the worker gives none); the same row is in POST /edit/check with render. Needs the Designs · Read permission.
Headers
X-Mestra-Edit-SessionstringRequiredThe session id the open call answered. It travels in this header, never in the path.
Returns
The drawing and its check.
An object with:
checkobjectRequiredThe plan’s check.
resultsis every rule the check judged, with the number it measured; a client that gets none shows the failures and warnings alone.Show child attributesHide child attributes
failuresarray of stringsRequiredwarningsarray of stringsRequiredobjectiveintegerRequiredresultsarray of objectsOptionalShow child attributesHide child attributes
sourcestringRequiredbrandfor the brand’s rules,specfor the screen spec.Possible values
brandspeccodestringRequiredrefstringOptionalNullableThe element the rule judged, or null for a whole-size rule.
passbooleanRequiredmeasurednumberOptionalNullablelimitnumberOptionalNullableunitstringOptionalNullablePossible values
ptpxmmratiosharewordsnullatstringRequiredWhat the result was judged on: the drawing, the plan’s boxes, or an earlier state that an edit has since changed.
Possible values
renderplanstalefixobjectOptionalOn a failing result only, and only when Mestra knows an edit that clears it: the edit’s
nameandinput, exactly as the edit call takes them, so applying it is one op and one undo step. It was tried on a copy of the session first: the copy took it, the rule is met on that element afterwards, and no failure appeared that the current state lacks. That check covers only what the plan can show (the boxes and sizes of the elements); the copy is never rendered, so a failure that only a drawing shows, such as contrast or a picture’s content, is not ruled out. Offered for a text under its type floor (type-min), which getsset_textwith the size that meets it; for a legal line under the legal size (rule-legal-size), which getsset_textwithparasnaming its paragraphs under the limit and the size that meets it; and for an element outside the safe area (crs-safe-area), which getsmove_unitto the nearest place that puts the element, its lockup and the units grouped with it inside the safe area (none when they are together bigger than it). Its numbers are in the edit’s own units, page units for a place and points for a size. It is computed on the state the answer shows: apply it to that state, not a later one. A master gets none (its type size is only ever a warning), and neither does a result judged on an earlier state (atisstale). This is not the answer’sfixes, which lists what Mestra already did on its own.Show child attributesHide child attributes
namestringRequiredAn edit the apply call takes, such as
set_textormove_unit.inputobjectRequiredThe edit’s input.
standInsarray of stringsRequiredThe families drawn as stand-ins because the brand and pack hold no face for them.
lossybooleanRequiredThe drawing holds something the apps can’t carry back.
hashstringRequiredThe plan hash of the state that was drawn.
currentbooleanRequiredFalse when the session moved on while the drawing ran: the drawing is of an earlier state and
checkis the current state’s as it stands.imageobjectRequiredShow child attributesHide child attributes
mimestringRequiredPossible values
image/pngwidthintegerRequiredheightintegerRequireddatastringRequiredThe PNG, base64.
Errors
| Status | Code | Meaning |
|---|---|---|
400 | “Send the editing session’s id in X-Mestra-Edit-Session.” ( | |
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
404 | session_gone | “This editing session has ended. Reopen the size.” (code |
409 | api_offtoo_heavy |
|
502 | render_failedcheck_unavailable | “The size couldn’t be drawn just now. Try again.” (code |
503 | editor_unavailable | “The editor isn’t available right now.” (code |
Update a size with its edits
Saves the open session’s design as the size’s file. Send the session id in X-Mestra-Edit-Session and the sceneHash the session holds (the open call’s, or the last save’s) in If-Match. Send {"idempotencyKey": "<a UUID you make>"} to make the save safe to retry: if the answer is lost, send the same request again and you get the first save’s answer, even when the editing session has ended in the meantime, and nothing is saved twice. Use a new key for each save. The design is drawn, then the size’s files are replaced in one step, and the edit joins the run’s review as an edited round when the run is the review’s latest. Saving is free. A server run made under the campaign’s current approved rules in rules mode publishes on Can publish alone until its first saved edit; after it the whole run (not just the edited size) needs Can publish without review, like a run made in an app, and the run’s publications still queued or running at that moment are cancelled so a person at that level can queue them again. A design that uses a missing font or picture, or an effect the drawing cannot keep, is refused and nothing is saved. Saving a size sends the size.edited event. Needs the Designs · Write permission.
A master is saved the same way, with the session Start editing a master answered. If-Match is the master’s version number: the ifMatch of the open answer, or of your last save. The save draws the master, checks it against the brand rules and stores it as the master’s next version, which new runs use; the version it was opened on stays as it was. The answer says version (the new number), ifMatch (the same number, for the next save), unchanged (true and no new version when the edits left the master as it was), status (checking, ready or not_ready), pull (ready when the master’s app can pull the change, else none), runsKept (how many runs were made from older versions), ruleSets (as when it was opened) and newRuleFailures (the brand rules the master now fails that it did not when opened), with check and label. If the master has a newer version than the one in If-Match (an app or someone else saved it since) nothing is saved and the answer is 412 with code version_changed, latest (that version’s number), by (mestra for a save made here, else the app: indesign, figma, canva or upload) and byName (who saved it, for a save made here; empty for an app’s): open the master again and redo the edits: the same session cannot be saved over a newer version, so sending latest as If-Match on that session is refused with the same 412. idempotencyKey works as for a size.
A new design (a session opened with Start a new design) is saved the same way, and its first save makes the master: its name is the campaign’s and the size it is designed at (Spring - Medium rectangle; with a name a brand’s master has already, ... (2)), its source app is mestra, and it is version 1. Leave out If-Match, or send 0 or draft; any other value is 400 (code if_match). A design with nothing in it (no element, or every one dropped) is 422 (code empty_design), and an organisation that keeps no files 409 (code dont_keep). The answer is a master save’s (version 1, ifMatch 1, status, pull none, …) with master (as the open of a master gives it), campaign, site and sizes (the sizes ticked when it was opened, as the open answered them), so the caller can start a run. The session is then a session on that master at version 1: its next save sends If-Match: 1 and makes version 2. A retry with the same idempotencyKey answers the first save, with the master, and makes no second one.
Headers
X-Mestra-Edit-SessionstringRequiredThe session id the open call answered. It travels in this header, never in the path.
If-MatchstringRequiredWhich state the save was made from, bare or quoted: for a size, the
sceneHashthe session holds (the open call’s, or the last save’s), a scene hash; for a master, the master’s version number as a decimal string (ifMatchof the open answer, or of the last save), such as4.
Body parameters (optional)
idempotencyKeystring (uuid)OptionalA UUID you make for this save. Sending the request again with the same key answers the first save’s result and saves nothing more.
Returns
Saved.
An object with:
sceneHashstringOptionalThe size’s new scene hash; send it as
If-Matchon the next save.fileIdstringOptionalNullableThe new PNG’s file id (a size’s save).
roundintegerOptionalNullableThe review round written, or null when none was.
publicationsintegerOptionalHow many queued publications were moved to the new file and will use this version.
pullstringRequiredA master’s save answers
ready(its app can pull the change) ornone. A size’s:ready: the edit is a round of the run’s review.quiet: the run had no review, so one was made.not_sent: the run was never sent to the review.superseded: another run or a plugin send came later. With the last two the edit is saved and published but writes no round, so a design app’s Pull does not bring it.Possible values
readyquietnot_sentsupersedednonecheckobjectRequiredThe plan’s check.
resultsis every rule the check judged, with the number it measured; a client that gets none shows the failures and warnings alone.Show child attributesHide child attributes
failuresarray of stringsRequiredwarningsarray of stringsRequiredobjectiveintegerRequiredresultsarray of objectsOptionalShow child attributesHide child attributes
sourcestringRequiredbrandfor the brand’s rules,specfor the screen spec.Possible values
brandspeccodestringRequiredrefstringOptionalNullableThe element the rule judged, or null for a whole-size rule.
passbooleanRequiredmeasurednumberOptionalNullablelimitnumberOptionalNullableunitstringOptionalNullablePossible values
ptpxmmratiosharewordsnullatstringRequiredWhat the result was judged on: the drawing, the plan’s boxes, or an earlier state that an edit has since changed.
Possible values
renderplanstalefixobjectOptionalOn a failing result only, and only when Mestra knows an edit that clears it: the edit’s
nameandinput, exactly as the edit call takes them, so applying it is one op and one undo step. It was tried on a copy of the session first: the copy took it, the rule is met on that element afterwards, and no failure appeared that the current state lacks. That check covers only what the plan can show (the boxes and sizes of the elements); the copy is never rendered, so a failure that only a drawing shows, such as contrast or a picture’s content, is not ruled out. Offered for a text under its type floor (type-min), which getsset_textwith the size that meets it; for a legal line under the legal size (rule-legal-size), which getsset_textwithparasnaming its paragraphs under the limit and the size that meets it; and for an element outside the safe area (crs-safe-area), which getsmove_unitto the nearest place that puts the element, its lockup and the units grouped with it inside the safe area (none when they are together bigger than it). Its numbers are in the edit’s own units, page units for a place and points for a size. It is computed on the state the answer shows: apply it to that state, not a later one. A master gets none (its type size is only ever a warning), and neither does a result judged on an earlier state (atisstale). This is not the answer’sfixes, which lists what Mestra already did on its own.Show child attributesHide child attributes
namestringRequiredAn edit the apply call takes, such as
set_textormove_unit.inputobjectRequiredThe edit’s input.
labelstringRequiredThe checkpoint the session stands on.
versionintegerOptionalA master’s save: the new version number (the master’s latest, or the one it already was when
unchanged).unchangedbooleanOptionalA master’s save: true when the edits left the master as it was, so no version was made.
ifMatchintegerOptionalA master’s save: the version number to send as
If-Matchon the next save.statusstringOptionalA master’s save: the master’s brand check of the saved version.
Possible values
checkingreadynot_readyrunsKeptintegerOptionalA master’s save: how many runs were made from older versions of the master.
ruleSetsarray of objectsOptionalA master’s save: each campaign whose current rule set lists a version of the master, as when it was opened. Empty for a key without the Campaigns · Read permission.
Show child attributesHide child attributes
campaignstringOptionalnamestringOptionallistsarray of integersOptionallockedarray of objectsOptionalShow child attributesHide child attributes
elementstringRequiredThe element’s role, such as
logo.minScalenumberRequiredmaxScalenumberRequired
newRuleFailuresarray of stringsOptionalA master’s save: the brand rule codes the saved master fails that the opened one did not.
masterobjectOptionalA new design’s first save: the master it made, as the open of a master answers it (
id,version,latest,name,sourceApp,brand,canPull).Show child attributesHide child attributes
idstringOptionalversionintegerOptionallatestintegerOptionalnamestringOptionalsourceAppstringOptionalbrandstringOptionalcanPullbooleanOptional
campaignstringOptionalA new design’s first save: the campaign it was opened for.
sitestringOptionalA new design’s first save: the brand.
sizesarray of objectsOptionalA new design’s first save: the sizes ticked when it was opened (
key,name,width,height,unit,screenSpec).
Errors
| Status | Code | Meaning |
|---|---|---|
400 | if_match | “Send the editing session’s id in X-Mestra-Edit-Session.” ( |
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
404 | session_gonenot_editable | “This editing session has ended. Reopen the size.” (code |
409 | api_offidempotency_conflictreview_moveddont_keeptoo_heavy |
|
412 | scene_changedversion_changed | “This size changed since you opened it” (code |
422 | stand_incannot_drawempty_designpicture_missing | Nothing was saved. code |
428 | if_match_required |
|
503 | editor_unavailableeditor_busy | code |
List all editable sizes of a run
Says, for each size of a run, whether it can be opened for editing: it has a stored design and the run is tied to a saved master. A server run’s size opens once the run has finished and the size is done; a booking’s run and the run of a dynamic content row never open. sizes adds each size’s sceneHash, the version it was last saved at (null when none was kept). Needs the Designs · Read permission.
Path parameters
idstringRequiredThe run’s id. A run of another organisation is a
404.
Returns
Per-size booleans, keyed by format key.
An object with:
editableobjectRequiredsizesmap of objectsOptionalThe same sizes with the scene hash each was last opened against. A client without it reads
editableand takes the hash as unknown.Show child attributesHide child attributes
editablebooleanOptionalsceneHashstringOptionalNullable
Errors
| Status | Code | Meaning |
|---|---|---|
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
404 | “job not found”: no such run in this organisation (a run of another organisation is as unknown as a missing one). | |
409 | api_off |
|
503 | editor_unavailable | “The editor isn’t available right now.” (code |
Add a picture to a size or master being edited
Keeps a picture for the open session, so a swap_picture edit can then name it. Send the session id in X-Mestra-Edit-Session. The body is the picture’s raw bytes (PNG, JPEG or SVG, at most 25 MiB; an SVG, image/svg+xml, is scanned as a logo is and sized by its viewBox, in a size as in a master or new design) with Content-Type and Content-Length sent, and the {asset} in the path is the SHA-256 of those bytes. The answer is asset (sha256, mime, width, height: send sha256 as the swap_picture edit’s sha256) and created: 201 when the picture is new and 200 when the session or run already held it. For a size it is kept for the run the way a run image is, encrypted and the organisation’s own, and a saved size keeps it. For a master the session holds it until the master is saved, and the save seals it as the picture’s new original in the next version (a session that ends first drops it). A master’s picture has no run canvas to be measured against, so image_too_large is a size’s refusal only. Saving is free. Needs the Designs · Write permission.
Path parameters
assetstringRequiredThe image’s SHA-256, 64 lowercase hex characters, as the scene names it.
Headers
X-Mestra-Edit-SessionstringRequiredThe session id the open call answered. It travels in this header, never in the path.
Body parameters
The request body is image/png.
Returns
The run already held the picture.
An object with:
assetobjectRequiredShow child attributesHide child attributes
sha256stringRequiredmimestringRequiredPossible values
image/pngimage/jpegwidthintegerRequiredheightintegerRequired
createdbooleanRequired
Errors
| Status | Code | Meaning |
|---|---|---|
400 | picture_sumpicture_emptypicture_shortpicture_sizeimage_too_large | “Send the editing session’s id in X-Mestra-Edit-Session.” ( |
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
404 | session_gone | “This editing session has ended. Reopen the size.” (code |
409 | api_offlibrary_off |
|
411 | picture_length | code |
413 | picture_too_big | code |
415 | picture_type | code |
422 | run_images_fullpicture_size | code |
429 | Too many uploads at once. | |
503 | editor_unavailable | “The editor isn’t available right now.” (code |
Start editing a master
Opens one version of a saved master for editing and answers the session: its id, the master’s elements, the check of the design rules and the checkpoint loaded, plus master (its id, the version opened, the latest version, its name, source app, brand and whether its app can pull changes), ifMatch (the latest version number: send it as If-Match on Save), ruleSets (each campaign whose rule set lists this master, with the elements it locks to a range of scales) and copyOverrides (per role, how many campaigns set their own copy). n is a version number or latest. Send the session id in X-Mestra-Edit-Session on every later call, which are the same Update, Check, Preview and Save calls as for a size, and Update also takes the master’s own edits (set_shape, set_opacity, set_role, and verticalAlign, caps and paras on text); Save makes the master’s next version, and answers 412 (version_changed) with the latest version and who made it when the master has a newer one than ifMatch. A session belongs to the key that opened it, ends after an hour unused and is lost if the service restarts: a later call that answers 404 (session_gone) means open the master again. Needs the Designs · Read permission, and a key that opens must also hold a Write permission somewhere: a key whose only permission is Designs · Read cannot open.
Path parameters
idstring (uuid)RequirednstringRequiredA version number, or
latest.
Query parameters
warmstringOptional1opens a warm session, held briefly ahead of a click.Possible values
1
Returns
The session, the identity plan, the composition and its pictures, and the master.
An object with:
sessionstringRequiredThe session id, 32 hex characters.
elementsarray of objectsRequiredThe master’s elements in words, in plan order. Each says its
kind(a picture isimage), itsrole, whether the role is the person’s choice (roleChosen) and what Auto would give it (suggestedRole).Show child attributesHide child attributes
refstringRequiredThe element’s ref, for
ref(orid) in an edit’s input.rolestringRequiredThe element’s role as an edit may send it: lower case, words joined by
_. Empty when it has none.namestringRequiredkindstringRequiredtext,image,shape,grouporvector; empty for an element the design adds.keptbooleanRequiredFalse when the element has been dropped.
frameobjectRequiredThe element’s box in the design’s own units.
Show child attributesHide child attributes
xnumberOptionalynumberOptionalwnumberOptionalhnumberOptional
textstringRequiredNullableA text element’s copy as it stands, paragraphs joined by a line break; null for any other element, and for every element in an answer that refuses an edit (a refusal carries no copy).
rotationnumberOptionalA turned element only (one its master turns): its angle in degrees, as the master holds it. On a size it does not change.
ownFrameobjectOptionalA turned element only, and only when the master stores its own size. The unturned frame its copy sets in, in the design’s own units: the rectangle
frame(the box round it) is the turned box of. It is whatset_frametakes and gives for the element’sx,y,wandh, so send numbers from this, not fromframe. Within about 3 degrees of 45 the size draws the master’s aspect, and this is that frame.Show child attributesHide child attributes
xnumberOptionalynumberOptionalwnumberOptionalhnumberOptional
roleChosenbooleanOptionalA master’s element only. True when the role is the person’s choice; false when it is the one Mestra suggested (Auto), which a later save of the master may suggest differently. A master saved before Mestra kept this answers true for every element.
zintegerOptionalA master’s element only. Its place in the stacking: a higher z is in front. A group’s is its topmost member’s.
groupstringOptionalA master’s element only, and only when it is a member of a group: the group’s ref.
membersarray of stringsOptionalA group’s entry only (
kindisgroup): the refs of its members, back to front. A master’s groups are listed beside its elements, each with the box around its members, soset_orderandungrouphave a ref to name. A master’s nested groups (a clip group’s clip is on one) are listed the same way, each withgroupset to the group or nested group it is under and its members the elements under it; the id is whatset_order,set_rotation,move_unit,scale_unitandungrouptake for it.lookobjectOptionalA master’s element only, and only when it has an effect or a paint. Its look in words:
effectsare the effect types in order (a level’s after the look’s own) andpaintsis how many fills and strokes it has.Show child attributesHide child attributes
effectsarray of stringsOptionalpaintsintegerOptional
suggestedRolestringOptionalA master’s element only. The role Mestra suggests for the element, in the same form as
role: what choosing Auto would give it. For an element whose role is suggested it is its own role.
formatobjectRequiredThe master’s own page as a format: key
master, the master’s name, the page’s width, height and unit (pxfor px and pt,mmfor mm).Show child attributesHide child attributes
keystringOptionalPossible values
masternamestringOptionalwidthnumberOptionalheightnumberOptionalunitstringOptionalPossible values
pxmm
checkobjectRequiredThe plan’s check.
resultsis every rule the check judged, with the number it measured; a client that gets none shows the failures and warnings alone.Show child attributesHide child attributes
failuresarray of stringsRequiredwarningsarray of stringsRequiredobjectiveintegerRequiredresultsarray of objectsOptionalShow child attributesHide child attributes
sourcestringRequiredbrandfor the brand’s rules,specfor the screen spec.Possible values
brandspeccodestringRequiredrefstringOptionalNullableThe element the rule judged, or null for a whole-size rule.
passbooleanRequiredmeasurednumberOptionalNullablelimitnumberOptionalNullableunitstringOptionalNullablePossible values
ptpxmmratiosharewordsnullatstringRequiredWhat the result was judged on: the drawing, the plan’s boxes, or an earlier state that an edit has since changed.
Possible values
renderplanstalefixobjectOptionalOn a failing result only, and only when Mestra knows an edit that clears it: the edit’s
nameandinput, exactly as the edit call takes them, so applying it is one op and one undo step. It was tried on a copy of the session first: the copy took it, the rule is met on that element afterwards, and no failure appeared that the current state lacks. That check covers only what the plan can show (the boxes and sizes of the elements); the copy is never rendered, so a failure that only a drawing shows, such as contrast or a picture’s content, is not ruled out. Offered for a text under its type floor (type-min), which getsset_textwith the size that meets it; for a legal line under the legal size (rule-legal-size), which getsset_textwithparasnaming its paragraphs under the limit and the size that meets it; and for an element outside the safe area (crs-safe-area), which getsmove_unitto the nearest place that puts the element, its lockup and the units grouped with it inside the safe area (none when they are together bigger than it). Its numbers are in the edit’s own units, page units for a place and points for a size. It is computed on the state the answer shows: apply it to that state, not a later one. A master gets none (its type size is only ever a warning), and neither does a result judged on an earlier state (atisstale). This is not the answer’sfixes, which lists what Mestra already did on its own.Show child attributesHide child attributes
namestringRequiredAn edit the apply call takes, such as
set_textormove_unit.inputobjectRequiredThe edit’s input.
sizeDriftarray of stringsRequiredAlways empty for a master.
labelstringRequiredThe first checkpoint,
loaded.masterobjectRequiredShow child attributesHide child attributes
idstring (uuid)RequiredversionintegerRequiredThe version opened.
latestintegerRequiredThe master’s latest version when the session opened.
namestringRequiredsourceAppstringRequiredThe app the master was made in.
brandstringRequiredThe brand’s code.
canPullbooleanRequiredWhether the master’s app has Pull master changes (InDesign and Figma).
ifMatchintegerRequiredlatest: send it asIf-Matchon Save.ruleSetsarray of objectsRequiredEach campaign whose current rule set lists a version of this master, so you know what a size made from it is held to. Empty (
[]) for a key without the Campaigns · Read permission.Show child attributesHide child attributes
campaignstringRequiredThe campaign’s key.
namestringRequiredlistsarray of integersRequiredThe version numbers of this master the campaign’s current rule set lists.
lockedarray of objectsRequiredThe elements the rule set holds to a range of scales; empty when it locks none.
Show child attributesHide child attributes
elementstringRequiredThe element’s role, such as
logo.minScalenumberRequiredmaxScalenumberRequired
copyOverridesobjectRequiredPer role, how many of the brand’s campaigns set their own copy for it: a change to that copy in the master does not reach their sizes. Empty (
{}) for a key without the Campaigns · Read permission.logosarray of objectsRequiredThe brand’s stored logos (empty when it has none): what
add_element’slogo.variantmay name. No bytes:pathis the route that serves the file.Show child attributesHide child attributes
variantstringRequiredPossible values
primaryreversedmimestringRequiredimage/pngorimage/svg+xml.widthintegerRequiredPixels;
0for a vector.heightintegerRequiredPixels;
0for a vector.usablebooleanRequiredWhether
add_elementtakes it: a PNG is, and an SVG whose root has a usableviewBoxis (itswidthandheightare theviewBox’s, rounded;svg-viewboxotherwise, width and height 0).pathstringRequired
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 | “This master can’t be opened in the editor” ( |
500 | The master or its fonts could not be read. | |
503 | editor_unavailable | “The editor isn’t available right now.” (code |
Update a campaign's sizes with one edit
Makes one edit on many sizes of a campaign at once. For each brand (the campaign’s own order, or only the ones in sites), the sizes are those of the brand’s newest run that has files; sizes lists the size keys to edit, or is "all". Each size is opened as an editing session of its own and given the edit, exactly as the open and apply calls do. Nothing is saved: look at the sessions you want, then save them with PUT /edit/sizes. The body is {"campaign", "sites"?, "sizes", "edit": {"name", "input"}, "idempotencyKey"?}; edit.name is one of the edits the apply call takes. The answer lists every size asked for, in results, and each says what became of it in outcome: applied, no_change (nothing moved), refused (with refused, detail, limit and, for a role that matches several elements, candidates; the session stays open so you can try another edit on it), not_editable (the size has nothing stored to edit, the run is not one that can be edited, the brand is not in the campaign or has no run), busy (the editor had no room; try that size again) or failed (with the status and code of the call that failed). A size that is refused or fails does not affect the others. Applied, no-change and refused sizes carry the session and the sceneHash to send as If-Match when saving. With an idempotencyKey, sending the same request again answers the first call’s result with the same sessions and opens nothing more; the same key with a different request is 409. When every size is done within 10 seconds the answer is 200 with the results; otherwise it is 202 with {"operation", "status": "running", "done", "total", "results"}, where results are the sizes finished so far in the order asked, and the work goes on in the background (up to four sizes at a time). Read the operation with GET /edit/sizes/operations/{id} until its status is done. A repeat with the same key while it runs answers the same operation. One change across sizes (POST or PUT /edit/sizes) runs for you at a time: another call while one is running is 409 with code sizes_busy (Another change across sizes is still running. Wait for it to finish, then try again.). If your key is revoked, or you are removed from the organisation, while it runs, the sizes not yet started are listed as failed with status 401. Needs the Designs · Write permission.
Body parameters
campaignstringRequiredThe campaign’s key.
sitesarray of stringsOptionalSite codes to edit. Omit for every brand of the campaign.
sizesone ofRequiredSize keys, or the string
"all"for every size of the brand.One of
arraystringPossible values
alleditobjectRequiredShow child attributesHide child attributes
namestringRequiredOne of the edits the apply call takes.
inputobjectOptional
idempotencyKeystring (uuid)OptionalA UUID you make for this call.
Returns
One result per size asked for, when every size was done within 10 seconds.
An object with:
resultsarray of objectsOptionalShow child attributesHide child attributes
runstringOptionalThe brand’s newest run the size belongs to. Absent when the brand has none.
sitestringRequiredsizestringOptionalThe size’s key. Absent on a result for a whole brand (no run, or not in the campaign).
outcomestringRequiredapplied,no_change(nothing moved),refused(seerefused),not_editable,busy(the editor had no room; try this size again) orfailed(seestatusandcode).Possible values
appliedno_changerefusednot_editablebusyfailedstatusintegerOptionalWith
busyandfailed: the status of the call that did not succeed.codestringOptionalWith
not_editable(not_editable,no_runorsite_not_in_campaign),busyandfailed: the code the call answered.sessionstringOptionalWith
applied,no_changeandrefused: the editing session the size was opened in. Send it inX-Mestra-Edit-Sessionto look at the size or edit it further, and inPUT /edit/sizesto save it.sceneHashstringOptionalWith a session: the scene hash to send as
If-Matchon the first save.labelstringOptionalThe checkpoint the edit made, when it made one.
checkobjectOptionalThe plan’s check.
resultsis every rule the check judged, with the number it measured; a client that gets none shows the failures and warnings alone.Show child attributesHide child attributes
failuresarray of stringsRequiredwarningsarray of stringsRequiredobjectiveintegerRequiredresultsarray of objectsOptionalShow child attributesHide child attributes
sourcestringRequiredbrandfor the brand’s rules,specfor the screen spec.Possible values
brandspeccodestringRequiredrefstringOptionalNullableThe element the rule judged, or null for a whole-size rule.
passbooleanRequiredmeasurednumberOptionalNullablelimitnumberOptionalNullableunitstringOptionalNullablePossible values
ptpxmmratiosharewordsnullatstringRequiredWhat the result was judged on: the drawing, the plan’s boxes, or an earlier state that an edit has since changed.
Possible values
renderplanstalefixobjectOptionalOn a failing result only, and only when Mestra knows an edit that clears it: the edit’s
nameandinput, exactly as the edit call takes them, so applying it is one op and one undo step. It was tried on a copy of the session first: the copy took it, the rule is met on that element afterwards, and no failure appeared that the current state lacks. That check covers only what the plan can show (the boxes and sizes of the elements); the copy is never rendered, so a failure that only a drawing shows, such as contrast or a picture’s content, is not ruled out. Offered for a text under its type floor (type-min), which getsset_textwith the size that meets it; for a legal line under the legal size (rule-legal-size), which getsset_textwithparasnaming its paragraphs under the limit and the size that meets it; and for an element outside the safe area (crs-safe-area), which getsmove_unitto the nearest place that puts the element, its lockup and the units grouped with it inside the safe area (none when they are together bigger than it). Its numbers are in the edit’s own units, page units for a place and points for a size. It is computed on the state the answer shows: apply it to that state, not a later one. A master gets none (its type size is only ever a warning), and neither does a result judged on an earlier state (atisstale). This is not the answer’sfixes, which lists what Mestra already did on its own.Show child attributesHide child attributes
namestringRequiredAn edit the apply call takes, such as
set_textormove_unit.inputobjectRequiredThe edit’s input.
refusedstringOptionalWith
refused: the refusal code.detailstringOptionalRefs, field names and numbers; never copy.
limitobjectOptionalWith
refused: the bound the edit ran into.candidatesarray of objectsOptionalWith
refusedambiguous_role: every kept element that has the role.Show child attributesHide child attributes
refstringRequiredrolestringRequirednamestringRequired
elementsarray of objectsOptionalWith a session: the size’s elements after the edit, in plan order, as the apply answer lists them, so a session can be shown without another call.
Show child attributesHide child attributes
refstringRequiredThe element’s ref, for
ref(orid) in an edit’s input.rolestringRequiredThe element’s role as an edit may send it: lower case, words joined by
_. Empty when it has none.namestringRequiredkindstringRequiredtext,image,shape,grouporvector; empty for an element the design adds.keptbooleanRequiredFalse when the element has been dropped.
frameobjectRequiredThe element’s box in the design’s own units.
Show child attributesHide child attributes
xnumberOptionalynumberOptionalwnumberOptionalhnumberOptional
textstringRequiredNullableA text element’s copy as it stands, paragraphs joined by a line break; null for any other element, and for every element in an answer that refuses an edit (a refusal carries no copy).
rotationnumberOptionalA turned element only (one its master turns): its angle in degrees, as the master holds it. On a size it does not change.
ownFrameobjectOptionalA turned element only, and only when the master stores its own size. The unturned frame its copy sets in, in the design’s own units: the rectangle
frame(the box round it) is the turned box of. It is whatset_frametakes and gives for the element’sx,y,wandh, so send numbers from this, not fromframe. Within about 3 degrees of 45 the size draws the master’s aspect, and this is that frame.Show child attributesHide child attributes
xnumberOptionalynumberOptionalwnumberOptionalhnumberOptional
roleChosenbooleanOptionalA master’s element only. True when the role is the person’s choice; false when it is the one Mestra suggested (Auto), which a later save of the master may suggest differently. A master saved before Mestra kept this answers true for every element.
zintegerOptionalA master’s element only. Its place in the stacking: a higher z is in front. A group’s is its topmost member’s.
groupstringOptionalA master’s element only, and only when it is a member of a group: the group’s ref.
membersarray of stringsOptionalA group’s entry only (
kindisgroup): the refs of its members, back to front. A master’s groups are listed beside its elements, each with the box around its members, soset_orderandungrouphave a ref to name. A master’s nested groups (a clip group’s clip is on one) are listed the same way, each withgroupset to the group or nested group it is under and its members the elements under it; the id is whatset_order,set_rotation,move_unit,scale_unitandungrouptake for it.lookobjectOptionalA master’s element only, and only when it has an effect or a paint. Its look in words:
effectsare the effect types in order (a level’s after the look’s own) andpaintsis how many fills and strokes it has.Show child attributesHide child attributes
effectsarray of stringsOptionalpaintsintegerOptional
suggestedRolestringOptionalA master’s element only. The role Mestra suggests for the element, in the same form as
role: what choosing Auto would give it. For an element whose role is suggested it is its own role.
Errors
| Status | Code | Meaning |
|---|---|---|
400 | master_only | A field that isn’t right: |
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
404 | campaign_not_found | “That campaign doesn’t exist.” (code |
409 | api_offidempotency_conflictsizes_busy |
|
503 | editor_unavailable | “The editor isn’t available right now.” (code |
Update many sizes with their edits
Saves several open editing sessions, one after another, each as PUT /edit/save saves one: the design is drawn, the size’s files are replaced, the edit joins the run’s review, and the size.edited event is sent. The body is {"sizes": [{"session", "ifMatch"}], "idempotencyKey"?}, where each session is the id an open call or POST /edit/sizes answered and ifMatch is the sceneHash it holds. Each save stands on its own: the answer lists every session in results, with outcome saved (and sceneHash, round, pull and fileId) or failed (with the status and code the single save would have answered, such as scene_changed, session_gone, stand_in, lossy or editor_busy). A failed size changes nothing and the others are still saved. With an idempotencyKey every save is made under it, as the single save is, so sending the same request again answers the saves that were made, writes no second round, and saves the sizes that failed. When every save is done within 10 seconds the answer is 200 with the results; otherwise it is 202 with an operation, read with GET /edit/sizes/operations/{id} as for POST /edit/sizes; the saves go on in the background, up to four at a time, and each is kept as it is made. One change across sizes (POST or PUT /edit/sizes) runs for you at a time: another call while one is running is 409 with code sizes_busy; a revoked key stops the saves not yet started (listed failed, status 401). Needs the Designs · Write permission.
Body parameters
sizesarray of objectsRequiredShow child attributesHide child attributes
sessionstringRequiredifMatchstringOptionalThe
sceneHashthe session holds.
idempotencyKeystring (uuid)OptionalA UUID you make for this call.
Returns
One result per session, in the order sent, when every save was done within 10 seconds.
An object with:
resultsarray of objectsOptionalShow child attributesHide child attributes
sessionstringRequiredThe session as it was sent.
outcomestringRequiredPossible values
savedfailedstatusintegerRequiredThe status the single save would have answered.
codestringOptionalWith
failed: the save’s own error code, such asscene_changed,session_gone,stand_in,lossy,editor_busyorif_match_required.sceneHashstringOptionalWith
saved: the size’s new scene hash, theifMatchof its next save.roundintegerOptionalNullableThe review round written, or null when none was.
pullstringOptionalPossible values
readyquietnot_sentsupersedednonefileIdstringOptionalNullableversionintegerOptionalA master session only: the master’s new version.
Errors
| Status | Code | Meaning |
|---|---|---|
400 | A field that isn’t right: | |
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
409 | api_offsizes_busy |
|
503 | editor_unavailable | “The editor isn’t available right now.” (code |
Retrieve a slow edit or save across sizes
Reads an edit or save across sizes that answered 202. The answer is {"operation", "kind", "status", "done", "total", "results"}: status is running or done, and results are the sizes finished so far in the order they were asked, each final once listed. When done equals total the status is done and the results are the same as the 200 of the call would have been. Only the organisation and user that started the call can read it; anyone else, and an operation that has ended, are 404 with code operation_gone. Needs the Designs · Write permission.
Path parameters
idstringRequiredThe operation id a
202fromPOST /edit/sizesorPUT /edit/sizesanswered.
Returns
The operation, running or done.
An object with:
operationstringRequiredThe operation’s id: random, and not a session id. Read it at
GET /edit/sizes/operations/{id}.kindstringRequiredWhich call this is:
edit(POST /edit/sizes; each result is anEditSizeResult) orsave(PUT /edit/sizes; each result is aSaveSizeResult).Possible values
editsavestatusstringRequiredPossible values
runningdonedoneintegerRequiredHow many results are listed.
totalintegerRequiredHow many sizes (or sessions) the call has.
resultsarray of objectsRequiredThe results listed so far, in the order asked. A listed result is final. Each is an
EditSizeResultfor an edit and aSaveSizeResultfor a save.
Errors
| Status | Code | Meaning |
|---|---|---|
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
404 | operation_gone | “That operation has ended, or it isn’t one of yours.” (code |
409 | api_off |
|
503 | editor_unavailable | “The editor isn’t available right now.” (code |
Start a design from blank
Starts a design from a blank page and answers the session. Send campaign (a campaign’s key), sizes (the campaign’s size keys ticked for the design’s first run; left out, every size of the campaign for the brand, and [] ticks none) and, to pick the page the design is drawn at, designAt: {"format": "<one of the ticked sizes>"} or {"custom": {"w": 1080, "h": 1920, "unit": "px"}} (px or mm; each side from 1 to 20000). Without designAt the page is the ticked size whose shape is the middle one of the set; of equal ones the larger. site names the brand of a campaign that has several (the first is used without it). With campaign set to no-campaign the design belongs to no campaign: site (a brand’s code) is required (400 site_required, unknown_site), sizes are the organisation’s own sizes (format keys; left out, none are ticked; an unknown key is 400 unknown_format, the field is sizes[i]) and customSizes are typed sizes, [{"w": 640, "h": 480, "unit": "px"}] (px or mm), each made a format of the organisation if it has none like it and ticked with the rest; customSizes with a real campaign is refused (field customSizes). A typed size sent as designAt.custom that is also in customSizes is drawn as that size’s format (designAt then answers its format). At least one size, typed size or custom page is needed (sizes_required). The page takes that size’s safe area as its margins. The answer is the same as for Start editing a master, with draft: true, master: null and ifMatch: null (nothing is stored yet), plus sizes (each ticked size: key, name, width, height, unit and its screenSpec, or null) and designAt (the page that was used, in the form you send it). Send the session id in X-Mestra-Edit-Session on every later call (Update, Check, Preview and the picture upload work as for a master; an edit that names an element answers unknown-ref while the page is empty). Update takes add_element (kinds text, shape, image, line, polygon, star), place_picture, set_picture, set_adjust, set_mask, set_order, make_group, release_clip, ungroup, set_look, set_paras_paint, set_paras_indent, set_paras_decoration, set_paras_breaks, set_flip, set_rotation and set_shape (with the composition’s own shape fields: radii, cornerStyle, cornerStyles, dash, dashOffset, dashFit, cap, join, miterLimit, gap, stripes, sides, ends, strokeAlign, and polygon and star for a path’s outline), and the master’s own edits set_opacity, set_role, set_text and set_style (see Update a size being edited); Save makes the master (see Save an editing session’s plan as the size’s file). Refusals: 404 unknown_campaign; 400 size_not_in_campaign (the field is sizes[i]), bad_custom_size (the field, with min and max), design_at_not_ticked, sizes_required, unknown_site; 403 wrong_key for a key without the Campaigns · Read permission (the design is made of the campaign’s name and sizes), or, with no campaign, without Brand · Read. Needs the Designs · Write and Campaigns · Read permissions (Brand · Read in place of Campaigns · Read with no campaign). The first save’s answer carries campaign (no-campaign for such a design), site and sizes.
Body parameters
campaignstringRequiredA campaign’s key, or
no-campaignfor a design that belongs to none.sizesarray of stringsOptionalSize (format) keys of the campaign, ticked for the design’s first run; with no campaign, keys of the organisation’s own formats (left out: none). A key twice counts once.
customSizesarray of objectsOptionalOnly with
no-campaign: typed sizes. Each is made a format of the organisation (an existing one of that size is reused) and joins the ticked sizes.Show child attributesHide child attributes
wnumberRequiredhnumberRequiredunitstringOptionalBlank is
px.Possible values
pxmm
designAtobjectOptionalThe page the design is drawn at: exactly one of
formatandcustom. Absent: the ticked size of the middle aspect ratio.Show child attributesHide child attributes
formatstringOptionalOne of the ticked sizes.
customobjectOptionalShow child attributesHide child attributes
wnumberRequiredhnumberRequiredunitstringRequiredPossible values
pxmm
sitestringOptionalThe brand’s code, one of the campaign’s. Absent: the campaign’s first. Required with
no-campaign.
Returns
The session over a blank page.
An object with:
sessionstringRequiredThe session id, 32 hex characters.
draftbooleanRequiredPossible values
truemasteranyRequiredNullableAlways
null: nothing is stored yet.ifMatchanyRequiredNullableAlways
null: there is no version to match.elementsarray of objectsRequiredEmpty on a blank page.
Show child attributesHide child attributes
refstringRequiredThe element’s ref, for
ref(orid) in an edit’s input.rolestringRequiredThe element’s role as an edit may send it: lower case, words joined by
_. Empty when it has none.namestringRequiredkindstringRequiredtext,image,shape,grouporvector; empty for an element the design adds.keptbooleanRequiredFalse when the element has been dropped.
frameobjectRequiredThe element’s box in the design’s own units.
Show child attributesHide child attributes
xnumberOptionalynumberOptionalwnumberOptionalhnumberOptional
textstringRequiredNullableA text element’s copy as it stands, paragraphs joined by a line break; null for any other element, and for every element in an answer that refuses an edit (a refusal carries no copy).
rotationnumberOptionalA turned element only (one its master turns): its angle in degrees, as the master holds it. On a size it does not change.
ownFrameobjectOptionalA turned element only, and only when the master stores its own size. The unturned frame its copy sets in, in the design’s own units: the rectangle
frame(the box round it) is the turned box of. It is whatset_frametakes and gives for the element’sx,y,wandh, so send numbers from this, not fromframe. Within about 3 degrees of 45 the size draws the master’s aspect, and this is that frame.Show child attributesHide child attributes
xnumberOptionalynumberOptionalwnumberOptionalhnumberOptional
roleChosenbooleanOptionalA master’s element only. True when the role is the person’s choice; false when it is the one Mestra suggested (Auto), which a later save of the master may suggest differently. A master saved before Mestra kept this answers true for every element.
zintegerOptionalA master’s element only. Its place in the stacking: a higher z is in front. A group’s is its topmost member’s.
groupstringOptionalA master’s element only, and only when it is a member of a group: the group’s ref.
membersarray of stringsOptionalA group’s entry only (
kindisgroup): the refs of its members, back to front. A master’s groups are listed beside its elements, each with the box around its members, soset_orderandungrouphave a ref to name. A master’s nested groups (a clip group’s clip is on one) are listed the same way, each withgroupset to the group or nested group it is under and its members the elements under it; the id is whatset_order,set_rotation,move_unit,scale_unitandungrouptake for it.lookobjectOptionalA master’s element only, and only when it has an effect or a paint. Its look in words:
effectsare the effect types in order (a level’s after the look’s own) andpaintsis how many fills and strokes it has.Show child attributesHide child attributes
effectsarray of stringsOptionalpaintsintegerOptional
suggestedRolestringOptionalA master’s element only. The role Mestra suggests for the element, in the same form as
role: what choosing Auto would give it. For an element whose role is suggested it is its own role.
formatobjectRequiredThe page as a format: key
master, the campaign’s name, the page’s width, height and unit.Show child attributesHide child attributes
keystringOptionalPossible values
masternamestringOptionalwidthnumberOptionalheightnumberOptionalunitstringOptionalPossible values
pxmm
checkobjectRequiredThe plan’s check.
resultsis every rule the check judged, with the number it measured; a client that gets none shows the failures and warnings alone.Show child attributesHide child attributes
failuresarray of stringsRequiredwarningsarray of stringsRequiredobjectiveintegerRequiredresultsarray of objectsOptionalShow child attributesHide child attributes
sourcestringRequiredbrandfor the brand’s rules,specfor the screen spec.Possible values
brandspeccodestringRequiredrefstringOptionalNullableThe element the rule judged, or null for a whole-size rule.
passbooleanRequiredmeasurednumberOptionalNullablelimitnumberOptionalNullableunitstringOptionalNullablePossible values
ptpxmmratiosharewordsnullatstringRequiredWhat the result was judged on: the drawing, the plan’s boxes, or an earlier state that an edit has since changed.
Possible values
renderplanstalefixobjectOptionalOn a failing result only, and only when Mestra knows an edit that clears it: the edit’s
nameandinput, exactly as the edit call takes them, so applying it is one op and one undo step. It was tried on a copy of the session first: the copy took it, the rule is met on that element afterwards, and no failure appeared that the current state lacks. That check covers only what the plan can show (the boxes and sizes of the elements); the copy is never rendered, so a failure that only a drawing shows, such as contrast or a picture’s content, is not ruled out. Offered for a text under its type floor (type-min), which getsset_textwith the size that meets it; for a legal line under the legal size (rule-legal-size), which getsset_textwithparasnaming its paragraphs under the limit and the size that meets it; and for an element outside the safe area (crs-safe-area), which getsmove_unitto the nearest place that puts the element, its lockup and the units grouped with it inside the safe area (none when they are together bigger than it). Its numbers are in the edit’s own units, page units for a place and points for a size. It is computed on the state the answer shows: apply it to that state, not a later one. A master gets none (its type size is only ever a warning), and neither does a result judged on an earlier state (atisstale). This is not the answer’sfixes, which lists what Mestra already did on its own.Show child attributesHide child attributes
namestringRequiredAn edit the apply call takes, such as
set_textormove_unit.inputobjectRequiredThe edit’s input.
sizeDriftarray of stringsRequiredAlways empty.
labelstringRequiredThe first checkpoint,
loaded.ruleSetsarray of objectsRequiredAlways empty.
copyOverridesobjectRequiredAlways empty.
logosarray of objectsRequiredThe brand’s stored logos (empty when it has none): what
add_element’slogo.variantmay name. No bytes:pathis the route that serves the file.Show child attributesHide child attributes
variantstringRequiredPossible values
primaryreversedmimestringRequiredimage/pngorimage/svg+xml.widthintegerRequiredPixels;
0for a vector.heightintegerRequiredPixels;
0for a vector.usablebooleanRequiredWhether
add_elementtakes it: a PNG is, and an SVG whose root has a usableviewBoxis (itswidthandheightare theviewBox’s, rounded;svg-viewboxotherwise, width and height 0).pathstringRequired
sizesarray of objectsRequiredThe ticked sizes, in the order sent.
Show child attributesHide child attributes
keystringRequirednamestringRequiredwidthnumberRequiredheightnumberRequiredunitstringRequiredscreenSpecobjectRequiredNullableThe size’s screen spec (network, format, viewing distance and what it asks), or
nullwhen it has none.
designAtobjectRequiredThe page the design is drawn at:
{format}or{custom: {w, h, unit}}.
Errors
| Status | Code | Meaning |
|---|---|---|
400 | size_not_in_campaignbad_custom_sizedesign_at_not_tickedsizes_requiredunknown_site | A refused field: |
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
404 | headless_offunknown_campaignnot_editable |
|
409 | api_off |
|
413 | The body is over 64 KB. | |
500 | The page or its fonts could not be read. | |
503 | editor_unavailable | “The editor isn’t available right now.” (code |