# Editing a master

Open a saved master, change it by element or role, and save it as its next version with the API.

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](https://withmestra.com/docs/api/starting-a-design/).

This guide builds on [Editing a size](https://withmestra.com/docs/api/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

```bash
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 as `If-Match` when 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 to `headline`, `subhead`, `body`, `cta`, `legal`, `logo`, `icon`, `photo`, `background` or `decorative`, or `null` for Auto. It takes `ref`, not `role`, to address the element. `carried` in 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_text` also takes `verticalAlign` (`top`, `center`, `bottom` or `justify`) and `caps` (`normal`, `allCaps`, `smallCaps` or `capToSmallCaps`). `caps` goes on the paragraphs in `paras`, or on every paragraph.
- `set_style` also takes `paras`, 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](https://withmestra.com/docs/api/editing-a-size/#edit-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

```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: $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`, `ready` or `not_ready`.
- `pull`: `ready` when the master's app can pull the change, otherwise `none`.
- `runsKept`: how many runs were made from older versions.
- `ruleSets` and `newRuleFailures`: 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`: `mestra` for a save made here, otherwise the app: `indesign`, `figma`, `canva` or `upload`.
- `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`.
