# Library

The library keeps the finished files of runs, when an owner has turned it on and chosen how long to keep them (30, 90 or 365 days, or Keep everything, which has no time limit). Use it to download a run's files after the fact.

The library keeps the finished files of runs, when an owner has turned it on and chosen how long to keep them (30, 90 or 365 days, or Keep everything, which has no time limit). Use it to download a run's files after the fact.

## The Library run object

The library run object is a run summary plus what the library has kept for it.

- `id` (string, required): The run's id (16 hex characters).
- `campaignKey` (string, required): The campaign the run was for.
- `siteCode` (string, required): The brand the run was for.
- `status` (string, required):  One of: `planning`, `planned`, `failed`, `cancelled`.
- `source` (string, required): The app the run came from; `headless` for a run made on the server from a saved master. One of: `indesign`, `figma`, `canva`, `headless`.
- `createdBy` (string, optional): The creating user's id; omitted when unknown.
- `createdByName` (string, required): The member's name; "Member" when they have none, or "Canva user" on a Canva run; "Removed member" when they have left (or no creator was recorded). Never an email.
- `createdAt` (string (date-time), required): When the run started.
- `runId` (string, optional): The run this belongs to; brands started together share it. Omitted when there is none.
- `appVersion` (string, optional): The app build the run came from; omitted when unknown.
- `formatCounts` (object, required): The run's formats, each counted once - failed, else flagged (any flag), else built.
  - `built` (integer, required): Formats made with no flags.
  - `flagged` (integer, required): Formats made, but with at least one flag worth a look.
  - `failed` (integer, required): Formats that could not be made.
- `hasFiles` (boolean, required): The library keeps files (not just a thumbnail) for the run.
- `notes` (integer, required): How many issues and distinct flags (element flags once per code) the run's kept review notes hold, across its formats.
- `brands` (array of strings, optional): With `grouped=1`: the brand codes of the run's brands.
- `jobIds` (array of strings, optional): With `grouped=1`: the ids of the run's brands, by brand code.
- `files` (integer, required): Kept files, not thumbnails.
- `bytes` (integer, required): Their size, not thumbnails.
- `keptUntil` (string (date-time), required, nullable): When the first of them expires; null under Keep everything.
- `thumbs` (array of objects, required): A thumbnail for each format that has one.
  - `formatKey` (string, required): The format the thumbnail shows.
  - `id` (string (uuid), required): The thumbnail's file id: fetch it with `GET /library/files/{id}`.
- `sourceLink` (object, optional): Where a Canva or Figma run's work lives, until it expires with the run's files.
  - `app` (string, required): `canva` or `figma`: the app the run was made in. One of: `canva`, `figma`.
  - `url` (string (uri), required): A link to the work in that app.
  - `expiresAt` (string (date-time), required, nullable): When the link stops being kept; null under Keep everything.

```json
{
  "id": "string",
  "campaignKey": "string",
  "siteCode": "string",
  "status": "planning",
  "source": "indesign",
  "createdByName": "string",
  "createdAt": "string",
  "formatCounts": {
    "built": 0,
    "flagged": 0,
    "failed": 0
  },
  "hasFiles": false,
  "notes": 0,
  "files": 0,
  "bytes": 0,
  "keptUntil": "string",
  "thumbs": [
    {
      "formatKey": "string",
      "id": "string"
    }
  ]
}
```

## List all library runs

`GET /api/v1/library/runs`

Permission: Runs · Read.

Returns the runs whose finished files the organisation has kept, newest first. It takes the same filters as List all runs. Only runs with at least one kept file (not just a thumbnail) are listed.

### Parameters

- `campaign` (string, optional): Filter by campaign key.
- `site` (string, optional): Filter by brand code.
- `status` (string, optional):  One of: `planning`, `planned`, `failed`, `cancelled`.
- `source` (string, optional): Filter by the app the run came from (`headless` for a run made on the server). One of: `indesign`, `figma`, `canva`, `headless`.
- `outcome` (string, optional): As `/jobs`' outcome. One of: `built`, `flagged`, `failed`.
- `from` (string (date), optional): First UTC day the run was started, inclusive.
- `to` (string (date), optional): Last UTC day the run was started, inclusive.
- `limit` (integer, optional): 1 to 200.
- `offset` (integer, optional):

### Returns

The runs, and how many match in all.

An object with:

- `runs` (array of objects, required):
  - `id` (string, required): The run's id (16 hex characters).
  - `campaignKey` (string, required): The campaign the run was for.
  - `siteCode` (string, required): The brand the run was for.
  - `status` (string, required):  One of: `planning`, `planned`, `failed`, `cancelled`.
  - `source` (string, required): The app the run came from; `headless` for a run made on the server from a saved master. One of: `indesign`, `figma`, `canva`, `headless`.
  - `createdBy` (string, optional): The creating user's id; omitted when unknown.
  - `createdByName` (string, required): The member's name; "Member" when they have none, or "Canva user" on a Canva run; "Removed member" when they have left (or no creator was recorded). Never an email.
  - `createdAt` (string (date-time), required): When the run started.
  - `runId` (string, optional): The run this belongs to; brands started together share it. Omitted when there is none.
  - `appVersion` (string, optional): The app build the run came from; omitted when unknown.
  - `formatCounts` (object, required): The run's formats, each counted once - failed, else flagged (any flag), else built.
    - `built` (integer, required): Formats made with no flags.
    - `flagged` (integer, required): Formats made, but with at least one flag worth a look.
    - `failed` (integer, required): Formats that could not be made.
  - `hasFiles` (boolean, required): The library keeps files (not just a thumbnail) for the run.
  - `notes` (integer, required): How many issues and distinct flags (element flags once per code) the run's kept review notes hold, across its formats.
  - `brands` (array of strings, optional): With `grouped=1`: the brand codes of the run's brands.
  - `jobIds` (array of strings, optional): With `grouped=1`: the ids of the run's brands, by brand code.
  - `files` (integer, required): Kept files, not thumbnails.
  - `bytes` (integer, required): Their size, not thumbnails.
  - `keptUntil` (string (date-time), required, nullable): When the first of them expires; null under Keep everything.
  - `thumbs` (array of objects, required): A thumbnail for each format that has one.
    - `formatKey` (string, required): The format the thumbnail shows.
    - `id` (string (uuid), required): The thumbnail's file id: fetch it with `GET /library/files/{id}`.
  - `sourceLink` (object, optional): Where a Canva or Figma run's work lives, until it expires with the run's files.
    - `app` (string, required): `canva` or `figma`: the app the run was made in. One of: `canva`, `figma`.
    - `url` (string (uri), required): A link to the work in that app.
    - `expiresAt` (string (date-time), required, nullable): When the link stops being kept; null under Keep everything.
- `total` (integer, required): Every run the filters match, limit and offset aside.

### Errors

- 400: As `GET /jobs`' 400.
- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403: “Your role (\<role>) can't \<action>.” (the role is below the route's minimum) or “Choose an organisation first.” (the session has no organisation).
- 409 (`api_off`): `409` with code `api_off` (“Turn on the API in Developer → API and MCP first.”): an owner hasn't turned the API on for this organisation, so no API key works yet. An owner turns it on in Settings, then API.
- 500: “could not list jobs”, “could not read the library” or “could not check token”.
- 501: “The library isn't set up on this server.”

### Example request

```sh
curl --request GET \
  --url https://app.withmestra.com/api/v1/library/runs \
  --header "Authorization: Bearer $MESTRA_TOKEN"
```

## Download a kept file

`GET /api/v1/library/files/{id}`

Permission: Runs · Read.

Downloads one kept file as an attachment, in the type it was saved in. It is never cached. Add `?thumb=1` to show a run's thumbnail inline instead. A file that can't be read part-way ends the connection, so you never receive a truncated file that looks complete.

### Parameters

- `id` (string (uuid), required): The kept file's id. A file of another organisation is a `404`.
- `thumb` (string, optional): `1`: the file is a format's thumbnail, to show inline; any other file is `404`. One of: `1`.

### Returns

The file's bytes.

### Errors

- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403: “Your role (\<role>) can't \<action>.” (the role is below the route's minimum) or “Choose an organisation first.” (the session has no organisation).
- 404: “That file isn't in the library.” (including another organisation's, an expired one, and a file whose stored object is gone).
- 409 (`api_off`): `409` with code `api_off` (“Turn on the API in Developer → API and MCP first.”): an owner hasn't turned the API on for this organisation, so no API key works yet. An owner turns it on in Settings, then API.
- 500: “could not read the library” or “could not check token”.
- 501: “The library isn't set up on this server.”

### Example request

```sh
curl --request GET \
  --url https://app.withmestra.com/api/v1/library/files/string \
  --header "Authorization: Bearer $MESTRA_TOKEN"
```

## Download a run's kept files

`GET /api/v1/library/runs/{jobId}.zip`

Permission: Runs · Read.

Downloads all of a run's kept files in one zip, each as `<format>/<name>`. Images and PDFs are stored as they are; SVGs and InDesign documents are compressed. A file deleted since the zip began is left out; one that can't be read part-way ends the connection.

### Parameters

- `jobId` (string, required): The id of the server run's run for one brand (16 hex characters).

### Returns

The zip.

### Errors

- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403: “Your role (\<role>) can't \<action>.” (the role is below the route's minimum) or “Choose an organisation first.” (the session has no organisation).
- 404: “No files are kept for this run.” (including another organisation's run).
- 409 (`api_off`): `409` with code `api_off` (“Turn on the API in Developer → API and MCP first.”): an owner hasn't turned the API on for this organisation, so no API key works yet. An owner turns it on in Settings, then API.
- 500: “could not read the library” or “could not check token”.
- 501: “The library isn't set up on this server.”

### Example request

```sh
curl --request GET \
  --url https://app.withmestra.com/api/v1/library/runs/string.zip \
  --header "Authorization: Bearer $MESTRA_TOKEN"
```

## Download one size's kept files

`GET /api/v1/library/runs/{jobId}/formats/{file}`

Permission: Runs · Read.

Downloads one size's kept files (not thumbnails) in one zip, flat, each as `<name>`. A size with no kept file is a `404`.

### Parameters

- `jobId` (string, required): The id of the server run's run for one brand (16 hex characters).
- `file` (string, required): The size's format key and `.zip` (`<key>.zip`). A key that matches no kept file, or a name without `.zip`, is a `404`.

### Returns

The zip.

### Errors

- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403: “Your role (\<role>) can't \<action>.” (the role is below the route's minimum) or “Choose an organisation first.” (the session has no organisation).
- 404: “No files are kept for this run.” (including another organisation's run).
- 409 (`api_off`): `409` with code `api_off` (“Turn on the API in Developer → API and MCP first.”): an owner hasn't turned the API on for this organisation, so no API key works yet. An owner turns it on in Settings, then API.
- 500: “could not read the library” or “could not check token”.
- 501: “The library isn't set up on this server.”

### Example request

```sh
curl --request GET \
  --url https://app.withmestra.com/api/v1/library/runs/string/formats/string \
  --header "Authorization: Bearer $MESTRA_TOKEN"
```

## Download a group's kept files

`GET /api/v1/library/groups/{runId}.zip`

Permission: Runs · Read.

Downloads the kept files of every brand run that shares a `runId` in one zip, a folder per brand holding what that brand's own zip holds. Another organisation's runs are never in it. A group with no kept file is a `404`.

### Parameters

- `runId` (string, required): The group's run id (the `runId` its runs were created with).

### Returns

The zip.

### Errors

- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403: “Your role (\<role>) can't \<action>.” (the role is below the route's minimum) or “Choose an organisation first.” (the session has no organisation).
- 404: “No files are kept for this run.” (including another organisation's run).
- 409 (`api_off`): `409` with code `api_off` (“Turn on the API in Developer → API and MCP first.”): an owner hasn't turned the API on for this organisation, so no API key works yet. An owner turns it on in Settings, then API.
- 500: “could not read the library” or “could not check token”.
- 501: “The library isn't set up on this server.”

### Example request

```sh
curl --request GET \
  --url https://app.withmestra.com/api/v1/library/groups/string.zip \
  --header "Authorization: Bearer $MESTRA_TOKEN"
```

## Start editing a size

`POST /api/v1/jobs/{id}/formats/{key}/edit`

Permission: Designs · Read.

Opens one size of a run for editing and answers the session: its id, the size's elements (what each is, where it sits and what it says), the check of the design rules and the checkpoint `loaded`. Send the session id in `X-Mestra-Edit-Session` on every later call. A session belongs to the key that opened it, ends after an hour unused and is lost if the service restarts: a later call that answers `404` (`session_gone`) means open the size again. Only sizes that List all editable sizes of a run marks editable can be opened. Needs the Designs · Read permission, and a key that opens must also hold a Write permission somewhere: a key whose only permission is Designs · Read cannot open.

### Parameters

- `id` (string, required): The run's id. A run of another organisation is a `404`.
- `key` (string, required): The format's key.
- `warm` (string, optional): `1` opens a warm session, held briefly ahead of a click. One of: `1`.

### Returns

The session, the size's format and the plan's check.

An object with:

- `session` (string, required): The session id, 32 hex characters.
- `run` (string, required): The run the size belongs to, as the path named it.
- `size` (string, required): The size's key, as the path named it.
- `elements` (array of objects, required): The design's elements in words, in plan order.
  - `ref` (string, required): The element's ref, for `ref` (or `id`) in an edit's input.
  - `role` (string, required): The element's role as an edit may send it: lower case, words joined by `_`. Empty when it has none.
  - `name` (string, required):
  - `kind` (string, required): `text`, `image`, `shape`, `group` or `vector`; empty for an element the design adds.
  - `kept` (boolean, required): False when the element has been dropped.
  - `frame` (object, required): The element's box in the design's own units.
    - `x` (number, optional):
    - `y` (number, optional):
    - `w` (number, optional):
    - `h` (number, optional):
  - `text` (string, required, nullable): A text element's copy as it stands, paragraphs joined by a line break; null for any other element, and for every element in an answer that refuses an edit (a refusal carries no copy).
  - `rotation` (number, optional): A turned element only (one its master turns): its angle in degrees, as the master holds it. On a size it does not change.
  - `ownFrame` (object, optional): A turned element only, and only when the master stores its own size. The unturned frame its copy sets in, in the design's own units: the rectangle `frame` (the box round it) is the turned box of. It is what `set_frame` takes and gives for the element's `x`, `y`, `w` and `h`, so send numbers from this, not from `frame`. Within about 3 degrees of 45 the size draws the master's aspect, and this is that frame.
    - `x` (number, optional):
    - `y` (number, optional):
    - `w` (number, optional):
    - `h` (number, optional):
  - `roleChosen` (boolean, optional): A master's element only. True when the role is the person's choice; false when it is the one Mestra suggested (Auto), which a later save of the master may suggest differently. A master saved before Mestra kept this answers true for every element.
  - `z` (integer, optional): A master's element only. Its place in the stacking: a higher z is in front. A group's is its topmost member's.
  - `group` (string, optional): A master's element only, and only when it is a member of a group: the group's ref.
  - `members` (array of strings, optional): A group's entry only (`kind` is `group`): the refs of its members, back to front. A master's groups are listed beside its elements, each with the box around its members, so `set_order` and `ungroup` have a ref to name. A master's nested groups (a clip group's clip is on one) are listed the same way, each with `group` set to the group or nested group it is under and its members the elements under it; the id is what `set_order`, `set_rotation`, `move_unit`, `scale_unit` and `ungroup` take for it.
  - `look` (object, optional): A master's element only, and only when it has an effect or a paint. Its look in words: `effects` are the effect types in order (a level's after the look's own) and `paints` is how many fills and strokes it has.
    - `effects` (array of strings, optional):
    - `paints` (integer, optional):
  - `suggestedRole` (string, optional): A master's element only. The role Mestra suggests for the element, in the same form as `role`: what choosing Auto would give it. For an element whose role is suggested it is its own role.
- `format` (object, required):
  - `key` (string, optional):
  - `name` (string, optional): The format's name.
  - `width` (number, optional):
  - `height` (number, optional):
  - `unit` (string, optional):  One of: `px`, `mm`.
- `check` (object, required): The plan's check. `results` is every rule the check judged, with the number it measured; a client that gets none shows the failures and warnings alone.
  - `failures` (array of strings, required):
  - `warnings` (array of strings, required):
  - `objective` (integer, required):
  - `results` (array of objects, optional):
    - `source` (string, required): `brand` for the brand's rules, `spec` for the screen spec. One of: `brand`, `spec`.
    - `code` (string, required):
    - `ref` (string, optional, nullable): The element the rule judged, or null for a whole-size rule.
    - `pass` (boolean, required):
    - `measured` (number, optional, nullable):
    - `limit` (number, optional, nullable):
    - `unit` (string, optional, nullable):  One of: `pt`, `px`, `mm`, `ratio`, `share`, `words`, `null`.
    - `at` (string, required): What the result was judged on: the drawing, the plan's boxes, or an earlier state that an edit has since changed. One of: `render`, `plan`, `stale`.
    - `fix` (object, optional): On a failing result only, and only when Mestra knows an edit that clears it: the edit's `name` and `input`, exactly as the edit call takes them, so applying it is one op and one undo step. It was tried on a copy of the session first: the copy took it, the rule is met on that element afterwards, and no failure appeared that the current state lacks. That check covers only what the plan can show (the boxes and sizes of the elements); the copy is never rendered, so a failure that only a drawing shows, such as contrast or a picture's content, is not ruled out. Offered for a text under its type floor (`type-min`), which gets `set_text` with the size that meets it; for a legal line under the legal size (`rule-legal-size`), which gets `set_text` with `paras` naming its paragraphs under the limit and the size that meets it; and for an element outside the safe area (`crs-safe-area`), which gets `move_unit` to the nearest place that puts the element, its lockup and the units grouped with it inside the safe area (none when they are together bigger than it). Its numbers are in the edit's own units, page units for a place and points for a size. It is computed on the state the answer shows: apply it to that state, not a later one. A master gets none (its type size is only ever a warning), and neither does a result judged on an earlier state (`at` is `stale`). This is not the answer's `fixes`, which lists what Mestra already did on its own.
      - `name` (string, required): An edit the apply call takes, such as `set_text` or `move_unit`.
      - `input` (object, required): The edit's input.
- `sizeDrift` (array of strings, required): Element refs whose stored text sizes differ from the plan's own scaling.
- `label` (string, required): The first checkpoint, `loaded`.
- `sceneHash` (string, required):

### Errors

- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`): `403` for a role below the route's minimum (“Your role (\<role>) can't \<action>.”, or “Choose an organisation first.”), or, for an API key without the permission this call needs, code `wrong_key` with “This key needs the \<Area> · \<Read|Write> permission.” (for example “This key needs the Reviews · Write permission.”), or “This key can't do that.” for a call only the Mestra apps make.
- 404: “job not found” or “format \<key> is not in the job's campaign.”
- 409 (`not_editable`, `api_off`): “This size can't be opened in the editor” (code `not_editable`): no stored plan, the scene was replaced or expired, the run is not pinned to a saved master, or the plan no longer belongs to the size. Or `409` with code `api_off` when the API is off for the organisation.
- 500: The master or its fonts could not be read.
- 503 (`editor_unavailable`): “The editor isn't available right now.” (code `editor_unavailable`).

### Example request

```sh
curl --request POST \
  --url https://app.withmestra.com/api/v1/jobs/string/formats/string/edit \
  --header "Authorization: Bearer $MESTRA_TOKEN"
```

## Update a size being edited

`POST /api/v1/edit/apply`

Permission: Designs · Write.

Makes one edit, or several, on an open session. Send the session id in `X-Mestra-Edit-Session`. The body is `{"name", "input"}`, where `name` is `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` (`field: name`). Send `{"edits": [{"name", "input"}, ...]}` to make several in one request: every name is checked first, the edits are made in order and stop at the first refusal, and the changes made share one checkpoint. Address the element by `ref` (`id` for `move_unit` and `scale_unit`), or send `role` in its place when exactly one kept element has that role: `{"name": "set_colour", "input": {"role": "headline", "colour": "#ff0000"}}`. A role that no kept element has is refused as `unknown_role`; a role several have is refused as `ambiguous_role` with `candidates` listing them by `ref`, `role` and `name`, and nothing is applied (a batch is refused whole). A refusal is a `200` with `refused` set and nothing applied for that edit. An edit that changed something is checkpointed `e1`, `e2`, ... in `label`; `noChange` says nothing moved. Needs the Designs · Write permission.

**Making the design itself, on a master or a new design** (a session opened with Start editing a master, or with Start a new design), the session also takes these, which change the composition and never a size: `add_element` `{"id": "m1a2b3c4d5e", "kind": "text", "frame": {"x": 40, "y": 30, "w": 600, "h": 120}}` adds an element on top of the stacking (or on top inside the group `parent`), where `id` is made by the caller and reads `m` and ten of `0-9a-z` (`bad-id` when it does not, `id-taken` when the composition holds it), `kind` is `text`, `shape` (`shape` is `rect`, `ellipse` or `path`) or `image`, and `frame` is `x`, `y`, `w`, `h` in the page's units; a `text` takes `text` `{"paragraphs": [...]}` (each paragraph the composition's own: `content`, `font`, `size`, `leading`, `tracking`, `align`, `fill`, `capitalization` and the like, each left out one taking the brand's face, the palette's darkest colour, left alignment, a size that sets one line in the frame and leading 1.2 times it), a `shape` takes `fill` (a colour of the brand's palette, else the brand's first colour) and, for a `rect`, `radius` (0 to half the shorter side of the frame, as `set_shape`'s: `bad-number` with the field in `limit` outside it, `bad-input` on an ellipse or any other kind) and, for a `path`, `radius` too (0 to 20000, the renderer's side limit: it rounds the corners of each closed subpath, and a corner is limited per vertex as it is drawn; `bad-number` with the field in `limit` outside it, `bad-input` for a path with no closed subpath), and for `path` the outline as `path` (the composition's own: subpaths `{closed, points: [{x, y, in?, out?}]}` as fractions of the frame, with `fillRule` `nonzero` or left out for even-odd; `bad-input` with `limit.field` `path` without one) and for an `ellipse` optionally `arc` `{start, end, inner}` (degrees clockwise from +x, `inner` the hole as a fraction of the radius; `bad-number` with the field when out of range), an `image` names `image` `{"asset": sha256}` of a picture uploaded into the session (or the organisation's) and is placed to cover its frame, or `logo` `{"variant": "primary"}` for the brand's own logo, a PNG or an SVG, which is added as a picture with the role `logo` (`unknown_logo` `404` when there is none; an SVG is placed as an SVG picture whose size is its `viewBox`, each side rounded to a whole number from 1 to 100000, and `svg-viewbox` `422` with `field` `logo.variant` refuses one whose root has no `viewBox` of four finite numbers with a width and height above 0, or a side outside that range; `logo_format` `422` for a file that cannot be read as a picture). `role` is optional: without one the element is saved with the role Mestra suggests, and its `roleChosen` says false until one is chosen. `set_order` `{"ref": ..., "to": "front" | "back" | "forward" | "backward" | {"above": ref}}` moves an element, or a group whole, in the stacking among its siblings (the other members of its group, or the other elements and groups), changing z and nothing else; `order-split` refuses an order that would take a member out of its group. `ref` may also be a nested group's id (a group inside a group; the elements list gives each one an entry of its own, with `group` the group or nested group it is under): the elements under it move together among its siblings, the other units of the group or nested group it is under, in one undo step, and a clip group's frame stays its bottom member (`clip-frame-back`). `{"above": ref}` names a sibling; an element or nested group that exists but is not one (one of the nested group's own members, or something outside its group) is `order-split`, and an id that is none of them is `unknown-ref`. `make_group` `{"id": ..., "refs": [...]}` makes a group of elements (`already-grouped` for one that is in a group; members apart in the stacking are brought together at the topmost one's place; a `clip` is refused as `not-supported`) and `ungroup` `{"ref": group}` dissolves one (`group-holds` for a group that has an opacity, fade, look or nested group of its own). `ref` may be a nested group's id: that nested group alone goes, its elements stay where they are in the group it was under (z is not changed) and any nested group under it moves up with them; one with an opacity, fade, look, mask or clip of its own is `group-holds` (release a clip with `release_clip` first). An element a session added is removed with `drop`. Every answer after the first of these carries `comp`, the working composition as a change to the one the open answer sent: `upsert` (each element that is new or changed, as the composition holds it), `remove` (ids that are gone) and `groups` (all of them); a restore carries it too. Each element in `elements` says its `z`, the `group` it is in when it is in one and, when it has effects or paints, its `look` in words (`{"effects": [type...], "paints": n}`); each group is an entry of its own (`kind` `group`, its `members`, the box around them and the `z` of its topmost member), the ref `set_order` and `ungroup` take. `set_look` `{"ref": ..., "look": {...}}` replaces an element's whole look with the composition's own (`blend`, `effects`, `fills`, `stroke`, `strokeWidth`, `strokeAlign`, `strokeOver`, the text stroke's `strokeDash`, `strokeDashOffset`, `strokeCap`, `strokeJoin` and `strokeMiterLimit`, `arc`, `levels` with `fill`, `stroke` and `content`); an empty `look` removes it, and nothing but that element's `look` changes. It is checked before it is written and refused with `limit.field` naming the field of the look (`look.effects[1]`, `look.levels.fill.effects[0]`, `look.fills[0]`, `look.blend`): `too-many-effects` for more than 8 effects in a look or level (`limit.max` 8, `measured`) or more than 64 in the design (`limit.field` `effects`, `max` 64, `measured` the total it would have; a progressive blur and a glass each count 8, and a look that lowers a total already over is let through), `glass-conflict` for a glass beside a background blur or a `linear-burn` or `linear-dodge` blend, or on a level (a level has no glass or background blur), and `bad-look` for anything else the composition refuses, an unknown field, or `picture`, `notes` and `reach` (the server's, for a look drawn from a saved picture: replacing such a look drops the picture). `set_shape` also takes the composition's own shape fields, each only when sent and `null` clearing it, all written to the composition together: `radii` `[topLeft, topRight, bottomRight, bottomLeft]` (0 to half the shorter side), `cornerStyle` (`rounded`, `bevel`, `inset`, `inverse` or `fancy`, for every corner), `cornerStyles` (four of those, one per corner in `radii`'s order, `null` for every corner rounded; sent with `cornerStyle` it is refused as `bad-input`, `limit` `{"field": "cornerStyles"}`; side weights go with no cut corner), `dash` (at most 16 lengths), `dashOffset`, `dashFit`, `cap` (`butt`, `round`, `square`), `join` (`miter`, `round`, `bevel`), `miterLimit` (1 to 100), `gap` (a colour of the brand's palette, `style-refused` otherwise), `stripes` (at most 8 `{from, to}` bands, 0 to 1), `sides` (the four side weights of a plain rectangle, not beside a cut corner) and `ends` (`{start, end}` line ends of a path shape, each `{type, scale?}`) and `strokeAlign` (`center`, `inside` or `outside`: where the stroke sits on the edge; `null` for the default, centre); a number out of range is `bad-number` with the field in `limit` (`radii[3]`, `dash[1]`), a field the shape cannot take (corners on an ellipse, `radii`, `cornerStyle` and `cornerStyles` on a path, `ends` on a shape with no path) `bad-input` or `not-supported`. A path shape (a polygon, a star or any path) takes `radius` alone: one size, 0 to 20000 (the renderer's side limit; each corner is limited per vertex as it is drawn), that rounds the corners of every closed subpath (an absent `closed` is closed, with 3 or more points) and is written to the composition, with a decorative too; `bad-number` with the field in `limit` outside the range, `bad-input` with `limit.field` `radius` for a path with no closed subpath (an open path or a line is never rounded). With `polygon` or `star` in the same call the radius rounds the new outline. On a size these are refused with `400`, code `master_only`.

**Lines, polygons, stars, turning and text paints** (the same sessions). `add_element` `kind` `text` may leave `frame.h` out (or send 0): the box is then one line high at the size the text takes (its leading, 1.2 times the size, unless a paragraph gives one), kept inside the safe area, so a click or a dragged width makes the box in one add and one undo step; an explicit `h` is kept as sent, and any other kind still needs all four numbers. `add_element` also takes `kind` `line`, `polygon` and `star`, each stored as a shape of type `path`. A `line` takes `from` and `to` (`{"x", "y"}` in the page's units; two different points, else `bad-number`) and no `frame` (`bad-input`): its frame is the box round the two points grown by half the stroke weight on every side, so a level or upright line has a width and a height, and its points are fractions of that frame. A line has no fill (`fill` is `bad-input`) and always a stroke: `stroke` (a colour of the brand's palette, default the brand's first colour, `style-refused` outside it) and `strokeWidth` (page units, above 0, default 0.4% of the page's shorter side and never below 1 pt, about 4 px on a 1080 px page, `bad-number` with `limit.field`), and it takes `ends` (`{start, end}`, each `{type, scale?}`), `cap`, `join` and `dash` as `set_shape`'s. A `polygon` takes `frame` and `sides` (a whole number from 3 to 1000), a `star` takes `frame`, `points` (3 to 500) and `innerRatio` (0 to 1, default 0.5: the inner vertices' share of the outer radius); the outline is made on the server (a vertex at the top, filling the frame) and stored as points, with no parameters kept. They take `fill` as a shape does, and optionally `stroke` and `strokeWidth` (giving either gives the other its default), `cap`, `join` and `dash`; `ends` is `bad-input` on them. `radius` is `bad-input` on a line (it has no corners), and a `polygon` and a `star` take it as a closed `path` does (0 to 20000, rounding each corner; `bad-number` with the field in `limit` outside it), as `from`, `to`, `sides`, `points`, `innerRatio` and the stroke fields on any other kind. `set_shape` takes `polygon` `{"sides"}` or `star` `{"points", "innerRatio"?}` to make the outline of a path shape again in the same frame (`bad-input` on a rectangle or ellipse or when both are sent, `bad-number` out of range; its line ends are dropped; a decorative may take it alone). `set_rotation` `{"ref": ..., "degrees": 30}` turns a text or shape to `degrees` (-360 to 360, counter-clockwise as the composition holds it, 0 unturns it; `bad-number` outside that): the composition's element gets `rotation`, `size` (the frame's own unturned width and height) and `bounds` (the box round the turned frame, about the same centre), and at 0 the `size` goes and `bounds` are the frame; a later move shifts the box and keeps the size, and a turned element is resized by its own frame (`set_frame`, `scale_unit`; see below). For a group `ref` names the group and `degrees` is the turn applied to every member about the centre of the box round them (a group holds no angle of its own), each member's angle growing by it. `ref` may also be a nested group's id, which turns the elements under it the same way; a group or nested group holding plain nested groups (no fade, look or mask, and no clip unless Mestra made it) turns, and its elements under them with it. A button (a text and the shape that backs it, as the editor's button tool makes them) turns as a group does: `ref` may be its label, its pill or its group, and `degrees` is a turn by (relative), applied to both about the centre of the box round them; a single element's `degrees` stays an angle to take. A picture, the background, a member of a lockup that is not a button, a text with pinned lines, a group or nested group with its own fade or look, a group or nested group holding (at any depth) a nested group with a fade, a look, a mask or a clip that Mestra did not make, and a turned element whose own size is not stored are refused as `not-supported`; an unknown `ref` as `unknown-ref`. `set_paras_paint` `{"ref": ..., "paras": [0], "fills": [...], "stroke": [...], "strokeWidth": 1.5, "strokeOver": true}` writes the glyph paints of a text's paragraphs (`paras` index the drawn paragraphs, as `set_colour`'s do, paragraphs split from one source sharing its paints; left out, every paragraph): `fills` is the paint stack that draws the text, bottom first, and `stroke` the outline's paints with `strokeWidth` (page units, above 0) and `strokeOver` (true: over the fill); each is read only when sent and an empty list or `null` removes it (removing the stroke removes its width and `strokeOver`). A paint is the composition's own (`solid`, `linear`, `radial`, `angular` or `diamond`; at most 8 to a list, `bad-number`; no `image` paint, `bad-input`); every colour and gradient stop must be of the brand's palette (`style-refused`), `bad-input` for a colour that is not #RRGGBB or a stroke without a width above 0 (or a width or `strokeOver` with no stroke), `bad-number` for a width outside 0 to 20000, `unknown-ref` for an element that is not a text. The paragraph's plain colour is kept in step with the first solid fill. `set_colour` with `paras` on a paragraph that has fills makes it that one plain colour and drops the fills (on a size it is still refused as `bad-input`). `set_page` `{"width": 1200, "height": 628, "margins": {"top": 20, "right": 20, "bottom": 20, "left": 20}}` (a master or new-design session only; each field only when sent and at least one, page units) changes the master's page size and margins after it is made: every element keeps its box (nothing is moved or scaled, as in InDesign with no layout adjustment), so an element may stand past the new edge, and the answer's `comp` carries the new `page`. A `width` or `height` under the least or past the most that can be drawn (1 to 20000 in the page's unit), a margin below 0, or margins that leave no page inside them (left and right at or over the width, top and bottom at or over the height) is `bad-number` with the field in `limit` (`width`, `height`, `margins.top` ... or `margins`); nothing sent is `bad-input`; the same page as it is now is `noChange`; on a size it is `400` `master_only`.

**Paragraph indents and list markers** (a master's session). `set_paras_indent` `{"ref": ..., "paras": [0], "indent": 24, "firstIndent": -24, "marker": "1."}` writes the indents and the list marker of a text's paragraphs (`paras` index the drawn paragraphs, as `set_colour`'s do, paragraphs split from one source sharing them; left out, every paragraph): `indent` is the inset of every line's start edge from the box's left edge (0 or more, page units), `firstIndent` the extra inset of the first line only (negative hangs it out) and `marker` the literal list marker drawn on the first line (a bullet, `1.` or `a)`: not empty, without a line break). Each is read only when sent; `null` removes one (and `0` an indent). `indent` plus `firstIndent` must be 0 or more as each paragraph ends up. An indent or a first-line indent outside its range, or one that takes the first line left of the box, is `bad-number` with the field in `limit`; an empty marker or one with a line break is `bad-input`. A size session answers `400`, code `master_only`.

**Underline and strikethrough** (a master's session). `set_paras_decoration` `{"ref": ..., "paras": [0], "underline": true, "strike": false}` underlines and strikes through the whole of a text's paragraphs (`paras` index the drawn paragraphs, as `set_colour`'s do; left out, every paragraph); each of `underline` and `strike` is read only when sent, `false` takes it away, and a paragraph's own style runs lose their underline and strike so that the paragraph follows the call. With `range` `{"para": 0, "start": 4, "end": 9}` it sets them on those graphemes of one drawn paragraph alone (extended grapheme clusters, the unit of `breaks` and style runs; 0 <= `start` < `end` <= the paragraph's count; `paras` is then left out or `[para]`), written as style runs that are split and merged as needed. The composition holds `underline` and `strike` as booleans: the line's weight, offset and colour are the renderer's own for now. Nothing to set, a paragraph that is part of a longer paragraph of the master (for a range), or `paras` naming another paragraph than the range's is `bad-input`; a range outside the paragraph is `bad-number` with `limit.field` `range`. A size session answers `400`, code `master_only`.

**Flipping a picture** (a master's session). `set_flip` `{"ref": ..., "flipX": true, "flipY": false}` mirrors the picture of a picture frame across (`flipX`) or down (`flipY`), each only when sent; `false` takes one away. The picture is mirrored about its frame's centre before the element's turn, so a zoomed and panned picture is the mirror of what it was; the logo and a vector picture can be flipped too. Nothing to set, or a flag that is not `true` or `false`, is `bad-input`; a ref that is not a picture is `unknown-ref`. A size session answers `400`, code `master_only`.

**Paths from the pen** (a master's session). `add_element` `kind` `path` `{"id": ..., "kind": "path", "path": [{"closed": false, "points": [{"x": 100, "y": 200}, {"x": 300, "y": 200, "in": {"x": 250, "y": 120}, "out": {"x": 350, "y": 280}}, {"x": 300, "y": 500}]}], "stroke": "#1A2B3C", "strokeWidth": 4}` adds a path shape from subpaths of anchor points. Every number is in page units, on the page (not relative to the element): a point's `x` and `y`, and its optional cubic handles `in` (toward the previous point) and `out` (toward the next; an open subpath's first `in` and last `out` lead nowhere and are not stored), each the handle's own place on the page and not an offset from the point; a segment with no handle at either end is a straight line, and one with a handle at one end only is curved by that handle. `closed` is `true` or left out for a closed subpath (it needs 3 points) and `false` for an open one (2 points); a subpath that is shorter is `bad-input`, as is a point or handle with no `x` or `y` and a key that is not `closed`, `points`, `x`, `y`, `in` or `out`, and more than 32 subpaths or 1000 points in all, or a number that is not finite or is past 1000000, is `bad-number` with the field and the limit. A path may reach into the bleed, but one wholly off the page is `bad-number` ("off the page") with the field `path`. There is no `frame`: the element's frame is the box round the drawn curve (a side with no extent, as a level path has, takes the stroke weight), and the stored points are fractions of it. An open path has no fill, as a line has none (`fill` on a path with no closed subpath is `bad-input`); a closed one has a fill only when `fill` (a colour of the brand's palette) is sent. With no fill the path is stroked, `stroke` (a palette colour, the brand's first by default) and `strokeWidth` (page units above 0, by default a line's: 0.4% of the page's shorter side, never below 1 pt), as a line is; with a fill, a stroke only when sent. `fillRule` is `nonzero`, or left out or `null` for even-odd, which decides what a path that crosses itself or holds another subpath fills. `cap`, `join`, `dash` and `ends` (open subpaths only) take what `set_shape` takes, and `radius` rounds the closed subpaths as for a polygon (`bad-input` on a path with none). `set_path` `{"ref": ..., "path": [...]}` replaces the outline of any path shape (made as a line, polygon, star or with the pen; after it the element is just a path) with subpaths as above, and the element's frame, in the design and in the plan, becomes the box round the new outline, so it is drawn where it was given. An outline with no open subpath takes the line ends away; one with no closed subpath takes the fill and the radius away and, if there was no stroke, gets the default one so it can be seen; nothing else of the shape changes. The same outline is `noChange`; a ref that is not a path, rectangle or ellipse shape is `unknown-ref`; a turned path keeps its angle: the points are given on the page, and its own frame is the box round the outline turned back by that angle (the stored frame is the box round that, as for any turned element). On a decorative, the fill, stroke and radius it was given and where it was moved are cleared where the new outline would undo them, so an open curve is not drawn filled and the new frame holds. With no `path`, a rectangle or an ellipse (also a picture frame of either) is made a path with the outline it has, drawn where the shape was and turned with it when it is turned (`set_path` `{"ref": ...}`; Edit shape in the editor). A rectangle with one radius on every corner becomes its four corners and that radius, which the renderer rounds in page units (capped at half the shorter side, as a rectangle's is), so the corners stay circular on every size; a radius the plan holds and the design does not yet (a decorative's included) is taken in. Corners that differ are drawn as the renderer draws them: rounded and inverse ones as quarter circles (cubics), bevelled and inset ones as straight segments, a fancy one as its staircase with the island as a closed subpath of its own, and a Figma design's corners by Figma's size rule. An ellipse becomes four cubics with the standard handle length; an arc or ring becomes its sector or annulus, the ring with an even-odd fill, and the look's arc goes. Fitted dashes (`dashFit`) keep their pattern without the fit, which a path does not have, and the answer's `fixes` has `dash-fit-dropped:<ref>`. Its fill, stroke, look and picture stay. Refused with `not-supported`: strokes of a different weight on each side (a path has one stroke weight), and a turned shape whose own size is not stored. A picture frame stays a picture frame, its picture clipped to the path and laid out again in the new frame at the zoom and focal it had (a turned frame's by the turned-frame resize, in its own unturned frame; `not-supported` when its picture's own box is not stored); its outline stays closed, and so does that of the frame of a clip group (`bad-input` for an open one). A lockup anchor's riders follow its new box (`bad-input` when the lockup would leave the page); a container or backing panel keeps the box given, held to its copy as `set_frame` is (`text-off-panel`); a background's outline is kept in the page box, so it is drawn on every size as it was given. A closed pen path takes a picture (`place_picture`) and can be the frame of a clip group (`make_group` with `clip`, the group's mask). `set_shape` also takes `fillRule` (`nonzero`, or `null` for even-odd; `bad-input` for anything else and for a shape that is not a path) and, on a path, `strokeWidth`, `stroke`, `cap`, `join`, `dash` and `ends`. A size session answers `400`, code `master_only`.

**Text on a path** (a master's session; render 0.40.0, InDesign's Type on a Path). `set_text_path` `{"ref": ..., "onPath": {"effect": "rainbow", "align": "baseline", "toPath": "center", "flip": false, "start": 0, "end": 1, "spacing": 0}, "text": "Along the line"}` sets the text of a path shape on its outline, changes how it sits there, or takes it off. `ref` is a path shape (a line, a pen path, a polygon or a star: a shape of type path) or a text that is on a path already: one element with its path as its shape, as InDesign holds it, so `set_path` and the pen move the text with the outline and the outline's stroke is the stroke `toPath` refers to. `onPath` is the whole set of options, replaced as one (`{}` is the defaults), or `null`: `effect` is `rainbow` (default), `skew`, `ribbon`, `stair` or `gravity`; `align` is which line of the text lies on the path, `baseline` (default), `ascender`, `descender` or `center`; `toPath` is where that line sits on the outline's stroke, `center` (default), `top` or `bottom`; `flip` puts the text on the path's other side; `start` and `end` are the brackets, fractions 0 to 1 of the path's length in the direction the unflipped text travels (defaults 0 and 1; on an open path `end` is after `start`); `spacing` is InDesign's Spacing, -1000 to 1000, in the text's units; `justify` is `all` to stretch the spaces to fill the span (a paragraph's own justify sets one line at its left); `ascent` and `descent` are the face's lines as fractions of the em (0 to 2), for a measured pair. A key sent as `null` or at its default is not written. On a path shape `onPath` makes it a text and `text` is the copy, required (the first paragraph, in the session's face, size and colour as `add_element` gives a new text; the path keeps its fill, stroke, frame and place in the stacking); on a text, `text` is `bad-input` (`set_text` and `set_copy` change the words) and `null` takes the type off the path: the element is a path shape again, as InDesign's Delete Type from Path leaves it (its text is gone; the path, fill, stroke and look stay). The same options are `noChange`. It is `unknown-ref` for anything that is not a path shape or a text on a path, `bad-number` with `limit.field` `onPath.<key>` for a number out of range (never clamped), `bad-input` for an `onPath` that is not an object or `null`, an unknown key or word, or a missing or blank `text` on a path shape. Only the element's `kind`, `text` and `onPath` change. A size whose text on a path does not fit between its brackets is reported as a text that does not fit. A size session answers `400`, code `master_only`.

**Pinned line ends** (a master's session). `set_paras_breaks` `{"ref": ..., "paras": [0], "breaks": [12, 30]}` pins the line ends of the one paragraph `paras` names (indices of the drawn paragraphs, as `set_colour`'s are) at those grapheme offsets of its text (extended grapheme clusters, the unit the layout wraps by: each above 0 and below the paragraph's count, in increasing order, none beside a line feed, which already ends a line): the paragraph is then broken at those places and nowhere else while its copy, size, face and box width are the master's. A pinned paragraph is broken only at its pins and never wrapped again, so a line wider than the box overflows it: `breaks` is every line end the paragraph should have, the places it wraps at now included. `"breaks": null` (or `[]`) releases the pins of `paras` (every paragraph when left out): `breaks`, `lineWidths` and `lineXs` all go, as they go together. A paragraph that has pinned line widths or letter positions (one per pinned line) refuses a different list until they are released. A list outside its range is `bad-number` with `limit.field` `breaks`; a list for more or fewer than one paragraph, a paragraph that is not its master's whole (part of a longer paragraph, or copy a size changed), or one with widths or positions is `bad-input`. A size session answers `400`, code `master_only`.

**Masking a picture** (a master's session). `set_mask` `{"ref": ..., "asset": "<hash>", "mode": "alpha", "bind": "frame"}` sets, replaces or removes a picture's own mask (render 0.30.0): another picture, read as its `alpha` or its `luminosity`, that hides parts of this one. `asset` is the mask picture, an upload or a library picture the session holds, by hash (a PNG, JPEG or SVG). On a picture with no mask it makes one over the whole frame, `mode` `alpha` and `bind` `frame` unless sent; on a picture that has one it replaces the mask's picture and keeps its mode, box and binding. `asset` `null` removes the mask. `mode` is `alpha` or `luminosity`; `bind` is `frame` (the mask stays put when the picture is panned or zoomed) or `picture` (the mask moves with the picture). Each of `mode` and `bind` is read only when sent, and a change of `bind` carries the mask's box over so the mask stays where it is (a turned picture's box is carried in its own unturned space, and a flipped picture's is mirrored, since a mask tied to the picture mirrors with it; the answer's `fixes` has `mask-mirrored:<ref>` then; only a picture with no known placement has its box become the whole of what it is now tied to, with `mask-box-reset:<ref>`). Refused: `bad-input` for nothing to set, a mode or bind with no mask and no `asset`, a mode or bind sent with `asset` `null`, a value that is not one of theirs, a picture the session does not hold or one that is not a PNG, JPEG or SVG; `unknown-ref` for a ref that is not a picture of the composition; `not-supported` (detail `picture_no_mask`) for a picture drawn from the design app's saved picture, and `bind` `picture` on a picture with no known placement (`limit.field` `bind`). `ref` may also be a nested group's own id (a clip group's `nested` id, as `set_rotation` and `ungroup` take): the group's soft mask is then set, replaced or removed the same way, with a first mask `alpha` over the whole group and the same `mode`; a group's mask has no binding, so `bind` is `bad-input`. A group with a mask moves and scales as one rigid piece when sizes are made. The mask picture is saved with the master and a save that replaces or removes it leaves no other. A size session answers `400`, code `master_only`.

**Adding a colour to the brand's palette.** `add_palette_colour` `{"hex": "#1A2B3C"}` works on any session, a size or a master. It adds the colour to the brand's own colour list, the one Setup edits, and takes it into the session's palette, so a `set_colour` (or any paint) with it is accepted afterwards; a colour the palette already holds (white and black always are) writes nothing. It is not an edit of the design: it answers `noChange` true with no `label`, is never an undo step, and an undo leaves the colour in the palette. The brand's list is the brand's, not the design's, so it needs the permission that changes a brand in Setup, the editor role, and for an API key Brand · Write as well as Designs · Write (`403`, code `wrong_key`, without it). A colour that is not `#RRGGBB` answers `400` (`field: hex`); a design that is not for a brand yet answers `400`, code `no_brand`. Read the brand's palette back with the brand (`GET /centres/{key}`, `brandColours`) or its styles.

**Picture frames and clip groups** (the same sessions). `add_element` `kind` `image` also takes an outline, which makes the picture a picture frame: `shape` (`rect`, `ellipse`, `path`, `polygon` or `star`; a line, an open path and `arc` are `bad-input`), `radius` (a rect's corner radius, as for a shape, `bad-number` with the field in `limit` outside 0 to half the shorter side; `bad-input` with `limit.field` `radius` on an ellipse; on a `path`, `polygon` or `star` frame it is 0 to 20000 and rounds the closed subpaths, `bad-number` with the field in `limit` outside that), `path` and `fillRule` (shape `path`: closed subpaths of at least 3 points), `sides` (polygon), `points` and `innerRatio` (star), and the border: `stroke` (a colour of the brand's palette, `style-refused` outside it) and `strokeWidth` (page units, 0 to the stroke limit, `bad-number` with `limit.field`; either gives the other its default). The picture covers the frame, centred (`image.placement.bounds`), and the frame is clipped to the outline, which is the element's `shape`, with no fill. `place_picture` `{"ref": ..., "asset": "<sha256 of an upload>"}` makes the shape `ref` a picture frame in place: it keeps its id, bounds, `z`, group, role and outline, and loses its fill, fill inks and look fills (`unknown-ref` for a text or an element the plan does not hold, `bad-input` for a picture already, with the picture swapped by `swap_picture`, or an upload the session does not hold, `not-supported` for a decorative, a lockup's member, a turned shape whose own size is not stored and an outline that is not closed). `set_picture` `{"ref": ..., "zoom": 2.5, "focal": {"x": 0.3, "y": 0.6}}` zooms (1 to 20, the frame always covered; `bad-number` with `limit.field` `zoom`) and pans (`focal` is where the frame sits in the picture, 0 to 1 on each axis; `bad-number` with `limit.field` `focal.x` or `focal.y`) the picture of a picture frame, each only when sent (`bad-input` when neither is); it writes `image.placement.bounds` (and, for a turned picture, `placement.own`, the graphic's box in the frame's own unturned space) and removes the scale, and the fold at save keeps it. It is `unknown-ref` for anything but a picture the plan holds and `not-supported` for the logo, a QR code, a vector, a picture drawn from the design app and a picture with no placed graphic. `set_adjust` `{"ref": ..., "adjust": {"exposure": 0.2, "contrast": -0.1, "saturation": 0, "temperature": 0, "tint": 0}}` sets a picture's colour adjustment (the five of Figma's image filters, each a number from -1 to 1, 0 neutral; the editor shows them times 100): the whole `adjust` is replaced, a key left out, `null` or 0 is not written, and an empty `adjust`, an all-neutral one or `null` removes it. It writes `image.adjust` alone. It is `unknown-ref` for anything but a picture of the composition, `bad-number` with `limit.field` `adjust.<key>` for a value that is not a number from -1 to 1 (never clamped), `bad-input` for an `adjust` that is not an object or has a key that is not one of the five, and `not-supported` for a picture drawn from the design app. `make_group` also takes `clip` `{"nested": "m...", "frame": "<ref>"}`: the group becomes a clip group, a nested group `nested` (a new id made as the others are, other than the group's own: `bad-id`, `id-taken`, `bad-input`) under it whose children are the frame, then the other members back to front, and whose `clip` is the frame's outline as fractions of the box round the members as they are drawn (a turned member counts as its own size about its centre). `frame` is the lowest of `refs` unless named and must be one of them (`bad-input`); it must be a closed shape, a rectangle with plain corners (not bevel, inset, inverse or fancy), an ellipse, a closed path, or a picture with an outline of its own (`not-supported`); a clip group has two or more `refs` (`bad-input`). The clip is derived again from where the members are after every edit and in the fold (a move, a resize, a turn, an added or a removed member), so it stays on the frame; only for ids Mestra made. `release_clip` `{"ref": ...}` (the group or its nested group) removes the clip and leaves a plain group, except a group that `make_group` with `clip` made in this same session, which goes with the clip (its members are as they were before it; a group from an earlier session or one that has since gained a look, fade, opacity or another nested group stays) (`unknown-ref` for neither, `bad-input` when it holds no clip). `ungroup` of a clip group is still `group-holds`. `set_order` is refused as `clip-frame-back` when it would put a clip group's frame above any of its content or content below it; `add_element` with `parent` the group joins the clip group; dropping the frame, or all the content, ends the clip group at save (the group stays). `set_rotation` now turns a picture (its graphic with it; a photo or the background, a vector and a picture drawn from the design app are `not-supported`) and a group holding clip groups (members about the centre of the box round them, the clip derived from the turned frame). The answer's `comp.nested` is every nested group of the working composition, as `comp.groups` is every group, and a master session's answer carries `foldNested`, the nested groups of the folded composition, when the fold changes them (a clip derived again from a member the plan moved or removed).

**On a master** (a session opened with Start editing a master) the session also takes these, and `set_text` and `set_style` take more. `set_opacity` `{"ref": ..., "opacity": 0.5}` sets a kept element's opacity, 0 (clear) to 1 (opaque); out of range is refused as `bad-number` with `limit` `{"field": "opacity"}`. `set_shape` `{"ref": ..., "stroke": "#1A2B3C", "strokeWidth": 2, "radius": 8}` sets a kept shape's stroke colour (a colour of the brand's palette, or an empty string for no stroke), stroke width and corner radius, each only when sent and at least one of them; a colour outside the palette is refused as `style-refused`, a width or radius out of range as `bad-number` with the field in `limit`, and an element that is neither a shape nor a picture frame as `unknown-ref`. A rectangle picture frame (a picture made with `shape` `rect`) takes `set_shape` too, for its corners alone: `radius`, `radii`, `cornerStyle` and `cornerStyles`, as a rectangle shape does, in one undo step; its border and the rest of its outline are not set that way (`bad-input` with `limit.field` naming the field). A path, polygon or star frame takes `radius` alone (0 to 20000, rounding its closed subpaths; `radii`, `cornerStyle` and `cornerStyles` are `bad-input`), and an ellipse frame has no corners to set (`bad-input` with `limit.field` `radius` or `radii`). The element's `caps.radius` is true for exactly the frames that take them. `set_role` `{"ref": ..., "role": "headline"}` sets a kept element's role to one of `headline`, `subhead`, `body`, `cta`, `legal`, `logo`, `icon`, `photo`, `background` or `decorative`, or `null` for Auto (the role Mestra would give it, as `suggestedRole` in the answer's elements says); the element's `roleChosen` is then true, and `carried` names each element that joined (`lockup-formed`) or left (`lockup-broken`) a lockup because of it. `set_opacity` and `set_shape` may send `role` in place of `ref`, as above; `set_role` takes `ref` alone, its `role` being the value. `set_text` also takes `verticalAlign` (`top`, `center`, `bottom` or `justify`) and `caps` (`normal`, `allCaps`, `smallCaps` or `capToSmallCaps`, on the paragraphs in `paras`, or on every paragraph), `set_text` with `align` (`left`, `center`, `right` or `justify`) and `paras` (or `align` `justify` alone, every paragraph) sets the paragraphs' own alignment in the master with no `alignReason`, sent without `size`, `maxLines`, `leading`, `tracking`, `verticalAlign` or `caps` (a value that is not an alignment, `inherit`, or a `paras` index out of range is refused as `bad-input`), and `set_style` also takes `paras` (the font goes on those paragraphs alone). `drop` on a master takes the element out of the master when it is saved (`fixes` has `removed:<ref>`), and a turned element is resized as an unturned one is, keeping its angle: `set_frame` with `w` or `h` on a turned element takes its own frame (`x`, `y`, `w`, `h` are the unturned rectangle whose centre is the centre it turns about, page units; a field left out keeps the element's own size or centre; the box round it follows), with neither it moves the box as before; `scale_unit` on a turned element, on any group id (turned or not; a group nested in it scales as part of it) or on a button with turned members takes `w` as the new width of the box round the unit, its top-left fixed, and scales every member's own size and centre about that corner, each keeping its angle and every text's type size scaling with it; `move_unit` on a group id takes `x` and `y` as where the top-left of the box round its members goes, and moves every member by the same amount in one edit. A resize that cannot be made is `not-supported` with a `detail` that starts `resize_kind:`, `resize_background:`, `resize_lockup:`, `resize_pinned_text:`, `resize_no_size:` or `resize_no_own_box:` (a lockup scales as one with `scale_unit`). A turned photo (a design app can draw one; `set_rotation` never turns one) resizes with its picture covering the new own frame at the same zoom and focal, as an unturned photo does, and a turned picture drawn from the design app scales with its frame. On a size, `set_frame` with `w` or `h` on a turned element takes its own frame in the same way (`x`, `y`, `w`, `h` are the unturned rectangle whose centre is the centre it turns about; a field left out keeps the own size or centre; a client that sent the box's numbers for a turned element before now gets the own frame's instead): the size holds the box round that frame, which follows, and the master's angle stays, so (reading `ownFrame` and `rotation` from the answer's elements) a width alone leaves the own height as it was, except within about 3 degrees of 45 (where the size cannot tell the own frame from its box and draws it in the master's aspect): there a `w` or `h` alone scales the other side with it in that aspect, and `w` leads when both are sent; with neither `w` nor `h` it moves the box. On a size these are refused: `set_opacity`, `set_shape` and `set_role` answer `400` with code `master_only` (`field: name`), and `set_text`'s `verticalAlign` and `caps` and `set_style`'s `paras` are a `200` with `refused` `bad-input` and a `detail` that starts `master_only:`. They are not part of Update many sizes either (`400`, code `master_only`, `field: edit.name`).
**What a session may hold.** The revisions of the composition a session keeps for an undo, and the states of its history, are charged to the same memory as its held pictures: the session's share (100 MiB with the pictures), the organisation's and the editing class's. An edit that would pass a limit is refused and changes nothing: `pictures_too_large_together` when the session is full (save it and open it again), `org_pictures_held` when the organisation's open designs are full (save or close one, then try again), or, with a `detail` that starts `memory_busy:`, when the server's memory for editing is in use for the moment (try again shortly). A revision no state of the history can come back to is dropped and its memory given back, and all of it is given back when the session ends. An op that would make the composition larger than a master may be (2,000,000 bytes) is refused as `too-large`. **Dashes the renderer would not draw as sent** are refused by `set_shape` and `add_element`, so a stroke is never drawn other than as set: `dash-too-fine` when the pattern's period (its sum, an odd list taken twice) is under 1 page unit (`limit` `{"field": "dash", "min": 1, "measured": ...}`), `dash-odd-too-long` when an odd list has more than 8 entries (`limit` `{"field": "dash", "max": 8, "measured": n}`; an even list has up to 16), and `dash-with-sides` when the shape would have a dash, side stroke weights of its own and rounded corners (`limit` `{"field": "dash"}`). `place_picture` on the background is `not-supported` with a `detail` that starts `frame_background:`.

### Parameters

- `X-Mestra-Edit-Session` (string, required): The session id the open call answered. It travels in this header, never in the path.
- `name` (string, required):
- `input` (object, optional):

### Returns

The size after the edit.

An object with:

- `elements` (array of objects, required): The design's elements in words, in plan order.
  - `ref` (string, required): The element's ref, for `ref` (or `id`) in an edit's input.
  - `role` (string, required): The element's role as an edit may send it: lower case, words joined by `_`. Empty when it has none.
  - `name` (string, required):
  - `kind` (string, required): `text`, `image`, `shape`, `group` or `vector`; empty for an element the design adds.
  - `kept` (boolean, required): False when the element has been dropped.
  - `frame` (object, required): The element's box in the design's own units.
    - `x` (number, optional):
    - `y` (number, optional):
    - `w` (number, optional):
    - `h` (number, optional):
  - `text` (string, required, nullable): A text element's copy as it stands, paragraphs joined by a line break; null for any other element, and for every element in an answer that refuses an edit (a refusal carries no copy).
  - `rotation` (number, optional): A turned element only (one its master turns): its angle in degrees, as the master holds it. On a size it does not change.
  - `ownFrame` (object, optional): A turned element only, and only when the master stores its own size. The unturned frame its copy sets in, in the design's own units: the rectangle `frame` (the box round it) is the turned box of. It is what `set_frame` takes and gives for the element's `x`, `y`, `w` and `h`, so send numbers from this, not from `frame`. Within about 3 degrees of 45 the size draws the master's aspect, and this is that frame.
    - `x` (number, optional):
    - `y` (number, optional):
    - `w` (number, optional):
    - `h` (number, optional):
  - `roleChosen` (boolean, optional): A master's element only. True when the role is the person's choice; false when it is the one Mestra suggested (Auto), which a later save of the master may suggest differently. A master saved before Mestra kept this answers true for every element.
  - `z` (integer, optional): A master's element only. Its place in the stacking: a higher z is in front. A group's is its topmost member's.
  - `group` (string, optional): A master's element only, and only when it is a member of a group: the group's ref.
  - `members` (array of strings, optional): A group's entry only (`kind` is `group`): the refs of its members, back to front. A master's groups are listed beside its elements, each with the box around its members, so `set_order` and `ungroup` have a ref to name. A master's nested groups (a clip group's clip is on one) are listed the same way, each with `group` set to the group or nested group it is under and its members the elements under it; the id is what `set_order`, `set_rotation`, `move_unit`, `scale_unit` and `ungroup` take for it.
  - `look` (object, optional): A master's element only, and only when it has an effect or a paint. Its look in words: `effects` are the effect types in order (a level's after the look's own) and `paints` is how many fills and strokes it has.
    - `effects` (array of strings, optional):
    - `paints` (integer, optional):
  - `suggestedRole` (string, optional): A master's element only. The role Mestra suggests for the element, in the same form as `role`: what choosing Auto would give it. For an element whose role is suggested it is its own role.
- `candidates` (array of objects, optional): With `refused` `ambiguous_role`: every kept element that has the role, by ref, role and name. With `unknown_role`: empty.
  - `ref` (string, required):
  - `role` (string, required):
  - `name` (string, required):
- `fixes` (array of strings, required):
- `carried` (object, required):
- `comp` (object, optional): A master's session that has had `add_element`, `place_picture`, `set_picture`, `set_adjust`, `set_mask`, `set_order`, `make_group`, `release_clip`, `ungroup`, `set_rotation`, `set_paras_paint`, `set_paras_indent`, `set_paras_decoration`, `set_paras_breaks`, `set_flip`, `set_path`, `set_text_path` or `set_page`: the working composition as a change to the composition the open answer sent. A restore answers it too.
  - `upsert` (array of objects, optional): Each element that is new or changed, as the composition holds it.
  - `remove` (array of strings, optional): Ids of the open composition's elements that are gone.
  - `groups` (array of objects, optional): Every group of the composition.
  - `nested` (array of objects, optional): Every nested group of the composition (a clip group's clip is on one).
  - `page` (object, optional): Present only when `set_page` has changed the page from the one the open answer sent: the page as it now is, as the composition holds it.
    - `width` (number, optional): The page width, in the page's unit.
    - `height` (number, optional): The page height, in the page's unit.
    - `unit` (string, optional): The page's unit, which `set_page` leaves as it was.
    - `margins` (object, optional): The margins, in the page's unit.
      - `top` (number, optional):
      - `left` (number, optional):
      - `bottom` (number, optional):
      - `right` (number, optional):
- `check` (object, required): The plan's check. `results` is every rule the check judged, with the number it measured; a client that gets none shows the failures and warnings alone.
  - `failures` (array of strings, required):
  - `warnings` (array of strings, required):
  - `objective` (integer, required):
  - `results` (array of objects, optional):
    - `source` (string, required): `brand` for the brand's rules, `spec` for the screen spec. One of: `brand`, `spec`.
    - `code` (string, required):
    - `ref` (string, optional, nullable): The element the rule judged, or null for a whole-size rule.
    - `pass` (boolean, required):
    - `measured` (number, optional, nullable):
    - `limit` (number, optional, nullable):
    - `unit` (string, optional, nullable):  One of: `pt`, `px`, `mm`, `ratio`, `share`, `words`, `null`.
    - `at` (string, required): What the result was judged on: the drawing, the plan's boxes, or an earlier state that an edit has since changed. One of: `render`, `plan`, `stale`.
    - `fix` (object, optional): On a failing result only, and only when Mestra knows an edit that clears it: the edit's `name` and `input`, exactly as the edit call takes them, so applying it is one op and one undo step. It was tried on a copy of the session first: the copy took it, the rule is met on that element afterwards, and no failure appeared that the current state lacks. That check covers only what the plan can show (the boxes and sizes of the elements); the copy is never rendered, so a failure that only a drawing shows, such as contrast or a picture's content, is not ruled out. Offered for a text under its type floor (`type-min`), which gets `set_text` with the size that meets it; for a legal line under the legal size (`rule-legal-size`), which gets `set_text` with `paras` naming its paragraphs under the limit and the size that meets it; and for an element outside the safe area (`crs-safe-area`), which gets `move_unit` to the nearest place that puts the element, its lockup and the units grouped with it inside the safe area (none when they are together bigger than it). Its numbers are in the edit's own units, page units for a place and points for a size. It is computed on the state the answer shows: apply it to that state, not a later one. A master gets none (its type size is only ever a warning), and neither does a result judged on an earlier state (`at` is `stale`). This is not the answer's `fixes`, which lists what Mestra already did on its own.
      - `name` (string, required): An edit the apply call takes, such as `set_text` or `move_unit`.
      - `input` (object, required): The edit's input.
- `refused` (string, required): A refusal code, or empty when the edit was made.
- `detail` (string, required): Refs, field names and numbers; never copy.
- `limit` (object, required, nullable): The bound a refusal or clamp ran into.
- `noChange` (boolean, required):
- `label` (string, required): The checkpoint a committed edit made (`e1`, `e2`, ...), the label restored, or empty.

### Errors

- 400 (`master_only`): “Send the editing session's id in X-Mestra-Edit-Session.” (`field: X-Mestra-Edit-Session`), “That edit isn't one the editor makes.” (`field: name`), “That edit is made on a master, not on a size.” (`field: name`, code `master_only`) or “Those edits can't be made together.” (`field: edits`).
- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`): `403` for a role below the route's minimum (“Your role (\<role>) can't \<action>.”, or “Choose an organisation first.”), or, for an API key without the permission this call needs, code `wrong_key` with “This key needs the \<Area> · \<Read|Write> permission.” (for example “This key needs the Reviews · Write permission.”), or “This key can't do that.” for a call only the Mestra apps make.
- 404 (`session_gone`): “This editing session has ended. Reopen the size.” (code `session_gone`): unknown, idle for an hour, or another person's.
- 409 (`api_off`): `409` with code `api_off` (“Turn on the API in Developer → API and MCP first.”): an owner hasn't turned the API on for this organisation, so no API key works yet. An owner turns it on in Settings, then API.
- 503 (`editor_unavailable`): “The editor isn't available right now.” (code `editor_unavailable`).

### Example request

```sh
curl --request POST \
  --url https://app.withmestra.com/api/v1/edit/apply \
  --header "Authorization: Bearer $MESTRA_TOKEN" \
  --header 'Content-Type: application/json' \
  --header 'X-Mestra-Edit-Session: string' \
  --data '{"name":"set_text","input":{"ref":"headline","text":"Summer sale"}}'
```

## Update a size to an earlier checkpoint

`POST /api/v1/edit/restore`

Permission: Designs · Write.

Puts an open session back on a checkpoint: `loaded`, an `e<n>` label an edit answered, `current` or `best`. Send the session id in `X-Mestra-Edit-Session`. Keep the list of labels to step back and forward. Needs the Designs · Write permission.

### Parameters

- `X-Mestra-Edit-Session` (string, required): The session id the open call answered. It travels in this header, never in the path.
- `label` (string, required):

### Returns

The size at that checkpoint.

An object with:

- `elements` (array of objects, required): The design's elements in words, in plan order.
  - `ref` (string, required): The element's ref, for `ref` (or `id`) in an edit's input.
  - `role` (string, required): The element's role as an edit may send it: lower case, words joined by `_`. Empty when it has none.
  - `name` (string, required):
  - `kind` (string, required): `text`, `image`, `shape`, `group` or `vector`; empty for an element the design adds.
  - `kept` (boolean, required): False when the element has been dropped.
  - `frame` (object, required): The element's box in the design's own units.
    - `x` (number, optional):
    - `y` (number, optional):
    - `w` (number, optional):
    - `h` (number, optional):
  - `text` (string, required, nullable): A text element's copy as it stands, paragraphs joined by a line break; null for any other element, and for every element in an answer that refuses an edit (a refusal carries no copy).
  - `rotation` (number, optional): A turned element only (one its master turns): its angle in degrees, as the master holds it. On a size it does not change.
  - `ownFrame` (object, optional): A turned element only, and only when the master stores its own size. The unturned frame its copy sets in, in the design's own units: the rectangle `frame` (the box round it) is the turned box of. It is what `set_frame` takes and gives for the element's `x`, `y`, `w` and `h`, so send numbers from this, not from `frame`. Within about 3 degrees of 45 the size draws the master's aspect, and this is that frame.
    - `x` (number, optional):
    - `y` (number, optional):
    - `w` (number, optional):
    - `h` (number, optional):
  - `roleChosen` (boolean, optional): A master's element only. True when the role is the person's choice; false when it is the one Mestra suggested (Auto), which a later save of the master may suggest differently. A master saved before Mestra kept this answers true for every element.
  - `z` (integer, optional): A master's element only. Its place in the stacking: a higher z is in front. A group's is its topmost member's.
  - `group` (string, optional): A master's element only, and only when it is a member of a group: the group's ref.
  - `members` (array of strings, optional): A group's entry only (`kind` is `group`): the refs of its members, back to front. A master's groups are listed beside its elements, each with the box around its members, so `set_order` and `ungroup` have a ref to name. A master's nested groups (a clip group's clip is on one) are listed the same way, each with `group` set to the group or nested group it is under and its members the elements under it; the id is what `set_order`, `set_rotation`, `move_unit`, `scale_unit` and `ungroup` take for it.
  - `look` (object, optional): A master's element only, and only when it has an effect or a paint. Its look in words: `effects` are the effect types in order (a level's after the look's own) and `paints` is how many fills and strokes it has.
    - `effects` (array of strings, optional):
    - `paints` (integer, optional):
  - `suggestedRole` (string, optional): A master's element only. The role Mestra suggests for the element, in the same form as `role`: what choosing Auto would give it. For an element whose role is suggested it is its own role.
- `fixes` (array of strings, required):
- `carried` (object, required):
- `comp` (object, optional): A master's session that has had composition edits: the working composition of the checkpoint restored, as a change to the composition the open answer sent (see Update).
  - `upsert` (array of objects, optional):
  - `remove` (array of strings, optional):
  - `groups` (array of objects, optional):
  - `nested` (array of objects, optional):
  - `page` (object, optional): Present only when the restored page is not the one the open answer sent (a restore of a `set_page`): the page as it now is, `width`, `height`, `unit` and `margins` as the composition holds it.
- `check` (object, required): The plan's check. `results` is every rule the check judged, with the number it measured; a client that gets none shows the failures and warnings alone.
  - `failures` (array of strings, required):
  - `warnings` (array of strings, required):
  - `objective` (integer, required):
  - `results` (array of objects, optional):
    - `source` (string, required): `brand` for the brand's rules, `spec` for the screen spec. One of: `brand`, `spec`.
    - `code` (string, required):
    - `ref` (string, optional, nullable): The element the rule judged, or null for a whole-size rule.
    - `pass` (boolean, required):
    - `measured` (number, optional, nullable):
    - `limit` (number, optional, nullable):
    - `unit` (string, optional, nullable):  One of: `pt`, `px`, `mm`, `ratio`, `share`, `words`, `null`.
    - `at` (string, required): What the result was judged on: the drawing, the plan's boxes, or an earlier state that an edit has since changed. One of: `render`, `plan`, `stale`.
    - `fix` (object, optional): On a failing result only, and only when Mestra knows an edit that clears it: the edit's `name` and `input`, exactly as the edit call takes them, so applying it is one op and one undo step. It was tried on a copy of the session first: the copy took it, the rule is met on that element afterwards, and no failure appeared that the current state lacks. That check covers only what the plan can show (the boxes and sizes of the elements); the copy is never rendered, so a failure that only a drawing shows, such as contrast or a picture's content, is not ruled out. Offered for a text under its type floor (`type-min`), which gets `set_text` with the size that meets it; for a legal line under the legal size (`rule-legal-size`), which gets `set_text` with `paras` naming its paragraphs under the limit and the size that meets it; and for an element outside the safe area (`crs-safe-area`), which gets `move_unit` to the nearest place that puts the element, its lockup and the units grouped with it inside the safe area (none when they are together bigger than it). Its numbers are in the edit's own units, page units for a place and points for a size. It is computed on the state the answer shows: apply it to that state, not a later one. A master gets none (its type size is only ever a warning), and neither does a result judged on an earlier state (`at` is `stale`). This is not the answer's `fixes`, which lists what Mestra already did on its own.
      - `name` (string, required): An edit the apply call takes, such as `set_text` or `move_unit`.
      - `input` (object, required): The edit's input.
- `refused` (string, required): A refusal code, or empty when the checkpoint was restored.
- `detail` (string, required): Refs, field names and numbers; never copy.
- `limit` (object, required, nullable): The bound a refusal ran into.
- `noChange` (boolean, required):
- `label` (string, required): The checkpoint the session stands on.

### Errors

- 400: “Send the editing session's id in X-Mestra-Edit-Session.” (`field: X-Mestra-Edit-Session`).
- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`): `403` for a role below the route's minimum (“Your role (\<role>) can't \<action>.”, or “Choose an organisation first.”), or, for an API key without the permission this call needs, code `wrong_key` with “This key needs the \<Area> · \<Read|Write> permission.” (for example “This key needs the Reviews · Write permission.”), or “This key can't do that.” for a call only the Mestra apps make.
- 404 (`session_gone`): “This editing session has ended. Reopen the size.” (code `session_gone`): unknown, idle for an hour, or another person's.
- 409 (`api_off`): `409` with code `api_off` (“Turn on the API in Developer → API and MCP first.”): an owner hasn't turned the API on for this organisation, so no API key works yet. An owner turns it on in Settings, then API.
- 503 (`editor_unavailable`): “The editor isn't available right now.” (code `editor_unavailable`).

### Example request

```sh
curl --request POST \
  --url https://app.withmestra.com/api/v1/edit/restore \
  --header "Authorization: Bearer $MESTRA_TOKEN" \
  --header 'Content-Type: application/json' \
  --header 'X-Mestra-Edit-Session: string' \
  --data '{"label":"loaded"}'
```

## Retrieve the check of a size being edited

`POST /api/v1/edit/check`

Permission: Designs · Read.

Checks the open session's current design against the rules. Send the session id in `X-Mestra-Edit-Session`. The body is optional. With `{"render": true}` the size is also drawn and the full rule gate and the screen spec run on the drawing, so the answer adds `standIns`, `lossy`, `hash` and `current`; without it only the boxes are judged and those are not sent. A drawing the worker refuses for what the design holds is not a failure to check: the answer still comes, with a failing row of `source` `render` and `code` `cannot_draw` whose `detail` is the worker's own code when it gave one (`lossy`, `asset-type`, `font`, ...; `lossy` in the answer is then `true`). An edit made meanwhile never waits for the drawing; a drawing of a state the session has moved on from is dropped (`current: false`). Needs the Designs · Read permission.

### Parameters

- `X-Mestra-Edit-Session` (string, required): The session id the open call answered. It travels in this header, never in the path.
- `render` (boolean, optional): Draw the plan and judge the drawing.

### Returns

The plan's check.

An object with:

- `check` (object, required): The plan's check. `results` is every rule the check judged, with the number it measured; a client that gets none shows the failures and warnings alone.
  - `failures` (array of strings, required):
  - `warnings` (array of strings, required):
  - `objective` (integer, required):
  - `results` (array of objects, optional):
    - `source` (string, required): `brand` for the brand's rules, `spec` for the screen spec. One of: `brand`, `spec`.
    - `code` (string, required):
    - `ref` (string, optional, nullable): The element the rule judged, or null for a whole-size rule.
    - `pass` (boolean, required):
    - `measured` (number, optional, nullable):
    - `limit` (number, optional, nullable):
    - `unit` (string, optional, nullable):  One of: `pt`, `px`, `mm`, `ratio`, `share`, `words`, `null`.
    - `at` (string, required): What the result was judged on: the drawing, the plan's boxes, or an earlier state that an edit has since changed. One of: `render`, `plan`, `stale`.
    - `fix` (object, optional): On a failing result only, and only when Mestra knows an edit that clears it: the edit's `name` and `input`, exactly as the edit call takes them, so applying it is one op and one undo step. It was tried on a copy of the session first: the copy took it, the rule is met on that element afterwards, and no failure appeared that the current state lacks. That check covers only what the plan can show (the boxes and sizes of the elements); the copy is never rendered, so a failure that only a drawing shows, such as contrast or a picture's content, is not ruled out. Offered for a text under its type floor (`type-min`), which gets `set_text` with the size that meets it; for a legal line under the legal size (`rule-legal-size`), which gets `set_text` with `paras` naming its paragraphs under the limit and the size that meets it; and for an element outside the safe area (`crs-safe-area`), which gets `move_unit` to the nearest place that puts the element, its lockup and the units grouped with it inside the safe area (none when they are together bigger than it). Its numbers are in the edit's own units, page units for a place and points for a size. It is computed on the state the answer shows: apply it to that state, not a later one. A master gets none (its type size is only ever a warning), and neither does a result judged on an earlier state (`at` is `stale`). This is not the answer's `fixes`, which lists what Mestra already did on its own.
      - `name` (string, required): An edit the apply call takes, such as `set_text` or `move_unit`.
      - `input` (object, required): The edit's input.
- `standIns` (array of strings, optional): Only with `render`: the families drawn as stand-ins because the brand and pack hold no face for them.
- `lossy` (boolean, optional): Only with `render`: the drawing holds something the apps can't carry back.
- `hash` (string, optional): Only with `render`: the plan hash of the state that was drawn and measured.
- `current` (boolean, optional): Only with `render`: false when the session moved on while the drawing ran, so the drawing was dropped and `check` is the current state's as it stands.

### Errors

- 400: “Send the editing session's id in X-Mestra-Edit-Session.” (`field: X-Mestra-Edit-Session`).
- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`): `403` for a role below the route's minimum (“Your role (\<role>) can't \<action>.”, or “Choose an organisation first.”), or, for an API key without the permission this call needs, code `wrong_key` with “This key needs the \<Area> · \<Read|Write> permission.” (for example “This key needs the Reviews · Write permission.”), or “This key can't do that.” for a call only the Mestra apps make.
- 404 (`session_gone`): “This editing session has ended. Reopen the size.” (code `session_gone`): unknown, idle for an hour, or another person's.
- 409 (`api_off`): `409` with code `api_off` (“Turn on the API in Developer → API and MCP first.”): an owner hasn't turned the API on for this organisation, so no API key works yet. An owner turns it on in Settings, then API.
- 502 (`render_failed`, `check_unavailable`): “The size couldn't be drawn just now. Try again.” (code `render_failed`), with `render`: the drawing could not be made, so the check could not be judged on it. The answer also carries `check` (the rules alone), whose `results` end with a failing row of `source` `render` and `code` `check_unavailable` (no numbers). Show that row; never read a check that could not be drawn as a clean one. The same answer on a master and a new design.
- 503 (`editor_unavailable`): “The editor isn't available right now.” (code `editor_unavailable`).

### Example request

```sh
curl --request POST \
  --url https://app.withmestra.com/api/v1/edit/check \
  --header "Authorization: Bearer $MESTRA_TOKEN" \
  --header 'Content-Type: application/json' \
  --header 'X-Mestra-Edit-Session: string' \
  --data '{"render":true}'
```

## Retrieve a picture of a size being edited

`POST /api/v1/edit/preview`

Permission: Designs · Read.

Draws the open session's current design and answers the picture with its check, so you can see the result of your edits before you save. Send the session id in `X-Mestra-Edit-Session`; there is no body. The picture is a PNG in `image.data` (base64), at most 1568 pixels on its long side, with its own `width` and `height`. It is the drawing the render check makes: a design already drawn is answered again without drawing it a second time, and an edit made meanwhile never waits for it. `current: false` says the session moved on while it was drawn, so the picture is of an earlier state. Works on a size and on a master. A design the preview worker cannot draw for its effects (too much filter work) is answered `409` with code `too_heavy` and the check, whose `results` hold a failing row with `source` `render` and `code` `too_heavy` (no numbers: the worker gives none); the same row is in `POST /edit/check` with `render`. Needs the Designs · Read permission.

### Parameters

- `X-Mestra-Edit-Session` (string, required): The session id the open call answered. It travels in this header, never in the path.

### Returns

The drawing and its check.

An object with:

- `check` (object, required): The plan's check. `results` is every rule the check judged, with the number it measured; a client that gets none shows the failures and warnings alone.
  - `failures` (array of strings, required):
  - `warnings` (array of strings, required):
  - `objective` (integer, required):
  - `results` (array of objects, optional):
    - `source` (string, required): `brand` for the brand's rules, `spec` for the screen spec. One of: `brand`, `spec`.
    - `code` (string, required):
    - `ref` (string, optional, nullable): The element the rule judged, or null for a whole-size rule.
    - `pass` (boolean, required):
    - `measured` (number, optional, nullable):
    - `limit` (number, optional, nullable):
    - `unit` (string, optional, nullable):  One of: `pt`, `px`, `mm`, `ratio`, `share`, `words`, `null`.
    - `at` (string, required): What the result was judged on: the drawing, the plan's boxes, or an earlier state that an edit has since changed. One of: `render`, `plan`, `stale`.
    - `fix` (object, optional): On a failing result only, and only when Mestra knows an edit that clears it: the edit's `name` and `input`, exactly as the edit call takes them, so applying it is one op and one undo step. It was tried on a copy of the session first: the copy took it, the rule is met on that element afterwards, and no failure appeared that the current state lacks. That check covers only what the plan can show (the boxes and sizes of the elements); the copy is never rendered, so a failure that only a drawing shows, such as contrast or a picture's content, is not ruled out. Offered for a text under its type floor (`type-min`), which gets `set_text` with the size that meets it; for a legal line under the legal size (`rule-legal-size`), which gets `set_text` with `paras` naming its paragraphs under the limit and the size that meets it; and for an element outside the safe area (`crs-safe-area`), which gets `move_unit` to the nearest place that puts the element, its lockup and the units grouped with it inside the safe area (none when they are together bigger than it). Its numbers are in the edit's own units, page units for a place and points for a size. It is computed on the state the answer shows: apply it to that state, not a later one. A master gets none (its type size is only ever a warning), and neither does a result judged on an earlier state (`at` is `stale`). This is not the answer's `fixes`, which lists what Mestra already did on its own.
      - `name` (string, required): An edit the apply call takes, such as `set_text` or `move_unit`.
      - `input` (object, required): The edit's input.
- `standIns` (array of strings, required): The families drawn as stand-ins because the brand and pack hold no face for them.
- `lossy` (boolean, required): The drawing holds something the apps can't carry back.
- `hash` (string, required): The plan hash of the state that was drawn.
- `current` (boolean, required): False when the session moved on while the drawing ran: the drawing is of an earlier state and `check` is the current state's as it stands.
- `image` (object, required):
  - `mime` (string, required):  One of: `image/png`.
  - `width` (integer, required):
  - `height` (integer, required):
  - `data` (string, required): The PNG, base64.

### Errors

- 400: “Send the editing session's id in X-Mestra-Edit-Session.” (`field: X-Mestra-Edit-Session`).
- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`): `403` for a role below the route's minimum (“Your role (\<role>) can't \<action>.”, or “Choose an organisation first.”), or, for an API key without the permission this call needs, code `wrong_key` with “This key needs the \<Area> · \<Read|Write> permission.” (for example “This key needs the Reviews · Write permission.”), or “This key can't do that.” for a call only the Mestra apps make.
- 404 (`session_gone`): “This editing session has ended. Reopen the size.” (code `session_gone`): unknown, idle for an hour, or another person's.
- 409 (`api_off`, `too_heavy`): `api_off`: an owner hasn't turned the API on for this organisation. Or “This design has too many effects to draw. Remove one.” (code `too_heavy`): the preview worker refused the drawing as too large; the answer also carries `check`, with the failing `too_heavy` row.
- 502 (`render_failed`, `check_unavailable`): “The size couldn't be drawn just now. Try again.” (code `render_failed`); when the drawing could not be made the answer also carries `check`, as `POST /edit/check` with `render` does, with the failing `check_unavailable` row.
- 503 (`editor_unavailable`): “The editor isn't available right now.” (code `editor_unavailable`).

### Example request

```sh
curl --request POST \
  --url https://app.withmestra.com/api/v1/edit/preview \
  --header "Authorization: Bearer $MESTRA_TOKEN" \
  --header 'X-Mestra-Edit-Session: string'
```

## Update a size with its edits

`PUT /api/v1/edit/save`

Permission: Designs · Write.

Saves the open session's design as the size's file. Send the session id in `X-Mestra-Edit-Session` and the `sceneHash` the session holds (the open call's, or the last save's) in `If-Match`. Send `{"idempotencyKey": "<a UUID you make>"}` to make the save safe to retry: if the answer is lost, send the same request again and you get the first save's answer, even when the editing session has ended in the meantime, and nothing is saved twice. Use a new key for each save. The design is drawn, then the size's files are replaced in one step, and the edit joins the run's review as an `edited` round when the run is the review's latest. Saving is free. A server run made under the campaign's current approved rules in rules mode publishes on Can publish alone until its first saved edit; after it the whole run (not just the edited size) needs Can publish without review, like a run made in an app, and the run's publications still queued or running at that moment are cancelled so a person at that level can queue them again. A design that uses a missing font or picture, or an effect the drawing cannot keep, is refused and nothing is saved. Saving a size sends the `size.edited` event. Needs the Designs · Write permission.

**A master** is saved the same way, with the session Start editing a master answered. `If-Match` is the master's version number: the `ifMatch` of the open answer, or of your last save. The save draws the master, checks it against the brand rules and stores it as the master's next version, which new runs use; the version it was opened on stays as it was. The answer says `version` (the new number), `ifMatch` (the same number, for the next save), `unchanged` (true and 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, else `none`), `runsKept` (how many runs were made from older versions), `ruleSets` (as when it was opened) and `newRuleFailures` (the brand rules the master now fails that it did not when opened), with `check` and `label`. If the master has a newer version than the one in `If-Match` (an app or someone else saved it since) nothing is saved and the answer is `412` with code `version_changed`, `latest` (that version's number), `by` (`mestra` for a save made here, else the app: `indesign`, `figma`, `canva` or `upload`) and `byName` (who saved it, for a save made here; empty for an app's): open the master again and redo the edits: the same session cannot be saved over a newer version, so sending `latest` as `If-Match` on that session is refused with the same `412`. `idempotencyKey` works as for a size.

**A new design** (a session opened with Start a new design) is saved the same way, and its first save makes the master: its name is the campaign's and the size it is designed at (`Spring - Medium rectangle`; with a name a brand's master has already, `... (2)`), its source app is `mestra`, and it is version 1. Leave out `If-Match`, or send `0` or `draft`; any other value is `400` (code `if_match`). A design with nothing in it (no element, or every one dropped) is `422` (code `empty_design`), and an organisation that keeps no files `409` (code `dont_keep`). The answer is a master save's (`version` 1, `ifMatch` 1, `status`, `pull` `none`, ...) with `master` (as the open of a master gives it), `campaign`, `site` and `sizes` (the sizes ticked when it was opened, as the open answered them), so the caller can start a run. The session is then 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.

### Parameters

- `X-Mestra-Edit-Session` (string, required): The session id the open call answered. It travels in this header, never in the path.
- `If-Match` (string, required): Which state the save was made from, bare or quoted: for a size, the `sceneHash` the session holds (the open call's, or the last save's), a scene hash; for a master, the master's version number as a decimal string (`ifMatch` of the open answer, or of the last save), such as `4`.
- `idempotencyKey` (string (uuid), optional): A UUID you make for this save. Sending the request again with the same key answers the first save's result and saves nothing more.

### Returns

Saved.

An object with:

- `sceneHash` (string, optional): The size's new scene hash; send it as `If-Match` on the next save.
- `fileId` (string, optional, nullable): The new PNG's file id (a size's save).
- `round` (integer, optional, nullable): The review round written, or null when none was.
- `publications` (integer, optional): How many queued publications were moved to the new file and will use this version.
- `pull` (string, required): A master's save answers `ready` (its app can pull the change) or `none`. A size's: `ready`: the edit is a round of the run's review. `quiet`: the run had no review, so one was made. `not_sent`: the run was never sent to the review. `superseded`: another run or a plugin send came later. With the last two the edit is saved and published but writes no round, so a design app's Pull does not bring it. One of: `ready`, `quiet`, `not_sent`, `superseded`, `none`.
- `check` (object, required): The plan's check. `results` is every rule the check judged, with the number it measured; a client that gets none shows the failures and warnings alone.
  - `failures` (array of strings, required):
  - `warnings` (array of strings, required):
  - `objective` (integer, required):
  - `results` (array of objects, optional):
    - `source` (string, required): `brand` for the brand's rules, `spec` for the screen spec. One of: `brand`, `spec`.
    - `code` (string, required):
    - `ref` (string, optional, nullable): The element the rule judged, or null for a whole-size rule.
    - `pass` (boolean, required):
    - `measured` (number, optional, nullable):
    - `limit` (number, optional, nullable):
    - `unit` (string, optional, nullable):  One of: `pt`, `px`, `mm`, `ratio`, `share`, `words`, `null`.
    - `at` (string, required): What the result was judged on: the drawing, the plan's boxes, or an earlier state that an edit has since changed. One of: `render`, `plan`, `stale`.
    - `fix` (object, optional): On a failing result only, and only when Mestra knows an edit that clears it: the edit's `name` and `input`, exactly as the edit call takes them, so applying it is one op and one undo step. It was tried on a copy of the session first: the copy took it, the rule is met on that element afterwards, and no failure appeared that the current state lacks. That check covers only what the plan can show (the boxes and sizes of the elements); the copy is never rendered, so a failure that only a drawing shows, such as contrast or a picture's content, is not ruled out. Offered for a text under its type floor (`type-min`), which gets `set_text` with the size that meets it; for a legal line under the legal size (`rule-legal-size`), which gets `set_text` with `paras` naming its paragraphs under the limit and the size that meets it; and for an element outside the safe area (`crs-safe-area`), which gets `move_unit` to the nearest place that puts the element, its lockup and the units grouped with it inside the safe area (none when they are together bigger than it). Its numbers are in the edit's own units, page units for a place and points for a size. It is computed on the state the answer shows: apply it to that state, not a later one. A master gets none (its type size is only ever a warning), and neither does a result judged on an earlier state (`at` is `stale`). This is not the answer's `fixes`, which lists what Mestra already did on its own.
      - `name` (string, required): An edit the apply call takes, such as `set_text` or `move_unit`.
      - `input` (object, required): The edit's input.
- `label` (string, required): The checkpoint the session stands on.
- `version` (integer, optional): A master's save: the new version number (the master's latest, or the one it already was when `unchanged`).
- `unchanged` (boolean, optional): A master's save: true when the edits left the master as it was, so no version was made.
- `ifMatch` (integer, optional): A master's save: the version number to send as `If-Match` on the next save.
- `status` (string, optional): A master's save: the master's brand check of the saved version. One of: `checking`, `ready`, `not_ready`.
- `runsKept` (integer, optional): A master's save: how many runs were made from older versions of the master.
- `ruleSets` (array of objects, optional): A master's save: each campaign whose current rule set lists a version of the master, as when it was opened. Empty for a key without the Campaigns · Read permission.
  - `campaign` (string, optional):
  - `name` (string, optional):
  - `lists` (array of integers, optional):
  - `locked` (array of objects, optional):
    - `element` (string, required): The element's role, such as `logo`.
    - `minScale` (number, required):
    - `maxScale` (number, required):
- `newRuleFailures` (array of strings, optional): A master's save: the brand rule codes the saved master fails that the opened one did not.
- `master` (object, optional): A new design's first save: the master it made, as the open of a master answers it (`id`, `version`, `latest`, `name`, `sourceApp`, `brand`, `canPull`).
  - `id` (string, optional):
  - `version` (integer, optional):
  - `latest` (integer, optional):
  - `name` (string, optional):
  - `sourceApp` (string, optional):
  - `brand` (string, optional):
  - `canPull` (boolean, optional):
- `campaign` (string, optional): A new design's first save: the campaign it was opened for.
- `site` (string, optional): A new design's first save: the brand.
- `sizes` (array of objects, optional): A new design's first save: the sizes ticked when it was opened (`key`, `name`, `width`, `height`, `unit`, `screenSpec`).

### Errors

- 400 (`if_match`): “Send the editing session's id in X-Mestra-Edit-Session.” (`field: X-Mestra-Edit-Session`), “idempotencyKey must be a UUID you make for this save.” (`field: idempotencyKey`), or for a master “If-Match must be the master's version number.” (`field: If-Match`, code `if_match`).
- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`): `403` for a role below the route's minimum (“Your role (\<role>) can't \<action>.”, or “Choose an organisation first.”), or, for an API key without the permission this call needs, code `wrong_key` with “This key needs the \<Area> · \<Read|Write> permission.” (for example “This key needs the Reviews · Write permission.”), or “This key can't do that.” for a call only the Mestra apps make.
- 404 (`session_gone`, `not_editable`): “This editing session has ended. Reopen the size.” (code `session_gone`): unknown, idle for an hour, or another person's. For a master, “This master can't be opened in the editor” (code `not_editable`): the master is gone or is not one this organisation can edit. Nothing was saved.
- 409 (`api_off`, `idempotency_conflict`, `review_moved`, `dont_keep`, `too_heavy`): `api_off`: an owner hasn't turned the API on for this organisation (“Turn on the API in Developer → API and MCP first.”). Or “That key was already used for a different save.” (code `idempotency_conflict`); or “A review round arrived; save again” (code `review_moved`), after one retry; or a billing refusal for a paused, read-only or pending organisation. For a master: “Saving masters needs the library to keep files. Choose how long to keep work in Settings.” (code `dont_keep`), or “That master is being saved. Try again.” (code `busy`); or, for a master or a new design the worker cannot draw for its effects, “This design has too many effects to draw. Remove one.” (code `too_heavy`, `field: effects`: remove an effect and save again). Nothing was saved.
- 412 (`scene_changed`, `version_changed`): “This size changed since you opened it” (code `scene_changed`): the scene or the run's master version is no longer the one opened, or `If-Match` is not the session's. For a master, “This master was saved since you opened it” (code `version_changed`) with `latest`, `by` and `byName`: the master has a newer version than `If-Match`. `byName` (who saved it) is empty for a key without the Team · Read permission. Nothing was written.
- 422 (`stand_in`, `cannot_draw`, `empty_design`, `picture_missing`): Nothing was saved. code `stand_in` (a font or picture is missing, so the drawing would be wrong), `lossy` (an effect the drawing can't keep) or `cannot_draw` (the size can't be drawn, such as a print size, or it is too large to draw), or, for a new design with nothing in it, `empty_design`. For a master, `picture_missing` with `ref` (the element whose swapped-in picture is no longer available to the organisation).
- 428 (`if_match_required`): `If-Match` is missing (code `if_match_required`).
- 503 (`editor_unavailable`, `editor_busy`): code `editor_unavailable` (no editor, or a build worker without the draw route), or `editor_busy` with `Retry-After` (the worker is busy or timed out). Nothing was saved.

### Example request

```sh
curl --request PUT \
  --url https://app.withmestra.com/api/v1/edit/save \
  --header "Authorization: Bearer $MESTRA_TOKEN" \
  --header 'Content-Type: application/json' \
  --header 'If-Match: string' \
  --header 'X-Mestra-Edit-Session: string' \
  --data '{"idempotencyKey":"5b0e4a5e-2c7d-4f43-9d52-0d8f8b0a3c11"}'
```

## List all editable sizes of a run

`GET /api/v1/jobs/{id}/editable`

Permission: Designs · Read.

Says, for each size of a run, whether it can be opened for editing: it has a stored design and the run is tied to a saved master. A server run's size opens once the run has finished and the size is done; a booking's run and the run of a dynamic content row never open. `sizes` adds each size's `sceneHash`, the version it was last saved at (null when none was kept). Needs the Designs · Read permission.

### Parameters

- `id` (string, required): The run's id. A run of another organisation is a `404`.

### Returns

Per-size booleans, keyed by format key.

An object with:

- `editable` (object, required):
- `sizes` (map of objects, optional): The same sizes with the scene hash each was last opened against. A client without it reads `editable` and takes the hash as unknown.
  - `editable` (boolean, optional):
  - `sceneHash` (string, optional, nullable):

### Errors

- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`): `403` for a role below the route's minimum (“Your role (\<role>) can't \<action>.”, or “Choose an organisation first.”), or, for an API key without the permission this call needs, code `wrong_key` with “This key needs the \<Area> · \<Read|Write> permission.” (for example “This key needs the Reviews · Write permission.”), or “This key can't do that.” for a call only the Mestra apps make.
- 404: “job not found”: no such run in this organisation (a run of another organisation is as unknown as a missing one).
- 409 (`api_off`): `409` with code `api_off` (“Turn on the API in Developer → API and MCP first.”): an owner hasn't turned the API on for this organisation, so no API key works yet. An owner turns it on in Settings, then API.
- 503 (`editor_unavailable`): “The editor isn't available right now.” (code `editor_unavailable`).

### Example request

```sh
curl --request GET \
  --url https://app.withmestra.com/api/v1/jobs/string/editable \
  --header "Authorization: Bearer $MESTRA_TOKEN"
```

## Add a picture to a size or master being edited

`PUT /api/v1/edit/assets/{asset}`

Permission: Designs · Write.

Keeps a picture for the open session, so a `swap_picture` edit can then name it. Send the session id in `X-Mestra-Edit-Session`. The body is the picture's raw bytes (PNG, JPEG or SVG, at most 25 MiB; an SVG, `image/svg+xml`, is scanned as a logo is and sized by its viewBox, in a size as in a master or new design) with `Content-Type` and `Content-Length` sent, and the `{asset}` in the path is the SHA-256 of those bytes. The answer is `asset` (`sha256`, `mime`, `width`, `height`: send `sha256` as the `swap_picture` edit's `sha256`) and `created`: `201` when the picture is new and `200` when the session or run already held it. For a size it is kept for the run the way a run image is, encrypted and the organisation's own, and a saved size keeps it. For a master the session holds it until the master is saved, and the save seals it as the picture's new original in the next version (a session that ends first drops it). A master's picture has no run canvas to be measured against, so `image_too_large` is a size's refusal only. Saving is free. Needs the Designs · Write permission.

### Parameters

- `asset` (string, required): The image's SHA-256, 64 lowercase hex characters, as the scene names it.
- `X-Mestra-Edit-Session` (string, required): The session id the open call answered. It travels in this header, never in the path.

### Returns

The run already held the picture.

An object with:

- `asset` (object, required):
  - `sha256` (string, required):
  - `mime` (string, required):  One of: `image/png`, `image/jpeg`.
  - `width` (integer, required):
  - `height` (integer, required):
- `created` (boolean, required):

### Errors

- 400 (`picture_sum`, `picture_empty`, `picture_short`, `picture_size`, `image_too_large`): “Send the editing session's id in X-Mestra-Edit-Session.” (`field: X-Mestra-Edit-Session`), or a picture refused: code `picture_sum` (the bytes aren't the SHA-256 in the address), `picture_empty`, `picture_short` (not sent whole), `picture_size` (it doesn't decode, or is too big a picture), `image_too_large` with `limit` (a size only: the most pixels its long side may span for this run).
- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`): `403` for a role below the route's minimum (“Your role (\<role>) can't \<action>.”, or “Choose an organisation first.”), or, for an API key without the permission this call needs, code `wrong_key` with “This key needs the \<Area> · \<Read|Write> permission.” (for example “This key needs the Reviews · Write permission.”), or “This key can't do that.” for a call only the Mestra apps make.
- 404 (`session_gone`): “This editing session has ended. Reopen the size.” (code `session_gone`): unknown, idle for an hour, or another person's.
- 409 (`api_off`, `library_off`): `api_off`, or code `library_off`: the organisation keeps nothing, so there is nowhere to keep the picture.
- 411 (`picture_length`): code `picture_length`: `Content-Length` is missing.
- 413 (`picture_too_big`): code `picture_too_big`, with `max` in bytes.
- 415 (`picture_type`): code `picture_type`: not a PNG or JPEG (a master or new-design session also takes an SVG, `image/svg+xml`; a size does not).
- 422 (`run_images_full`, `picture_size`): code `run_images_full`, with `max`; or, for an SVG, code `svg-viewbox` with `min` and `max`: the SVG has no usable viewBox (its size is the root element's viewBox width and height, each rounded to a whole number from `min` to `max`). An SVG goes through the logo upload's safety scan first (`picture_size` when it fails); it is held and charged like any other picture and linked as `<sha256>.svg`.
- 429: Too many uploads at once.
- 503 (`editor_unavailable`): “The editor isn't available right now.” (code `editor_unavailable`).

### Example request

```sh
curl --request PUT \
  --url https://app.withmestra.com/api/v1/edit/assets/string \
  --header "Authorization: Bearer $MESTRA_TOKEN" \
  --header 'X-Mestra-Edit-Session: string'
```

## Start editing a master

`POST /api/v1/masters/{id}/versions/{n}/edit`

Permission: Designs · Read.

Opens one version of a saved master for editing and answers the session: its id, the master's elements, the check of the design rules and the checkpoint `loaded`, plus `master` (its id, the version opened, the latest version, its name, source app, brand and whether its app can pull changes), `ifMatch` (the latest version number: send it as `If-Match` on Save), `ruleSets` (each campaign whose rule set lists this master, with the elements it locks to a range of scales) and `copyOverrides` (per role, how many campaigns set their own copy). `n` is a version number or `latest`. Send the session id in `X-Mestra-Edit-Session` on every later call, which are the same Update, Check, Preview and Save calls as for a size, and Update also takes the master's own edits (`set_shape`, `set_opacity`, `set_role`, and `verticalAlign`, `caps` and `paras` on text); Save makes the master's next version, and answers `412` (`version_changed`) with the `latest` version and who made it when the master has a newer one than `ifMatch`. A session belongs to the key that opened it, ends after an hour unused and is lost if the service restarts: a later call that answers `404` (`session_gone`) means open the master again. Needs the Designs · Read permission, and a key that opens must also hold a Write permission somewhere: a key whose only permission is Designs · Read cannot open.

### Parameters

- `id` (string (uuid), required):
- `n` (string, required): A version number, or `latest`.
- `warm` (string, optional): `1` opens a warm session, held briefly ahead of a click. One of: `1`.

### Returns

The session, the identity plan, the composition and its pictures, and the master.

An object with:

- `session` (string, required): The session id, 32 hex characters.
- `elements` (array of objects, required): The master's elements in words, in plan order. Each says its `kind` (a picture is `image`), its `role`, whether the role is the person's choice (`roleChosen`) and what Auto would give it (`suggestedRole`).
  - `ref` (string, required): The element's ref, for `ref` (or `id`) in an edit's input.
  - `role` (string, required): The element's role as an edit may send it: lower case, words joined by `_`. Empty when it has none.
  - `name` (string, required):
  - `kind` (string, required): `text`, `image`, `shape`, `group` or `vector`; empty for an element the design adds.
  - `kept` (boolean, required): False when the element has been dropped.
  - `frame` (object, required): The element's box in the design's own units.
    - `x` (number, optional):
    - `y` (number, optional):
    - `w` (number, optional):
    - `h` (number, optional):
  - `text` (string, required, nullable): A text element's copy as it stands, paragraphs joined by a line break; null for any other element, and for every element in an answer that refuses an edit (a refusal carries no copy).
  - `rotation` (number, optional): A turned element only (one its master turns): its angle in degrees, as the master holds it. On a size it does not change.
  - `ownFrame` (object, optional): A turned element only, and only when the master stores its own size. The unturned frame its copy sets in, in the design's own units: the rectangle `frame` (the box round it) is the turned box of. It is what `set_frame` takes and gives for the element's `x`, `y`, `w` and `h`, so send numbers from this, not from `frame`. Within about 3 degrees of 45 the size draws the master's aspect, and this is that frame.
    - `x` (number, optional):
    - `y` (number, optional):
    - `w` (number, optional):
    - `h` (number, optional):
  - `roleChosen` (boolean, optional): A master's element only. True when the role is the person's choice; false when it is the one Mestra suggested (Auto), which a later save of the master may suggest differently. A master saved before Mestra kept this answers true for every element.
  - `z` (integer, optional): A master's element only. Its place in the stacking: a higher z is in front. A group's is its topmost member's.
  - `group` (string, optional): A master's element only, and only when it is a member of a group: the group's ref.
  - `members` (array of strings, optional): A group's entry only (`kind` is `group`): the refs of its members, back to front. A master's groups are listed beside its elements, each with the box around its members, so `set_order` and `ungroup` have a ref to name. A master's nested groups (a clip group's clip is on one) are listed the same way, each with `group` set to the group or nested group it is under and its members the elements under it; the id is what `set_order`, `set_rotation`, `move_unit`, `scale_unit` and `ungroup` take for it.
  - `look` (object, optional): A master's element only, and only when it has an effect or a paint. Its look in words: `effects` are the effect types in order (a level's after the look's own) and `paints` is how many fills and strokes it has.
    - `effects` (array of strings, optional):
    - `paints` (integer, optional):
  - `suggestedRole` (string, optional): A master's element only. The role Mestra suggests for the element, in the same form as `role`: what choosing Auto would give it. For an element whose role is suggested it is its own role.
- `format` (object, required): The master's own page as a format: key `master`, the master's name, the page's width, height and unit (`px` for px and pt, `mm` for mm).
  - `key` (string, optional):  One of: `master`.
  - `name` (string, optional):
  - `width` (number, optional):
  - `height` (number, optional):
  - `unit` (string, optional):  One of: `px`, `mm`.
- `check` (object, required): The plan's check. `results` is every rule the check judged, with the number it measured; a client that gets none shows the failures and warnings alone.
  - `failures` (array of strings, required):
  - `warnings` (array of strings, required):
  - `objective` (integer, required):
  - `results` (array of objects, optional):
    - `source` (string, required): `brand` for the brand's rules, `spec` for the screen spec. One of: `brand`, `spec`.
    - `code` (string, required):
    - `ref` (string, optional, nullable): The element the rule judged, or null for a whole-size rule.
    - `pass` (boolean, required):
    - `measured` (number, optional, nullable):
    - `limit` (number, optional, nullable):
    - `unit` (string, optional, nullable):  One of: `pt`, `px`, `mm`, `ratio`, `share`, `words`, `null`.
    - `at` (string, required): What the result was judged on: the drawing, the plan's boxes, or an earlier state that an edit has since changed. One of: `render`, `plan`, `stale`.
    - `fix` (object, optional): On a failing result only, and only when Mestra knows an edit that clears it: the edit's `name` and `input`, exactly as the edit call takes them, so applying it is one op and one undo step. It was tried on a copy of the session first: the copy took it, the rule is met on that element afterwards, and no failure appeared that the current state lacks. That check covers only what the plan can show (the boxes and sizes of the elements); the copy is never rendered, so a failure that only a drawing shows, such as contrast or a picture's content, is not ruled out. Offered for a text under its type floor (`type-min`), which gets `set_text` with the size that meets it; for a legal line under the legal size (`rule-legal-size`), which gets `set_text` with `paras` naming its paragraphs under the limit and the size that meets it; and for an element outside the safe area (`crs-safe-area`), which gets `move_unit` to the nearest place that puts the element, its lockup and the units grouped with it inside the safe area (none when they are together bigger than it). Its numbers are in the edit's own units, page units for a place and points for a size. It is computed on the state the answer shows: apply it to that state, not a later one. A master gets none (its type size is only ever a warning), and neither does a result judged on an earlier state (`at` is `stale`). This is not the answer's `fixes`, which lists what Mestra already did on its own.
      - `name` (string, required): An edit the apply call takes, such as `set_text` or `move_unit`.
      - `input` (object, required): The edit's input.
- `sizeDrift` (array of strings, required): Always empty for a master.
- `label` (string, required): The first checkpoint, `loaded`.
- `master` (object, required):
  - `id` (string (uuid), required):
  - `version` (integer, required): The version opened.
  - `latest` (integer, required): The master's latest version when the session opened.
  - `name` (string, required):
  - `sourceApp` (string, required): The app the master was made in.
  - `brand` (string, required): The brand's code.
  - `canPull` (boolean, required): Whether the master's app has Pull master changes (InDesign and Figma).
- `ifMatch` (integer, required): `latest`: send it as `If-Match` on Save.
- `ruleSets` (array of objects, required): Each campaign whose current rule set lists a version of this master, so you know what a size made from it is held to. Empty (`[]`) for a key without the Campaigns · Read permission.
  - `campaign` (string, required): The campaign's key.
  - `name` (string, required):
  - `lists` (array of integers, required): The version numbers of this master the campaign's current rule set lists.
  - `locked` (array of objects, required): The elements the rule set holds to a range of scales; empty when it locks none.
    - `element` (string, required): The element's role, such as `logo`.
    - `minScale` (number, required):
    - `maxScale` (number, required):
- `copyOverrides` (object, required): Per role, how many of the brand's campaigns set their own copy for it: a change to that copy in the master does not reach their sizes. Empty (`{}`) for a key without the Campaigns · Read permission.
- `logos` (array of objects, required): The brand's stored logos (empty when it has none): what `add_element`'s `logo.variant` may name. No bytes: `path` is the route that serves the file.
  - `variant` (string, required):  One of: `primary`, `reversed`.
  - `mime` (string, required): `image/png` or `image/svg+xml`.
  - `width` (integer, required): Pixels; `0` for a vector.
  - `height` (integer, required): Pixels; `0` for a vector.
  - `usable` (boolean, required): Whether `add_element` takes it: a PNG is, and an SVG whose root has a usable `viewBox` is (its `width` and `height` are the `viewBox`'s, rounded; `svg-viewbox` otherwise, width and height 0).
  - `path` (string, required):

### Errors

- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`): `403` for a role below the route's minimum (“Your role (\<role>) can't \<action>.”, or “Choose an organisation first.”), or, for an API key without the permission this call needs, code `wrong_key` with “This key needs the \<Area> · \<Read|Write> permission.” (for example “This key needs the Reviews · Write permission.”), or “This key can't do that.” for a call only the Mestra apps make.
- 404 (`headless_off`): `headless_off`, or “This master can't be opened in the editor” (`code: not_editable`): unknown, another organisation's, a customer's master, a version it has no such number, or `n` is neither a number nor `latest`.
- 409 (`api_off`): “This master can't be opened in the editor” (`code: not_editable`): the version's identity plan could not be loaded. Or `409` with code `api_off` when the API is off for the organisation.
- 500: The master or its fonts could not be read.
- 503 (`editor_unavailable`): “The editor isn't available right now.” (code `editor_unavailable`).

### Example request

```sh
curl --request POST \
  --url https://app.withmestra.com/api/v1/masters/string/versions/string/edit \
  --header "Authorization: Bearer $MESTRA_TOKEN"
```

## Update a campaign's sizes with one edit

`POST /api/v1/edit/sizes`

Permission: Designs · Write.

Makes one edit on many sizes of a campaign at once. For each brand (the campaign's own order, or only the ones in `sites`), the sizes are those of the brand's newest run that has files; `sizes` lists the size keys to edit, or is `"all"`. Each size is opened as an editing session of its own and given the edit, exactly as the open and apply calls do. Nothing is saved: look at the sessions you want, then save them with `PUT /edit/sizes`. The body is `{"campaign", "sites"?, "sizes", "edit": {"name", "input"}, "idempotencyKey"?}`; `edit.name` is one of the edits the apply call takes. The answer lists every size asked for, in `results`, and each says what became of it in `outcome`: `applied`, `no_change` (nothing moved), `refused` (with `refused`, `detail`, `limit` and, for a role that matches several elements, `candidates`; the session stays open so you can try another edit on it), `not_editable` (the size has nothing stored to edit, the run is not one that can be edited, the brand is not in the campaign or has no run), `busy` (the editor had no room; 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 send as `If-Match` when saving. With an `idempotencyKey`, sending the same request again answers the first call's result with the same sessions and opens nothing more; the same key with a different request is `409`. When every size is done within 10 seconds the answer is `200` with the results; otherwise it is `202` with `{"operation", "status": "running", "done", "total", "results"}`, where `results` are the sizes finished so far in the order asked, and the work goes on in the background (up to four sizes at a time). Read the operation with `GET /edit/sizes/operations/{id}` until its `status` is `done`. A repeat with the same key while it runs answers the same operation. One change across sizes (`POST` or `PUT /edit/sizes`) runs for you at a time: another call while one is running is `409` with code `sizes_busy` (`Another change across sizes is still running. Wait for it to finish, then try again.`). If your key is revoked, or you are removed from the organisation, while it runs, the sizes not yet started are listed as `failed` with status `401`. Needs the Designs · Write permission.

### Parameters

- `campaign` (string, required): The campaign's key.
- `sites` (array of strings, optional): Site codes to edit. Omit for every brand of the campaign.
- `sizes` (one of, required): Size keys, or the string `"all"` for every size of the brand.
- `edit` (object, required):
  - `name` (string, required): One of the edits the apply call takes.
  - `input` (object, optional):
- `idempotencyKey` (string (uuid), optional): A UUID you make for this call.

### Returns

One result per size asked for, when every size was done within 10 seconds.

An object with:

- `results` (array of objects, optional):
  - `run` (string, optional): The brand's newest run the size belongs to. Absent when the brand has none.
  - `site` (string, required):
  - `size` (string, optional): The size's key. Absent on a result for a whole brand (no run, or not in the campaign).
  - `outcome` (string, required): `applied`, `no_change` (nothing moved), `refused` (see `refused`), `not_editable`, `busy` (the editor had no room; try this size again) or `failed` (see `status` and `code`). One of: `applied`, `no_change`, `refused`, `not_editable`, `busy`, `failed`.
  - `status` (integer, optional): With `busy` and `failed`: the status of the call that did not succeed.
  - `code` (string, optional): With `not_editable` (`not_editable`, `no_run` or `site_not_in_campaign`), `busy` and `failed`: the code the call answered.
  - `session` (string, optional): With `applied`, `no_change` and `refused`: the editing session the size was opened in. Send it in `X-Mestra-Edit-Session` to look at the size or edit it further, and in `PUT /edit/sizes` to save it.
  - `sceneHash` (string, optional): With a session: the scene hash to send as `If-Match` on the first save.
  - `label` (string, optional): The checkpoint the edit made, when it made one.
  - `check` (object, optional): The plan's check. `results` is every rule the check judged, with the number it measured; a client that gets none shows the failures and warnings alone.
    - `failures` (array of strings, required):
    - `warnings` (array of strings, required):
    - `objective` (integer, required):
    - `results` (array of objects, optional):
      - `source` (string, required): `brand` for the brand's rules, `spec` for the screen spec. One of: `brand`, `spec`.
      - `code` (string, required):
      - `ref` (string, optional, nullable): The element the rule judged, or null for a whole-size rule.
      - `pass` (boolean, required):
      - `measured` (number, optional, nullable):
      - `limit` (number, optional, nullable):
      - `unit` (string, optional, nullable):  One of: `pt`, `px`, `mm`, `ratio`, `share`, `words`, `null`.
      - `at` (string, required): What the result was judged on: the drawing, the plan's boxes, or an earlier state that an edit has since changed. One of: `render`, `plan`, `stale`.
      - `fix` (object, optional): On a failing result only, and only when Mestra knows an edit that clears it: the edit's `name` and `input`, exactly as the edit call takes them, so applying it is one op and one undo step. It was tried on a copy of the session first: the copy took it, the rule is met on that element afterwards, and no failure appeared that the current state lacks. That check covers only what the plan can show (the boxes and sizes of the elements); the copy is never rendered, so a failure that only a drawing shows, such as contrast or a picture's content, is not ruled out. Offered for a text under its type floor (`type-min`), which gets `set_text` with the size that meets it; for a legal line under the legal size (`rule-legal-size`), which gets `set_text` with `paras` naming its paragraphs under the limit and the size that meets it; and for an element outside the safe area (`crs-safe-area`), which gets `move_unit` to the nearest place that puts the element, its lockup and the units grouped with it inside the safe area (none when they are together bigger than it). Its numbers are in the edit's own units, page units for a place and points for a size. It is computed on the state the answer shows: apply it to that state, not a later one. A master gets none (its type size is only ever a warning), and neither does a result judged on an earlier state (`at` is `stale`). This is not the answer's `fixes`, which lists what Mestra already did on its own.
        - `name` (string, required): An edit the apply call takes, such as `set_text` or `move_unit`.
        - `input` (object, required): The edit's input.
  - `refused` (string, optional): With `refused`: the refusal code.
  - `detail` (string, optional): Refs, field names and numbers; never copy.
  - `limit` (object, optional): With `refused`: the bound the edit ran into.
  - `candidates` (array of objects, optional): With `refused` `ambiguous_role`: every kept element that has the role.
    - `ref` (string, required):
    - `role` (string, required):
    - `name` (string, required):
  - `elements` (array of objects, optional): With a session: the size's elements after the edit, in plan order, as the apply answer lists them, so a session can be shown without another call.
    - `ref` (string, required): The element's ref, for `ref` (or `id`) in an edit's input.
    - `role` (string, required): The element's role as an edit may send it: lower case, words joined by `_`. Empty when it has none.
    - `name` (string, required):
    - `kind` (string, required): `text`, `image`, `shape`, `group` or `vector`; empty for an element the design adds.
    - `kept` (boolean, required): False when the element has been dropped.
    - `frame` (object, required): The element's box in the design's own units.
      - `x` (number, optional):
      - `y` (number, optional):
      - `w` (number, optional):
      - `h` (number, optional):
    - `text` (string, required, nullable): A text element's copy as it stands, paragraphs joined by a line break; null for any other element, and for every element in an answer that refuses an edit (a refusal carries no copy).
    - `rotation` (number, optional): A turned element only (one its master turns): its angle in degrees, as the master holds it. On a size it does not change.
    - `ownFrame` (object, optional): A turned element only, and only when the master stores its own size. The unturned frame its copy sets in, in the design's own units: the rectangle `frame` (the box round it) is the turned box of. It is what `set_frame` takes and gives for the element's `x`, `y`, `w` and `h`, so send numbers from this, not from `frame`. Within about 3 degrees of 45 the size draws the master's aspect, and this is that frame.
      - `x` (number, optional):
      - `y` (number, optional):
      - `w` (number, optional):
      - `h` (number, optional):
    - `roleChosen` (boolean, optional): A master's element only. True when the role is the person's choice; false when it is the one Mestra suggested (Auto), which a later save of the master may suggest differently. A master saved before Mestra kept this answers true for every element.
    - `z` (integer, optional): A master's element only. Its place in the stacking: a higher z is in front. A group's is its topmost member's.
    - `group` (string, optional): A master's element only, and only when it is a member of a group: the group's ref.
    - `members` (array of strings, optional): A group's entry only (`kind` is `group`): the refs of its members, back to front. A master's groups are listed beside its elements, each with the box around its members, so `set_order` and `ungroup` have a ref to name. A master's nested groups (a clip group's clip is on one) are listed the same way, each with `group` set to the group or nested group it is under and its members the elements under it; the id is what `set_order`, `set_rotation`, `move_unit`, `scale_unit` and `ungroup` take for it.
    - `look` (object, optional): A master's element only, and only when it has an effect or a paint. Its look in words: `effects` are the effect types in order (a level's after the look's own) and `paints` is how many fills and strokes it has.
      - `effects` (array of strings, optional):
      - `paints` (integer, optional):
    - `suggestedRole` (string, optional): A master's element only. The role Mestra suggests for the element, in the same form as `role`: what choosing Auto would give it. For an element whose role is suggested it is its own role.

### Errors

- 400 (`master_only`): A field that isn't right: `campaign`, `sizes`, `edit.name` (“That edit isn't one the editor makes.”, or code `master_only` for one that is made on a master) or `idempotencyKey`.
- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`): `403` for a role below the route's minimum (“Your role (\<role>) can't \<action>.”, or “Choose an organisation first.”), or, for an API key without the permission this call needs, code `wrong_key` with “This key needs the \<Area> · \<Read|Write> permission.” (for example “This key needs the Reviews · Write permission.”), or “This key can't do that.” for a call only the Mestra apps make.
- 404 (`campaign_not_found`): “That campaign doesn't exist.” (code `campaign_not_found`).
- 409 (`api_off`, `idempotency_conflict`, `sizes_busy`): `api_off`: an owner hasn't turned the API on for this organisation. Or “That key was already used for a different edit.” (code `idempotency_conflict`). Or “Another change across sizes is still running. Wait for it to finish, then try again.” (code `sizes_busy`).
- 503 (`editor_unavailable`): “The editor isn't available right now.” (code `editor_unavailable`).

### Example request

```sh
curl --request POST \
  --url https://app.withmestra.com/api/v1/edit/sizes \
  --header "Authorization: Bearer $MESTRA_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"campaign":"winter-sale","sizes":["300x250","728x90"],"edit":{"name":"set_text","input":{"role":"headline","text":"Book now"}},"idempotencyKey":"9c1f6a0e-7a52-4e0b-b1d3-5d5b6f1d2a10"}'
```

## Update many sizes with their edits

`PUT /api/v1/edit/sizes`

Permission: Designs · Write.

Saves several open editing sessions, one after another, each as `PUT /edit/save` saves one: the design is drawn, the size's files are replaced, the edit joins the run's review, and the `size.edited` event is sent. The body is `{"sizes": [{"session", "ifMatch"}], "idempotencyKey"?}`, where each `session` is the id an open call or `POST /edit/sizes` answered and `ifMatch` is the `sceneHash` it holds. Each save stands on its own: the answer lists every session in `results`, with `outcome` `saved` (and `sceneHash`, `round`, `pull` and `fileId`) or `failed` (with the `status` and `code` the single save would have answered, such as `scene_changed`, `session_gone`, `stand_in`, `lossy` or `editor_busy`). A failed size changes nothing and the others are still saved. With an `idempotencyKey` every save is made under it, as the single save is, so sending the same request again answers the saves that were made, writes no second round, and saves the sizes that failed. When every save is done within 10 seconds the answer is `200` with the results; otherwise it is `202` with an operation, read with `GET /edit/sizes/operations/{id}` as for `POST /edit/sizes`; the saves go on in the background, up to four at a time, and each is kept as it is made. One change across sizes (`POST` or `PUT /edit/sizes`) runs for you at a time: another call while one is running is `409` with code `sizes_busy`; a revoked key stops the saves not yet started (listed `failed`, status `401`). Needs the Designs · Write permission.

### Parameters

- `sizes` (array of objects, required):
  - `session` (string, required):
  - `ifMatch` (string, optional): The `sceneHash` the session holds.
- `idempotencyKey` (string (uuid), optional): A UUID you make for this call.

### Returns

One result per session, in the order sent, when every save was done within 10 seconds.

An object with:

- `results` (array of objects, optional):
  - `session` (string, required): The session as it was sent.
  - `outcome` (string, required):  One of: `saved`, `failed`.
  - `status` (integer, required): The status the single save would have answered.
  - `code` (string, optional): With `failed`: the save's own error code, such as `scene_changed`, `session_gone`, `stand_in`, `lossy`, `editor_busy` or `if_match_required`.
  - `sceneHash` (string, optional): With `saved`: the size's new scene hash, the `ifMatch` of its next save.
  - `round` (integer, optional, nullable): The review round written, or null when none was.
  - `pull` (string, optional):  One of: `ready`, `quiet`, `not_sent`, `superseded`, `none`.
  - `fileId` (string, optional, nullable):
  - `version` (integer, optional): A master session only: the master's new version.

### Errors

- 400: A field that isn't right: `sizes` or `idempotencyKey`.
- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`): `403` for a role below the route's minimum (“Your role (\<role>) can't \<action>.”, or “Choose an organisation first.”), or, for an API key without the permission this call needs, code `wrong_key` with “This key needs the \<Area> · \<Read|Write> permission.” (for example “This key needs the Reviews · Write permission.”), or “This key can't do that.” for a call only the Mestra apps make.
- 409 (`api_off`, `sizes_busy`): `api_off`: an owner hasn't turned the API on for this organisation. Or “Another change across sizes is still running. Wait for it to finish, then try again.” (code `sizes_busy`).
- 503 (`editor_unavailable`): “The editor isn't available right now.” (code `editor_unavailable`).

### Example request

```sh
curl --request PUT \
  --url https://app.withmestra.com/api/v1/edit/sizes \
  --header "Authorization: Bearer $MESTRA_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"sizes":[{"session":"3f9c1a7e5b2d4c60a1e8b7d9c4f20a13","ifMatch":"a1b2c3d4e5f60718"},{"session":"0d4e7a91c3b84f2e8a6b1c5d7e9f3a24","ifMatch":"b2c3d4e5f6071829"}],"idempotencyKey":"5b0e4a5e-2c7d-4f43-9d52-0d8f8b0a3c11"}'
```

## Retrieve a slow edit or save across sizes

`GET /api/v1/edit/sizes/operations/{id}`

Permission: Designs · Write.

Reads an edit or save across sizes that answered `202`. The answer is `{"operation", "kind", "status", "done", "total", "results"}`: `status` is `running` or `done`, and `results` are the sizes finished so far in the order they were asked, each final once listed. When `done` equals `total` the status is `done` and the results are the same as the `200` of the call would have been. Only the organisation and user that started the call can read it; anyone else, and an operation that has ended, are `404` with code `operation_gone`. Needs the Designs · Write permission.

### Parameters

- `id` (string, required): The operation id a `202` from `POST /edit/sizes` or `PUT /edit/sizes` answered.

### Returns

The operation, running or done.

An object with:

- `operation` (string, required): The operation's id: random, and not a session id. Read it at `GET /edit/sizes/operations/{id}`.
- `kind` (string, required): Which call this is: `edit` (`POST /edit/sizes`; each result is an `EditSizeResult`) or `save` (`PUT /edit/sizes`; each result is a `SaveSizeResult`). One of: `edit`, `save`.
- `status` (string, required):  One of: `running`, `done`.
- `done` (integer, required): How many results are listed.
- `total` (integer, required): How many sizes (or sessions) the call has.
- `results` (array of objects, required): The results listed so far, in the order asked. A listed result is final. Each is an `EditSizeResult` for an edit and a `SaveSizeResult` for a save.

### Errors

- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`): `403` for a role below the route's minimum (“Your role (\<role>) can't \<action>.”, or “Choose an organisation first.”), or, for an API key without the permission this call needs, code `wrong_key` with “This key needs the \<Area> · \<Read|Write> permission.” (for example “This key needs the Reviews · Write permission.”), or “This key can't do that.” for a call only the Mestra apps make.
- 404 (`operation_gone`): “That operation has ended, or it isn't one of yours.” (code `operation_gone`): unknown, ended, or started by someone else, in the same words for all three.
- 409 (`api_off`): `409` with code `api_off` (“Turn on the API in Developer → API and MCP first.”): an owner hasn't turned the API on for this organisation, so no API key works yet. An owner turns it on in Settings, then API.
- 503 (`editor_unavailable`): “The editor isn't available right now.” (code `editor_unavailable`).

### Example request

```sh
curl --request GET \
  --url https://app.withmestra.com/api/v1/edit/sizes/operations/string \
  --header "Authorization: Bearer $MESTRA_TOKEN"
```

## Start a design from blank

`POST /api/v1/designs/new/edit`

Permission: Designs · Write.

Starts a design from a blank page and answers the session. Send `campaign` (a campaign's key), `sizes` (the campaign's size keys ticked for the design's first run; left out, every size of the campaign for the brand, and `[]` ticks none) and, to pick the page the design is drawn at, `designAt`: `{"format": "<one of the ticked sizes>"}` or `{"custom": {"w": 1080, "h": 1920, "unit": "px"}}` (`px` or `mm`; each side from 1 to 20000). Without `designAt` the page is the ticked size whose shape is the middle one of the set; of equal ones the larger. `site` names the brand of a campaign that has several (the first is used without it). With `campaign` set to `no-campaign` the design belongs to no campaign: `site` (a brand's code) is required (`400` `site_required`, `unknown_site`), `sizes` are the organisation's own sizes (format keys; left out, none are ticked; an unknown key is `400` `unknown_format`, the field is `sizes[i]`) and `customSizes` are typed sizes, `[{"w": 640, "h": 480, "unit": "px"}]` (`px` or `mm`), each made a format of the organisation if it has none like it and ticked with the rest; `customSizes` with a real campaign is refused (field `customSizes`). A typed size sent as `designAt.custom` that is also in `customSizes` is drawn as that size's format (`designAt` then answers its `format`). At least one size, typed size or custom page is needed (`sizes_required`). The page takes that size's safe area as its margins. The answer is the same as for Start editing a master, with `draft: true`, `master: null` and `ifMatch: null` (nothing is stored yet), plus `sizes` (each ticked size: `key`, `name`, `width`, `height`, `unit` and its `screenSpec`, or `null`) and `designAt` (the page that was used, in the form you send it). Send the session id in `X-Mestra-Edit-Session` on every later call (Update, Check, Preview and the picture upload work as for a master; an edit that names an element answers `unknown-ref` while the page is empty). Update takes `add_element` (kinds `text`, `shape`, `image`, `line`, `polygon`, `star`), `place_picture`, `set_picture`, `set_adjust`, `set_mask`, `set_order`, `make_group`, `release_clip`, `ungroup`, `set_look`, `set_paras_paint`, `set_paras_indent`, `set_paras_decoration`, `set_paras_breaks`, `set_flip`, `set_rotation` and `set_shape` (with the composition's own shape fields: `radii`, `cornerStyle`, `cornerStyles`, `dash`, `dashOffset`, `dashFit`, `cap`, `join`, `miterLimit`, `gap`, `stripes`, `sides`, `ends`, `strokeAlign`, and `polygon` and `star` for a path's outline), and the master's own edits `set_opacity`, `set_role`, `set_text` and `set_style` (see Update a size being edited); Save makes the master (see Save an editing session's plan as the size's file). Refusals: `404` `unknown_campaign`; `400` `size_not_in_campaign` (the field is `sizes[i]`), `bad_custom_size` (the field, with `min` and `max`), `design_at_not_ticked`, `sizes_required`, `unknown_site`; `403` `wrong_key` for a key without the Campaigns · Read permission (the design is made of the campaign's name and sizes), or, with no campaign, without Brand · Read. Needs the Designs · Write and Campaigns · Read permissions (Brand · Read in place of Campaigns · Read with no campaign). The first save's answer carries `campaign` (`no-campaign` for such a design), `site` and `sizes`.

### Parameters

- `campaign` (string, required): A campaign's key, or `no-campaign` for a design that belongs to none.
- `sizes` (array of strings, optional): Size (format) keys of the campaign, ticked for the design's first run; with no campaign, keys of the organisation's own formats (left out: none). A key twice counts once.
- `customSizes` (array of objects, optional): Only with `no-campaign`: typed sizes. Each is made a format of the organisation (an existing one of that size is reused) and joins the ticked sizes.
  - `w` (number, required):
  - `h` (number, required):
  - `unit` (string, optional): Blank is `px`. One of: `px`, `mm`.
- `designAt` (object, optional): The page the design is drawn at: exactly one of `format` and `custom`. Absent: the ticked size of the middle aspect ratio.
  - `format` (string, optional): One of the ticked sizes.
  - `custom` (object, optional):
    - `w` (number, required):
    - `h` (number, required):
    - `unit` (string, required):  One of: `px`, `mm`.
- `site` (string, optional): The brand's code, one of the campaign's. Absent: the campaign's first. Required with `no-campaign`.

### Returns

The session over a blank page.

An object with:

- `session` (string, required): The session id, 32 hex characters.
- `draft` (boolean, required):  One of: `true`.
- `master` (any, required, nullable): Always `null`: nothing is stored yet.
- `ifMatch` (any, required, nullable): Always `null`: there is no version to match.
- `elements` (array of objects, required): Empty on a blank page.
  - `ref` (string, required): The element's ref, for `ref` (or `id`) in an edit's input.
  - `role` (string, required): The element's role as an edit may send it: lower case, words joined by `_`. Empty when it has none.
  - `name` (string, required):
  - `kind` (string, required): `text`, `image`, `shape`, `group` or `vector`; empty for an element the design adds.
  - `kept` (boolean, required): False when the element has been dropped.
  - `frame` (object, required): The element's box in the design's own units.
    - `x` (number, optional):
    - `y` (number, optional):
    - `w` (number, optional):
    - `h` (number, optional):
  - `text` (string, required, nullable): A text element's copy as it stands, paragraphs joined by a line break; null for any other element, and for every element in an answer that refuses an edit (a refusal carries no copy).
  - `rotation` (number, optional): A turned element only (one its master turns): its angle in degrees, as the master holds it. On a size it does not change.
  - `ownFrame` (object, optional): A turned element only, and only when the master stores its own size. The unturned frame its copy sets in, in the design's own units: the rectangle `frame` (the box round it) is the turned box of. It is what `set_frame` takes and gives for the element's `x`, `y`, `w` and `h`, so send numbers from this, not from `frame`. Within about 3 degrees of 45 the size draws the master's aspect, and this is that frame.
    - `x` (number, optional):
    - `y` (number, optional):
    - `w` (number, optional):
    - `h` (number, optional):
  - `roleChosen` (boolean, optional): A master's element only. True when the role is the person's choice; false when it is the one Mestra suggested (Auto), which a later save of the master may suggest differently. A master saved before Mestra kept this answers true for every element.
  - `z` (integer, optional): A master's element only. Its place in the stacking: a higher z is in front. A group's is its topmost member's.
  - `group` (string, optional): A master's element only, and only when it is a member of a group: the group's ref.
  - `members` (array of strings, optional): A group's entry only (`kind` is `group`): the refs of its members, back to front. A master's groups are listed beside its elements, each with the box around its members, so `set_order` and `ungroup` have a ref to name. A master's nested groups (a clip group's clip is on one) are listed the same way, each with `group` set to the group or nested group it is under and its members the elements under it; the id is what `set_order`, `set_rotation`, `move_unit`, `scale_unit` and `ungroup` take for it.
  - `look` (object, optional): A master's element only, and only when it has an effect or a paint. Its look in words: `effects` are the effect types in order (a level's after the look's own) and `paints` is how many fills and strokes it has.
    - `effects` (array of strings, optional):
    - `paints` (integer, optional):
  - `suggestedRole` (string, optional): A master's element only. The role Mestra suggests for the element, in the same form as `role`: what choosing Auto would give it. For an element whose role is suggested it is its own role.
- `format` (object, required): The page as a format: key `master`, the campaign's name, the page's width, height and unit.
  - `key` (string, optional):  One of: `master`.
  - `name` (string, optional):
  - `width` (number, optional):
  - `height` (number, optional):
  - `unit` (string, optional):  One of: `px`, `mm`.
- `check` (object, required): The plan's check. `results` is every rule the check judged, with the number it measured; a client that gets none shows the failures and warnings alone.
  - `failures` (array of strings, required):
  - `warnings` (array of strings, required):
  - `objective` (integer, required):
  - `results` (array of objects, optional):
    - `source` (string, required): `brand` for the brand's rules, `spec` for the screen spec. One of: `brand`, `spec`.
    - `code` (string, required):
    - `ref` (string, optional, nullable): The element the rule judged, or null for a whole-size rule.
    - `pass` (boolean, required):
    - `measured` (number, optional, nullable):
    - `limit` (number, optional, nullable):
    - `unit` (string, optional, nullable):  One of: `pt`, `px`, `mm`, `ratio`, `share`, `words`, `null`.
    - `at` (string, required): What the result was judged on: the drawing, the plan's boxes, or an earlier state that an edit has since changed. One of: `render`, `plan`, `stale`.
    - `fix` (object, optional): On a failing result only, and only when Mestra knows an edit that clears it: the edit's `name` and `input`, exactly as the edit call takes them, so applying it is one op and one undo step. It was tried on a copy of the session first: the copy took it, the rule is met on that element afterwards, and no failure appeared that the current state lacks. That check covers only what the plan can show (the boxes and sizes of the elements); the copy is never rendered, so a failure that only a drawing shows, such as contrast or a picture's content, is not ruled out. Offered for a text under its type floor (`type-min`), which gets `set_text` with the size that meets it; for a legal line under the legal size (`rule-legal-size`), which gets `set_text` with `paras` naming its paragraphs under the limit and the size that meets it; and for an element outside the safe area (`crs-safe-area`), which gets `move_unit` to the nearest place that puts the element, its lockup and the units grouped with it inside the safe area (none when they are together bigger than it). Its numbers are in the edit's own units, page units for a place and points for a size. It is computed on the state the answer shows: apply it to that state, not a later one. A master gets none (its type size is only ever a warning), and neither does a result judged on an earlier state (`at` is `stale`). This is not the answer's `fixes`, which lists what Mestra already did on its own.
      - `name` (string, required): An edit the apply call takes, such as `set_text` or `move_unit`.
      - `input` (object, required): The edit's input.
- `sizeDrift` (array of strings, required): Always empty.
- `label` (string, required): The first checkpoint, `loaded`.
- `ruleSets` (array of objects, required): Always empty.
- `copyOverrides` (object, required): Always empty.
- `logos` (array of objects, required): The brand's stored logos (empty when it has none): what `add_element`'s `logo.variant` may name. No bytes: `path` is the route that serves the file.
  - `variant` (string, required):  One of: `primary`, `reversed`.
  - `mime` (string, required): `image/png` or `image/svg+xml`.
  - `width` (integer, required): Pixels; `0` for a vector.
  - `height` (integer, required): Pixels; `0` for a vector.
  - `usable` (boolean, required): Whether `add_element` takes it: a PNG is, and an SVG whose root has a usable `viewBox` is (its `width` and `height` are the `viewBox`'s, rounded; `svg-viewbox` otherwise, width and height 0).
  - `path` (string, required):
- `sizes` (array of objects, required): The ticked sizes, in the order sent.
  - `key` (string, required):
  - `name` (string, required):
  - `width` (number, required):
  - `height` (number, required):
  - `unit` (string, required):
  - `screenSpec` (object, required, nullable): The size's screen spec (network, format, viewing distance and what it asks), or `null` when it has none.
- `designAt` (object, required): The page the design is drawn at: `{format}` or `{custom: {w, h, unit}}`.

### Errors

- 400 (`size_not_in_campaign`, `bad_custom_size`, `design_at_not_ticked`, `sizes_required`, `unknown_site`): A refused field: `field` names it (`sizes[i]`, `designAt`, `designAt.format`, `designAt.custom.w`, `site`) and `code` is `size_not_in_campaign`, `bad_custom_size` (with `min` and `max`), `design_at_not_ticked`, `sizes_required` or `unknown_site`; or a body that is not the request.
- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`): `403` for a role below the route's minimum (“Your role (\<role>) can't \<action>.”, or “Choose an organisation first.”), or, for an API key without the permission this call needs, code `wrong_key` with “This key needs the \<Area> · \<Read|Write> permission.” (for example “This key needs the Reviews · Write permission.”), or “This key can't do that.” for a call only the Mestra apps make.
- 404 (`headless_off`, `unknown_campaign`, `not_editable`): `headless_off`; `unknown_campaign`; or `not_editable` for a Network customer.
- 409 (`api_off`): `409` with code `api_off` when the API is off for the organisation. The design's identity plan could not be loaded: “This master can't be opened in the editor” (`code: not_editable`).
- 413: The body is over 64 KB.
- 500: The page or its fonts could not be read.
- 503 (`editor_unavailable`): “The editor isn't available right now.” (code `editor_unavailable`).

### Example request

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