API reference
Editing a size
You can change a size of a finished run from your own code, the way the editor does. Open a size to start a session, make edits, look at the result, then save. Mestra draws every picture on its servers, so you send edits and get a picture back.
This guide is about sizes. To change a saved master, see Editing a master. The @withmestra/sdk package wraps these calls for you. Agents can use the Designs MCP tools.
What you need
- A key with the Designs permission. Read opens, checks and previews. Write makes edits and saves. A key that opens a size must also hold a write permission somewhere, so a key with only Designs · Read cannot open. See Authentication.
- A run whose size can be edited. List them with
GET /api/v1/jobs/{id}/editable: each size says whether it can be opened, andsizesadds itssceneHash. A size can be opened when it has a stored design and the run is tied to a saved master. Otherwise opening answers409with the codenot_editable.
Open a session
curl -X POST https://app.withmestra.com/api/v1/jobs/$RUN/formats/$SIZE/edit \ -H "Authorization: Bearer $MESTRA_TOKEN"The answer holds:
session: the session id.elements: what is in the design, in plan order.check: the check against the design rules.label: the first checkpoint,loaded.sceneHash: send it asIf-Matchwhen you save.
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.
Make edits
curl -X POST https://app.withmestra.com/api/v1/edit/apply \ -H "Authorization: Bearer $MESTRA_TOKEN" \ -H "X-Mestra-Edit-Session: $SESSION" \ -H "Content-Type: application/json" \ -d '{"name": "set_colour", "input": {"role": "headline", "colour": "#ff0000"}}'name is one of 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.
Name the element by ref, or by role when exactly one kept element has that role. (move_unit and scale_unit take id in place of ref.) A role that no element has is refused as unknown_role. A role that several have is refused as ambiguous_role, and candidates lists them by ref, role and name. Nothing is changed.
A refusal is a 200 with refused set, and that edit changes nothing. detail and limit say why. An edit that changed something answers a checkpoint in label (e1, e2 and on); noChange says nothing moved.
To make several edits in one request, send {"edits": [{"name": "...", "input": {...}}, ...]}. Every name is checked first. The edits are made in order and stop at the first refusal. The changes made share one checkpoint.
To go back, POST /api/v1/edit/restore puts the session on a checkpoint: loaded, an e<n> label, current or best.
Some edits are for masters only. On a size, set_opacity, set_shape and set_role answer 400 with the code master_only. On set_text, verticalAlign and caps are refused with bad-input and a detail that starts master_only:, and so is paras on set_style.
Check and preview
POST /api/v1/edit/check judges the current design against the rules. Send {"render": true} to draw it as well. The answer then adds standIns, lossy, hash and current.
POST /api/v1/edit/preview draws the current design. The answer holds a PNG in image.data (base64), with its width and height and the check. The long side is at most 1568 pixels. current: false means you made an edit while it was drawn, so the picture shows an earlier state.
Upload a picture
To use a picture that Mestra doesn’t hold yet, keep it for the session first:
SHA=$(shasum -a 256 photo.png | cut -d' ' -f1)curl -X PUT https://app.withmestra.com/api/v1/edit/assets/$SHA \ -H "Authorization: Bearer $MESTRA_TOKEN" \ -H "X-Mestra-Edit-Session: $SESSION" \ -H "Content-Type: image/png" \ --data-binary @photo.pngThe path holds the SHA-256 of the bytes. The body is the raw PNG or JPEG, up to 25 MiB, and Content-Length must be sent. The answer holds asset (sha256, mime, width, height) and created: 201 for a new picture, 200 when the run already held it. Then edit with swap_picture and the sha256. A size keeps the picture with the run, encrypted and your organisation’s own, and a saved size keeps it.
Refusals include 400 picture_sum (the bytes are not the SHA-256), 411 picture_length, 413 picture_too_big (with max), 415 picture_type, 422 run_images_full (with max) and 429. A 409 library_off means your organisation keeps nothing, so there is nowhere to keep it.
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: $SCENE_HASH" \ -H "Content-Type: application/json" \ -d '{"idempotencyKey": "6f0c2a4e-8d7b-4c59-9a43-1d2b7e5f9a10"}'If-Matchis thesceneHashthe session holds: the open answer’s, or the last save’s. Without it the call answers428withif_match_required.idempotencyKeyis a UUID you make. Use a new one for each save. If you lose the answer, send the same request again: you get the first save’s answer, even if the session has ended, and nothing is saved twice. The same key for a different save answers409withidempotency_conflict.
Mestra draws the size, replaces its files and adds the edit to the run’s review as an edited round, when the run is the review’s latest. Saving is free. The answer holds the new sceneHash (use it as If-Match on the next save), fileId, round and pull. Saving sends the size.edited event.
A save that can’t keep the design is refused with 422 and saves nothing: stand_in (a font or picture is missing), lossy (an effect the drawing can’t keep) or cannot_draw.
When it goes wrong
404withsession_gone. The session ended: it was idle for an hour, Mestra restarted, or it is another person’s. Open the size again and redo the edits. A save you sent with anidempotencyKeycan still be sent again, in case the first one was recorded.412withscene_changed. The size, or the run’s master version, is no longer the one you opened, orIf-Matchis not the session’s. Nothing was written. Open the size again and redo the edits.503witheditor_busy. Try again shortly.Retry-Aftersays when. Nothing was saved.409withreview_moved. A review round arrived while you saved. Save again.
Edit many sizes at once
To make the same edit on many sizes of a campaign, call POST /api/v1/edit/sizes:
{ "campaign": "winter-sale", "sizes": "all", "edit": { "name": "set_copy", "input": { "role": "headline", "text": "Book now" } }, "idempotencyKey": "b3c1e0d2-5a47-4c0e-8f1b-7d9a2e6c4f31"}sizes is a list of size keys or "all". centres limits it to some centres. For each centre, the sizes are those of its newest run that has files. Each size gets a session of its own, and nothing is saved. edit.name is one of the edits above, except the master-only ones.
Each size answers in results with an outcome: applied, no_change, refused, not_editable, busy (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 use when you save.
Look at the sizes you want to keep, then save them with PUT /api/v1/edit/sizes:
{ "sizes": [{ "session": "…", "ifMatch": "…" }], "idempotencyKey": "0e7d4b1a-92c6-4f38-a5d0-3b8c6e2f1d94"}Each save stands on its own and answers saved (with sceneHash, round, pull and fileId) or failed (with the status and code that a single save would have answered). A failed size changes nothing and the others are still saved.
Both calls answer 200 with the results when every size is done within 10 seconds. Otherwise they answer 202 with an operation, {"operation", "status": "running", "done", "total", "results"}, and the work goes on. Read it until status is done:
curl https://app.withmestra.com/api/v1/edit/sizes/operations/$OPERATION \ -H "Authorization: Bearer $MESTRA_TOKEN"results holds the sizes finished so far, in the order you sent them, and each is final once listed. Only the person who started the call can read the operation. Anyone else, or an operation that has ended, gets 404 with operation_gone.
One change across sizes runs at a time for you. Another POST or PUT to /edit/sizes while one runs answers 409 with sizes_busy. Wait for it to finish, then try again.
With an idempotencyKey, sending the same request again answers the first call’s result and opens or saves nothing more.