# Editing a size

Open a size of a run, change it by element or role, check and preview it, and save it with the API, including many sizes at once.

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](https://withmestra.com/docs/api/editing-a-master/). The [`@withmestra/sdk`](https://withmestra.com/docs/developers/sdk/) package wraps these calls for you. Agents can use the Designs [MCP tools](https://withmestra.com/docs/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](https://withmestra.com/docs/api/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, and `sizes` adds its `sceneHash`. A size can be opened when it has a stored design and the run is tied to a saved master. Otherwise opening answers `409` with the code `not_editable`.

## Open a session

```bash
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 as `If-Match` when 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

```bash
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:

```bash
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.png
```

The 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

```bash
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-Match` is the `sceneHash` the session holds: the open answer's, or the last save's. Without it the call answers `428` with `if_match_required`.
- `idempotencyKey` is 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 answers `409` with `idempotency_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`](https://withmestra.com/docs/webhooks/event-types/#sizeedited) 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

- **`404` with `session_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 an `idempotencyKey` can still be sent again, in case the first one was recorded.
- **`412` with `scene_changed`.** The size, or the run's master version, is no longer the one you opened, or `If-Match` is not the session's. Nothing was written. Open the size again and redo the edits.
- **`503` with `editor_busy`.** Try again shortly. `Retry-After` says when. Nothing was saved.
- **`409` with `review_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`:

```json
{
  "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`:

```json
{
  "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`:

```bash
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.
