# Starting a design

Start a design from a blank page, add elements, check it and save it as a master with the API, then start a run from it.

You can start a design from nothing from your own code. Open a new design for a campaign, or for none, add elements, look at the result, then save. The first save makes a master, and you start a run from it.

This guide builds on [Editing a size](https://withmestra.com/docs/api/editing-a-size/) and [Editing a master](https://withmestra.com/docs/api/editing-a-master/): sessions, checks, previews and saves work the same way. Read them first. Here is what differs for a new design. Agents can use the MCP op `sizes.new_design`.

## What you need

- A key with the **Designs · Write** permission, and **Campaigns · Read**. A key without Campaigns · Read is refused with `403` and `wrong_key`, because the design is made of the campaign's name and sizes. See [Authentication](https://withmestra.com/docs/api/authentication/).
- A campaign key, and for a campaign of several brands, the brand's code as `centre`. Or, for a design with no campaign, `no-campaign` and the brand's code as `centre`.

## Open a session

```bash
curl -X POST https://app.withmestra.com/api/v1/designs/new/edit \
  -H "Authorization: Bearer $MESTRA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"campaign": "spring", "sizes": ["mrec", "tall"], "designAt": {"format": "mrec"}}'
```

- `campaign`: the campaign's key.
- `sizes`: the campaign's size keys ticked for the design's first run. Left out, it is every size of the campaign for the brand. `[]` ticks none.
- `designAt`: the page the design is drawn at. Send `{"format": "<one of the ticked sizes>"}` or `{"custom": {"w": 1080, "h": 1920, "unit": "px"}}`. The unit is `px` or `mm`, and each side is from 1 to 20000. Left out, the page is the ticked size whose shape is the middle one of the set. Of equal ones, the larger.
- `centre`: the brand of a campaign that has several. The first is used without it.

### A design with no campaign

Send `"campaign": "no-campaign"`. The design belongs to no campaign, so `centre` is required and `sizes` are keys of your own formats (left out, none). Add typed sizes in `customSizes`:

```bash
curl -X POST https://app.withmestra.com/api/v1/designs/new/edit \
  -H "Authorization: Bearer $MESTRA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"campaign": "no-campaign", "centre": "ESP", "sizes": ["mrec"], "customSizes": [{"w": 300, "h": 250, "unit": "px"}], "designAt": {"custom": {"w": 300, "h": 250, "unit": "px"}}}'
```

`customSizes` is a list of `{"w", "h", "unit"}` (`px` or `mm`, each side 1 to 20,000). Each is made a format of your organisation, or an existing one of that size is reused, and joins the ticked sizes. Use `POST /api/v1/formats/custom` to get a size's format key first. The Campaigns · Read permission isn't needed for `no-campaign` if the key has Designs · Write and Brand · Read. A campaign design needs it as before. See [Starting a run](https://withmestra.com/docs/api/starting-a-run/).

The master from the first save is named `No campaign - <size name>`.

The page takes that size's safe area as its margins. The answer is the same as for a master, with:

- `draft`: `true`.
- `master` and `ifMatch`: `null`, because nothing is stored yet.
- `elements`: empty.
- `sizes`: each ticked size, with its `key`, `name`, `width`, `height`, `unit` and `screenSpec`, or `null`.
- `designAt`: the page that was used, in the form you send it.

Send the session id in the `X-Mestra-Edit-Session` header on every later call.

A refusal names the field. `404` `unknown_campaign`. `400` `size_not_in_campaign` (the field is `sizes[i]`), `bad_custom_size` (with `min` and `max`), `design_at_not_ticked`, `sizes_required` and `unknown_centre`, and with `no-campaign`, `centre_required` (choose a brand) and `bad_custom_size` for a size in `customSizes`.

## Add elements

Use `POST /api/v1/edit/apply`, as for a master. On an empty page, an edit that names an element is refused as `unknown-ref`.

`add_element` puts an element on top of the stacking:

```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": "add_element", "input": {"id": "m1a2b3c4d5e", "kind": "text", "frame": {"x": 40, "y": 30, "w": 600, "h": 120}}}'
```

- `id` is made by you. It reads `m` and ten of `0-9a-z`. Otherwise it is refused as `bad-id`, and `id-taken` when the design already holds it.
- `kind` is `text`, `shape`, `image`, `line`, `polygon` or `star`.
- `frame` is `x`, `y`, `w` and `h` in the page's units. A `text` may leave `h` out, and the box is then one line high. A `line` takes `from` and `to` instead of a frame.
- A `text` takes `text` with its `paragraphs`. A `shape` takes `shape` (`rect`, `ellipse` or `path`) and `fill`. A `polygon` takes `sides`, and a `star` takes `points` and `innerRatio`.
- An `image` names `image` with the `asset` (the SHA-256 of a picture you uploaded into the session), or `logo` with the `variant` of the brand's own logo. The open answer lists the brand's logos. A logo that isn't there is `404` `unknown_logo`.

Colours must be of the brand's palette, or the edit is refused as `style-refused`. A number out of range is refused as `bad-number`, with the field in `limit`.

A new design also takes these edits: `place_picture`, `set_picture`, `set_order`, `make_group`, `ungroup`, `release_clip`, `set_look`, `set_paras_paint`, `set_rotation`, `set_shape`, and the master's own `set_opacity`, `set_role`, `set_text` and `set_style`. An element you added comes out with `drop`. The [API reference](https://withmestra.com/docs/api/) gives every field.

Upload a picture as for a master, with `PUT /api/v1/edit/assets/{sha}`.

## Check and preview

`POST /api/v1/edit/check` and `POST /api/v1/edit/preview` work as for a size. Look at the preview before you save.

## 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 "Content-Type: application/json" \
  -d '{"idempotencyKey": "6f0c2a4e-8d7b-4c59-9a43-1d2b7e5f9a10"}'
```

Leave out `If-Match` for the first save, or send `0` or `draft`. Any other value is `400` with the code `if_match`.

The first save makes the master. Its name is the campaign's and the size it was designed at, such as `Spring - Medium rectangle`. If the brand already has a master with that name, it ends in `(2)`. Its source app is `mestra`, and it is version 1. The answer is a master save's, with `version` 1, `ifMatch` 1, `status` and `pull` set to `none`, plus:

- `master`: the master, as opening a master gives it.
- `campaign`, `centre` and `sizes`: what the design was opened for.

A design with nothing in it is refused with `422` and `empty_design`. An organisation that keeps no files gets `409` and `dont_keep`. Saving is free.

The session is now 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.

## Start a run

Make the sizes with [`POST /api/v1/masters/{id}/runs`](https://withmestra.com/docs/api/) using the master's `id`. It needs the Runs · Write permission, and the master must be `ready`. A master that is still `checking` or `not_ready` answers `409` with `not_ready`. Send `dryRun: true` first to see which sizes it would make, without a charge. A design with no campaign is run with `campaignKey` `no-campaign`, its brand in `centres` and its sizes in `formats` and `customSizes`. See [Starting a run](https://withmestra.com/docs/api/starting-a-run/).

## When it goes wrong

- **`404` with `session_gone`.** The session ended. Open the design again and redo the edits. A save you sent with an `idempotencyKey` can still be sent again.
- **`422` with `empty_design`.** Add an element, then save again.
- **`409` with `dont_keep`.** Your organisation keeps no files, so nothing can be saved.
- **`404` with `headless_off`, or `not_editable` for a Network customer.** Saved masters or the editor aren't available to that organisation.
- **`503` with `editor_unavailable`.** Try again shortly.
