# Saved masters

A saved master is a design kept in Mestra, saved once from InDesign, Figma or Canva, so that it can be built into sizes without opening the design app. A master has to be checked and `ready` before a server run can use it.

A saved master is a design kept in Mestra, saved once from InDesign, Figma or Canva, so that it can be built into sizes without opening the design app. A master has to be checked and `ready` before a server run can use it.

## The Saved master object

The saved master object. Its `status` says whether it can make server runs.

- `id` (string (uuid), required): The master's id.
- `name` (string, required): The master's name, as saved from the design app.
- `brand` (string, required): The brand code.
- `sourceApp` (string, required): Where the master was made: the design app it was saved from (`indesign`, `figma`, `canva`), `upload` for one made from an uploaded file, or `mestra` for one made in Mestra's own editor. One of: `indesign`, `figma`, `canva`, `upload`, `mestra`.
- `madeInMestra` (boolean, optional): True when any version of the master was made in Mestra's own editor, so a design app can open it. Stays true after a design app saves a later version.
- `status` (string, required): `checking`: still being checked; `ready`: can make runs; `not_ready`: see `reasons`. One of: `checking`, `ready`, `not_ready`.
- `reasons` (array of objects, required): Why the master can't make runs. Empty when it is ready.
  - `code` (string, required): A short code: `font`, `artwork`, `snapshot`, `invalid` or `resave`.
  - `element` (string, optional): The composition element the reason is about, when it is about one.
  - `text` (string, required): What to do, as the apps and the web show it (`Add font: Jost Bold`).
  - `family` (string, optional): A `font` reason: the family to add, apart from the style in `text`.
- `savedBy` (string, required): The saver's name; empty when unknown.
- `runs` (integer, optional): How many server runs the master has had so far (the list only).
- `lastRunAt` (string (date-time), optional): When the latest run started; absent without any (the list only).
- `savedAt` (string (date-time), required): When the master was last saved.
- `checkedAt` (string (date-time), required, nullable): When the check finished; null while it is still running.
- `pageWidth` (number, required): The page width of the design, in its own units.
- `pageHeight` (number, required): The page height of the design, in its own units.
- `size` (integer (int64), required): The composition's and every file's bytes.
- `replaced` (boolean, optional): Only on a save: true when it replaced the same document's earlier save.
- `unchanged` (boolean, optional): Only on a save: true when the design matched the master's latest version, so nothing was stored (`200`).
- `version` (integer, optional): The version this save made, or on an unchanged save the version that matched, which is the latest.

```json
{
  "id": "3f6c1b52-8d3e-4c7a-9a41-5b0e2f7d8c11",
  "name": "Spring launch master",
  "brand": "ESP",
  "sourceApp": "indesign",
  "status": "ready",
  "reasons": [],
  "savedBy": "Alex Morgan",
  "runs": 2,
  "lastRunAt": "2027-09-02T01:15:00Z",
  "savedAt": "2027-09-01T23:40:12Z",
  "checkedAt": "2027-09-01T23:40:31Z",
  "pageWidth": 1080,
  "pageHeight": 1080,
  "size": 2814337
}
```

## Create a saved master

`POST /api/v1/masters`

Permission: Runs · Write.

Saves a design from a design app so that server runs can build from it. Saving a document that was already saved replaces that master in place (`200`, `replaced: true`) and it is checked again; a new master is `201`. The organisation must keep its work, or the request is refused with `409 dont_keep`. Send the parts in the order shown in the request body.

### Parameters

- `composition` (string, required): Required. The design as one JSON object: its `version`, its page `width` and `height`, and its `elements` (text, images, vectors and shapes, each with an `id`). Up to 2,000,000 bytes; the request is refused if it isn't a valid composition. Send it as a text field, before every other part.
- `meta` (string, required): Required. A JSON object, up to 16 KB, describing the save: `name` (up to 200 characters), `docKey` (up to 512 characters; your stable id for the source document, which is how a second save finds the master to replace), `site` (a brand on your account), `sourceApp` (`indesign`, `figma` or `canva`) and `snapshot` (`mime` `image/png`, plus the picture's `width`, `height` and `size` in bytes). Send it as a text field, second.
- `assets` (string, required): Required. A JSON array, up to 1 MB, with one entry per image or vector file you send: `elementId` (the composition element it fills), `kind` (`image` or `vector`), `mime` (`image/svg+xml` for a vector), `width`, `height`, `size` in bytes and `placement` (a small JSON object, or null). Each element appears at most once; send `[]` if the design has no pictures. Send it as a text field, third.
- `snapshot` (file, required): Required. A PNG picture of the whole design, used as its preview, sent as a file part with exactly the `size` given in `meta.snapshot`. At most 95 MB and 16 million pixels.
- `assets` (file, optional): One file part per entry in `assets`, named `asset:<elementId>` (for example `asset:el-12`), sent after `snapshot` in the same order as `assets`. Each must be exactly the `size` its entry gives, at most 95 MB and 40 million pixels; vectors are SVG files and pictures are PNG, JPEG or WebP.

### Returns

Replaced in place.

### Errors

- 400: “That master couldn't be read. Save it again.” (a part is missing, repeated, out of order or not what it says, an SVG that isn't plain, or not a composition) or a field error on `site`.
- 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` (saved masters aren't on for this server, or for this organisation), or “That master isn't here any more.” (unknown or another organisation's).
- 409 (`dont_keep`, `brand_changed`, `name_taken`, `api_off`): `dont_keep`: “Saving masters needs the library to keep files. Choose how long to keep work in Settings.”; `busy`: “That master is being saved. Try again.”; `brand_changed`: “This document is already saved for another brand.”; or `name_taken`: “A master with that name is already saved for this brand.” with `master` (`id`, `name`) of the one that holds the name; only when the request sends `savedHow`. Answer with `onClash`. With an API key, `api_off` (“Turn on the API in Developer → API and MCP first.”) when an owner has turned the API off.
- 411: “Send the master's size (Content-Length).”
- 413: “That master is too large to keep.” or a part over its limit.
- 429: “Too many uploads at once. Try again shortly.”
- 507: “Your organisation's cloud storage is full.”

### Example request

```sh
curl --request POST \
  --url https://app.withmestra.com/api/v1/masters \
  --header "Authorization: Bearer $MESTRA_TOKEN" \
  --form 'composition={"version":1, "elements":[...]}' \
  --form 'meta={"name":"Spring launch master","docKey":"doc-7f31","site":"ESP","sourceApp":"indesign","snapshot":{"mime":"image/png","width":1080,"height":1080,"size":812004}}' \
  --form 'assets=[{"elementId":"el-12","kind":"image","mime":"image/jpeg","width":2400,"height":1600,"size":734002,"placement":"fill"}]' \
  --form snapshot=@snapshot.bin \
  --form asset:el-12=@asset-el-12.bin
```

## Retrieve a saved master

`GET /api/v1/masters/{id}`

Permission: Runs · Read.

Returns the master, including whether it is `checking`, `ready` or `not_ready` and, if not ready, `reasons`. A master of another organisation is a `404`.

### Parameters

- `id` (string (uuid), required):

### Returns

The master.

### 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 (`headless_off`): `headless_off` (saved masters aren't on for this server, or for this organisation), or “That master isn't here any more.” (unknown or another organisation'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.

### Example request

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

## Update a saved master

`PUT /api/v1/masters/{id}`

Permission: Runs · Write.

Saves the master again, replacing it in place. `meta.docKey` must be the master's own, or the request is refused with `400`. The parts and answers are the same as Create a saved master.

### Parameters

- `id` (string (uuid), required):
- `composition` (string, required): Required. The design as one JSON object: its `version`, its page `width` and `height`, and its `elements` (text, images, vectors and shapes, each with an `id`). Up to 2,000,000 bytes; the request is refused if it isn't a valid composition. Send it as a text field, before every other part.
- `meta` (string, required): Required. A JSON object, up to 16 KB, describing the save: `name` (up to 200 characters), `docKey` (up to 512 characters; your stable id for the source document, which is how a second save finds the master to replace), `site` (a brand on your account), `sourceApp` (`indesign`, `figma` or `canva`) and `snapshot` (`mime` `image/png`, plus the picture's `width`, `height` and `size` in bytes). Send it as a text field, second.
- `assets` (string, required): Required. A JSON array, up to 1 MB, with one entry per image or vector file you send: `elementId` (the composition element it fills), `kind` (`image` or `vector`), `mime` (`image/svg+xml` for a vector), `width`, `height`, `size` in bytes and `placement` (a small JSON object, or null). Each element appears at most once; send `[]` if the design has no pictures. Send it as a text field, third.
- `snapshot` (file, required): Required. A PNG picture of the whole design, used as its preview, sent as a file part with exactly the `size` given in `meta.snapshot`. At most 95 MB and 16 million pixels.
- `assets` (file, optional): One file part per entry in `assets`, named `asset:<elementId>` (for example `asset:el-12`), sent after `snapshot` in the same order as `assets`. Each must be exactly the `size` its entry gives, at most 95 MB and 40 million pixels; vectors are SVG files and pictures are PNG, JPEG or WebP.

### Returns

Replaced in place.

### Errors

- 400: “That master couldn't be read. Save it again.” (a part is missing, repeated, out of order or not what it says, an SVG that isn't plain, or not a composition) or a field error on `site`.
- 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` (saved masters aren't on for this server, or for this organisation), or “That master isn't here any more.” (unknown or another organisation's).
- 409 (`dont_keep`, `brand_changed`, `name_taken`, `api_off`): `dont_keep`: “Saving masters needs the library to keep files. Choose how long to keep work in Settings.”; `busy`: “That master is being saved. Try again.”; `brand_changed`: “This document is already saved for another brand.”; or `name_taken`: “A master with that name is already saved for this brand.” with `master` (`id`, `name`) of the one that holds the name; only when the request sends `savedHow`. Answer with `onClash`. With an API key, `api_off` (“Turn on the API in Developer → API and MCP first.”) when an owner has turned the API off.
- 411: “Send the master's size (Content-Length).”
- 413: “That master is too large to keep.” or a part over its limit.
- 429: “Too many uploads at once. Try again shortly.”
- 507: “Your organisation's cloud storage is full.”

### Example request

```sh
curl --request PUT \
  --url https://app.withmestra.com/api/v1/masters/string \
  --header "Authorization: Bearer $MESTRA_TOKEN" \
  --form 'composition={"version":1, "elements":[...]}' \
  --form 'meta={"name":"Spring launch master","docKey":"doc-7f31","site":"ESP","sourceApp":"indesign","snapshot":{"mime":"image/png","width":1080,"height":1080,"size":812004}}' \
  --form 'assets=[{"elementId":"el-12","kind":"image","mime":"image/jpeg","width":2400,"height":1600,"size":734002,"placement":"fill"}]' \
  --form snapshot=@snapshot.bin \
  --form asset:el-12=@asset-el-12.bin
```

## List all saved masters

`GET /api/v1/masters`

Permission: Runs · Read.

Returns the organisation's saved masters, newest save first, each with its readiness `status` and, if it isn't ready, the `reasons`.

### Returns

The masters.

An object with:

- `masters` (array of objects, required):
  - `id` (string (uuid), required): The master's id.
  - `name` (string, required): The master's name, as saved from the design app.
  - `brand` (string, required): The brand code.
  - `sourceApp` (string, required): Where the master was made: the design app it was saved from (`indesign`, `figma`, `canva`), `upload` for one made from an uploaded file, or `mestra` for one made in Mestra's own editor. One of: `indesign`, `figma`, `canva`, `upload`, `mestra`.
  - `madeInMestra` (boolean, optional): True when any version of the master was made in Mestra's own editor, so a design app can open it. Stays true after a design app saves a later version.
  - `status` (string, required): `checking`: still being checked; `ready`: can make runs; `not_ready`: see `reasons`. One of: `checking`, `ready`, `not_ready`.
  - `reasons` (array of objects, required): Why the master can't make runs. Empty when it is ready.
    - `code` (string, required): A short code: `font`, `artwork`, `snapshot`, `invalid` or `resave`.
    - `element` (string, optional): The composition element the reason is about, when it is about one.
    - `text` (string, required): What to do, as the apps and the web show it (`Add font: Jost Bold`).
    - `family` (string, optional): A `font` reason: the family to add, apart from the style in `text`.
  - `savedBy` (string, required): The saver's name; empty when unknown.
  - `runs` (integer, optional): How many server runs the master has had so far (the list only).
  - `lastRunAt` (string (date-time), optional): When the latest run started; absent without any (the list only).
  - `savedAt` (string (date-time), required): When the master was last saved.
  - `checkedAt` (string (date-time), required, nullable): When the check finished; null while it is still running.
  - `pageWidth` (number, required): The page width of the design, in its own units.
  - `pageHeight` (number, required): The page height of the design, in its own units.
  - `size` (integer (int64), required): The composition's and every file's bytes.
  - `replaced` (boolean, optional): Only on a save: true when it replaced the same document's earlier save.
  - `unchanged` (boolean, optional): Only on a save: true when the design matched the master's latest version, so nothing was stored (`200`).
  - `version` (integer, optional): The version this save made, or on an unchanged save the version that matched, which is the latest.

### 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 (`headless_off`): `headless_off`: saved masters aren't on for this server, or for this 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.

### Example request

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

## Delete a saved master

`DELETE /api/v1/masters/{id}`

Permission: Runs · Write.

Deletes the master and its files. Server runs already made keep their results.

### Parameters

- `id` (string (uuid), required):

### Returns

Deleted.

### 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` (saved masters aren't on for this server, or for this organisation), or “That master isn't here any more.” (unknown or another organisation'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.

### Example request

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