API reference
Editing a master
You can change a saved master from your own code. Open a version of the master to start a session, make edits, look at the result, then save. A save makes the master’s next version, and new runs use it. The version you opened stays as it was.
To make a master from a blank page instead, see Starting a design.
This guide builds on Editing a size: sessions, edits, checks, previews and saves work the same way, and the same Designs permission is needed. Read that page first. Here is what differs for a master.
Open a session
curl -X POST https://app.withmestra.com/api/v1/masters/$MASTER/versions/latest/edit \ -H "Authorization: Bearer $MESTRA_TOKEN"The last part of the path is a version number or latest. The answer is a session, as for a size, plus:
master: its id, the version opened, the latest version, its name, its source app, its brand and whether its app can pull changes.ifMatch: the latest version number. Send it asIf-Matchwhen you save.ruleSets: each campaign whose rule set lists this master, with the elements it locks to a range of scales. Empty without the Campaigns · Read permission.copyOverrides: for each role, how many campaigns set their own copy.
Send the session id in the X-Mestra-Edit-Session header on every later call. A session belongs to the key that opened it. It ends after an hour unused, and it is lost if the service restarts. A call that then answers 404 with session_gone means open the master again.
Make edits
Use POST /api/v1/edit/apply, with the element’s ref or its role when exactly one kept element has it. All the edits for a size work on a master. A master also takes these:
set_role{"ref": "...", "role": "headline"}sets an element’s role toheadline,subhead,body,cta,legal,logo,icon,photo,backgroundordecorative, ornullfor Auto. It takesref, notrole, to address the element.carriedin the answer names each element that joined or left a lockup because of it.set_opacity{"ref": "...", "opacity": 0.5}sets a kept element’s opacity, from 0 (clear) to 1 (opaque).set_shape{"ref": "...", "stroke": "#1A2B3C", "strokeWidth": 2, "radius": 8}sets a shape’s stroke colour (a colour of the brand’s palette, or an empty string for none), stroke width and corner radius. Send at least one.set_textalso takesverticalAlign(top,center,bottomorjustify) andcaps(normal,allCaps,smallCapsorcapToSmallCaps).capsgoes on the paragraphs inparas, or on every paragraph.set_stylealso takesparas, so the font goes on those paragraphs alone.
set_opacity and set_shape may send role in place of ref. A colour outside the palette is refused as style-refused. A number out of range is refused as bad-number, with the field in limit. An element that is not a shape is refused as unknown-ref.
drop on a master takes the element out of the master when it is saved. A rotated element moves but is not resized.
Moving a picture’s frame on a master moves the picture with it.
These edits are not part of editing many sizes at once: that answers 400 with master_only.
Upload a picture
Upload as for a size, with PUT /api/v1/edit/assets/{sha} in a master’s session. The session holds the picture until the master is saved. The save keeps it as the picture’s new original in the next version. If the session ends first, the picture is dropped.
Save
curl -X PUT https://app.withmestra.com/api/v1/edit/save \ -H "Authorization: Bearer $MESTRA_TOKEN" \ -H "X-Mestra-Edit-Session: $SESSION" \ -H "If-Match: $IF_MATCH" \ -H "Content-Type: application/json" \ -d '{"idempotencyKey": "6f0c2a4e-8d7b-4c59-9a43-1d2b7e5f9a10"}'If-Match is the master’s version number: the ifMatch of the open answer, or of your last save. If it isn’t a version number, the call answers 400 with the code if_match. idempotencyKey works as for a size.
Mestra draws the master, checks it against the brand rules and stores it as the next version. The answer holds:
version: the new version number.ifMatch: the same number, for your next save.unchanged: true, with no new version, when the edits left the master as it was.status:checking,readyornot_ready.pull:readywhen the master’s app can pull the change, otherwisenone.runsKept: how many runs were made from older versions.ruleSetsandnewRuleFailures: the campaigns that list it, and the brand rules the master now fails that it didn’t when you opened it.
Saving is free. A save needs your organisation to keep files, or it answers 409 with dont_keep. A save made while the master is already being saved answers 409 with busy: try again. A swapped-in picture that is no longer available answers 422 with picture_missing and the ref.
When the master has a newer version
If someone, or an app, saved the master after you opened it, the save answers 412 with the code version_changed. Nothing is written. The answer holds:
latest: the newer version’s number.by:mestrafor a save made here, otherwise the app:indesign,figma,canvaorupload.byName: who saved it, for a save made here. It is empty for an app’s save, and for a key without the Team · Read permission.
Open the master again and redo your edits. The same session can’t be saved over a newer version: sending latest as If-Match on that session is refused with the same 412.