# Formats

A format is one output size and its rules: width, height, bleed, safe margin, the smallest type allowed, and what must be kept or left out. Formats are grouped into format sets, and a campaign builds every format in its set.

A format is one output size and its rules: width, height, bleed, safe margin, the smallest type allowed, and what must be kept or left out. Formats are grouped into format sets, and a campaign builds every format in its set.

## The Format object

The format object. A format is identified by its `key`.

- `name` (string, required): The format's display name.
- `key` (string, required): The format's key: its identifier in format sets and runs. Unique in the organisation.
- `width` (number, required): Width, in `unit`.
- `height` (number, required): Height, in `unit`.
- `unit` (string, required): The unit of `width`, `height`, `bleed` and `safeMargin`: `px`, `mm` or `pt`. Type sizes are always in points. One of: `px`, `mm`, `pt`.
- `dpi` (number, optional, nullable): Resolution in dots per inch. Needed for `mm` formats; usually null for `px` and `pt`.
- `exportScale` (integer, optional): px and pt formats: exported pixels per page unit: 0 (the default) or 1 to 3, at most 16 MP in all. 0 or absent is the family default (2 for social and web when that fits 16 MP, else 1). Campaign answers always carry it resolved.
- `bleed` (number, optional): Bleed beyond the trim, in `unit`. A format with a bleed is a print size.
- `safeMargin` (number, optional): The margin kept clear of important content, in `unit`.
- `family` (string, optional): The kind of output (for example `print`, `social`, `web` or `screen`). It decides defaults such as the export scale.
- `require` (array of strings, optional, nullable): Elements every layout of this format must keep: `cta`, `qr`. Null or empty for none.
- `drop` (array of strings, optional, nullable): Roles left out of this format (for example `subhead`). Null or empty for none.
- `minTypeSize` (object, optional, nullable): Smallest type size per role, in points.
- `exportFormats` (array of strings, optional, nullable): The file types a review of this format can export (for example `png`, `jpg`, `pdf`). Null for the defaults.
- `reviewPolicy` (string, required): `always` checks every layout of this format; `skip-if-clean` skips the check when the layout is already clean.
- `copyOverrides` (object, optional, nullable): Wording that replaces the campaign's own for this format, by role. Each value is up to 2,000 characters.

```json
{
  "name": "Social story",
  "key": "social-story",
  "width": 1080,
  "height": 1920,
  "unit": "px",
  "dpi": null,
  "bleed": 0,
  "safeMargin": 64,
  "family": "social",
  "require": [
    "cta"
  ],
  "drop": [
    "legal"
  ],
  "minTypeSize": {
    "headline": 48,
    "body": 24
  },
  "exportFormats": [
    "png"
  ],
  "reviewPolicy": "skip-if-clean",
  "copyOverrides": {}
}
```

## Retrieve a format

`GET /api/v1/formats/{key}`

Permission: Brand · Read.

Returns the format with this key, exactly as it was saved.

### Parameters

- `key` (string, required): The document's key (a brand's code).

### Returns

The document.

### 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: “unknown format”
- 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 configuration” or “could not check token”.
- 501: “configuration is read-only here”: this server can't change configuration.

### Example request

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

## Create or update a format

`PUT /api/v1/formats/{key}`

Permission: Brand · Write.

Creates the format with this key, or replaces it if it already exists. The body is strict JSON: unknown fields are refused, and its `key` must equal the one in the path. A value that isn't allowed is refused with `400`, and `field` names it. Send `X-Mestra-Create: 1` to insist on creating (a key that already exists is `409`), or `X-Mestra-Updated-At` with the value from your last save to replace safely (`412` when someone else changed it first). The answer carries the new `X-Mestra-Updated-At`.

### Parameters

- `key` (string, required): The document's key (a brand's code).
- `X-Mestra-Updated-At` (string (date-time), optional): The `X-Mestra-Updated-At` your last save of this document answered with. The write goes ahead only if the document is unchanged since, otherwise `412` (a document deleted since counts as changed). Send either this or `X-Mestra-Create`, not both.
- `X-Mestra-Create` (string, optional): `1`: the write creates the document; a taken key is `409`. A DELETE ignores it. One of: `1`.
- `name` (string, required): The format's display name.
- `key` (string, required): The format's key: its identifier in format sets and runs. Unique in the organisation.
- `width` (number, required): Width, in `unit`.
- `height` (number, required): Height, in `unit`.
- `unit` (string, required): The unit of `width`, `height`, `bleed` and `safeMargin`: `px`, `mm` or `pt`. Type sizes are always in points. One of: `px`, `mm`, `pt`.
- `dpi` (number, optional, nullable): Resolution in dots per inch. Needed for `mm` formats; usually null for `px` and `pt`.
- `exportScale` (integer, optional): px and pt formats: exported pixels per page unit: 0 (the default) or 1 to 3, at most 16 MP in all. 0 or absent is the family default (2 for social and web when that fits 16 MP, else 1). Campaign answers always carry it resolved.
- `bleed` (number, optional): Bleed beyond the trim, in `unit`. A format with a bleed is a print size.
- `safeMargin` (number, optional): The margin kept clear of important content, in `unit`.
- `family` (string, optional): The kind of output (for example `print`, `social`, `web` or `screen`). It decides defaults such as the export scale.
- `require` (array of strings, optional, nullable): Elements every layout of this format must keep: `cta`, `qr`. Null or empty for none.
- `drop` (array of strings, optional, nullable): Roles left out of this format (for example `subhead`). Null or empty for none.
- `minTypeSize` (object, optional, nullable): Smallest type size per role, in points.
- `exportFormats` (array of strings, optional, nullable): The file types a review of this format can export (for example `png`, `jpg`, `pdf`). Null for the defaults.
- `reviewPolicy` (string, required): `always` checks every layout of this format; `skip-if-clean` skips the check when the layout is already clean.
- `copyOverrides` (object, optional, nullable): Wording that replaces the campaign's own for this format, by role. Each value is up to 2,000 characters.

### Returns

The stored (canonical) document.

### Errors

- 400: A value is refused. The answer is `{"error": "<sentence>", "field": "<name>"}` for the first refused value, for example `{"error":"Add a name.","field":"name"}`, `{"error":"Enter a full web address starting with https://.","field":"qrBaseUrl"}` or `{"error":"Width must be more than 0.","field":"width"}`. Nothing is saved. The rules: every kind needs a non-blank `name`; a brand's `qrBaseUrl` and a campaign's `qrUrl` and `externalRef.url`, when not empty, must be full http or https addresses; a campaign's `startDate` and `endDate`, when set, must be real dates (“Enter a valid date.”), and `endDate` can't be before `startDate`; a campaign's `formatSet` is optional, its `formats` (format keys, added to the set's) must each exist and be listed once (a campaign with neither has no sizes until some are added), and it needs at least one brand (“Choose at least one brand.”); a format's width, height, unit, dpi (for mm), safe margin, review policy and lists must be valid; a campaign's `brandRulesOverride.typography` may not set only one of `headlineMaxLines` and `allowedFamilies`. Without a `field`, the answer is a plain sentence: the change would leave a reference to something that doesn't exist, the key isn't allowed (“Keys use letters, numbers, dots, dashes and underscores, up to 64 characters, starting with a letter or number.”), or the headers are wrong (“Send X-Mestra-Create or X-Mestra-Updated-At, not both.”, “X-Mestra-Updated-At must be an updatedAt value from this service.” or “X-Mestra-Create must be 1.”).
- 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`): “That key is already taken.” (`X-Mestra-Create: 1` and a document with that key exists). Nothing is saved. With an API key, also `api_off` (“Turn on the API in Developer → API and MCP first.”) when an owner has turned the API off.
- 412: “Someone else changed this. Reload to see their changes.” (`X-Mestra-Updated-At` is not the document's current `updatedAt`, or the document is gone). Nothing is saved.
- 413: “body exceeds limit (1048576 bytes)”
- 500: “could not save configuration”, “could not read configuration” (re-reading after the change), “could not check token”, or “Couldn't save that change. Try again.” (the change could not be recorded, so it was not made). Nothing is half-saved: try again.
- 501: “configuration is read-only here”: this server can't change configuration.

### Example request

```sh
curl --request PUT \
  --url https://app.withmestra.com/api/v1/formats/string \
  --header "Authorization: Bearer $MESTRA_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"name":"Social story","key":"social-story","width":1080,"height":1920,"unit":"px","dpi":null,"bleed":0,"safeMargin":64,"family":"social","require":["cta"],"drop":["legal"],"minTypeSize":{"headline":48,"body":24},"exportFormats":["png"],"reviewPolicy":"skip-if-clean","copyOverrides":{}}'
```

## List all formats

`GET /api/v1/formats`

Permission: Brand · Read.

Returns every format (a named output size and its rules) the organisation has, sorted by key.

### Returns

Every format.

### 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).
- 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 load configuration” or “could not check token”.

### Example request

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

## Delete a format

`DELETE /api/v1/formats/{key}`

Permission: Brand · Write.

Deletes the format. If a format set or campaign still uses it, the request is refused with `400` and `field` names it.

### Parameters

- `key` (string, required): The document's key (a brand's code).
- `X-Mestra-Updated-At` (string (date-time), optional): The `X-Mestra-Updated-At` your last save of this document answered with. The write goes ahead only if the document is unchanged since, otherwise `412` (a document deleted since counts as changed). Send either this or `X-Mestra-Create`, not both.
- `X-Mestra-Create` (string, optional): `1`: the write creates the document; a taken key is `409`. A DELETE ignores it. One of: `1`.

### Returns

Deleted.

### Errors

- 400: A value is refused. The answer is `{"error": "<sentence>", "field": "<name>"}` for the first refused value, for example `{"error":"Add a name.","field":"name"}`, `{"error":"Enter a full web address starting with https://.","field":"qrBaseUrl"}` or `{"error":"Width must be more than 0.","field":"width"}`. Nothing is saved. The rules: every kind needs a non-blank `name`; a brand's `qrBaseUrl` and a campaign's `qrUrl` and `externalRef.url`, when not empty, must be full http or https addresses; a campaign's `startDate` and `endDate`, when set, must be real dates (“Enter a valid date.”), and `endDate` can't be before `startDate`; a campaign's `formatSet` is optional, its `formats` (format keys, added to the set's) must each exist and be listed once (a campaign with neither has no sizes until some are added), and it needs at least one brand (“Choose at least one brand.”); a format's width, height, unit, dpi (for mm), safe margin, review policy and lists must be valid; a campaign's `brandRulesOverride.typography` may not set only one of `headlineMaxLines` and `allowedFamilies`. Without a `field`, the answer is a plain sentence: the change would leave a reference to something that doesn't exist, the key isn't allowed (“Keys use letters, numbers, dots, dashes and underscores, up to 64 characters, starting with a letter or number.”), or the headers are wrong (“Send X-Mestra-Create or X-Mestra-Updated-At, not both.”, “X-Mestra-Updated-At must be an updatedAt value from this service.” or “X-Mestra-Create must be 1.”).
- 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: “unknown format”
- 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.
- 412: “Someone else changed this. Reload to see their changes.” (`X-Mestra-Updated-At` is not the document's current `updatedAt`, or the document is gone). Nothing is saved.
- 500: “could not save configuration”, “could not read configuration” (re-reading after the change), “could not check token”, or “Couldn't save that change. Try again.” (the change could not be recorded, so it was not made). Nothing is half-saved: try again.
- 501: “configuration is read-only here”: this server can't change configuration.

### Example request

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

## Retrieve or create a format for a size

`POST /api/v1/formats/custom`

Permission: Campaigns · Write.

Answers the organisation's format for a width, height and unit (`px` or `mm`; a blank unit is `px`), making one when it has none. A size the organisation already has, with the same width, height and unit, answers that format's key (the lowest key if several match; a print format, which the server does not make, is never reused). Otherwise a format is made with the key `custom-<w>x<h>-<unit>` (a decimal keeps its dot, for example `custom-99.5x210-mm`), the name `<w> × <h> <unit>` and the usual defaults (review always, export `indd`, `png` and `jpg`, no bleed or safe margin; 150 dpi for a size in `mm`). Each side must be at least 1 and at most 20000, else `400` with `code` `bad_custom_size`, `field` (`w`, `h` or `unit`) and, for a side, `min` and `max`. Needs the same permission as saving a campaign.

### Parameters

- `w` (number, required):
- `h` (number, required):
- `unit` (string, optional):  One of: `px`, `mm`.

### Returns

The format.

An object with:

- `key` (string, required):
- `name` (string, required):
- `width` (number, required):
- `height` (number, required):
- `unit` (string, required):  One of: `px`, `mm`.

### Errors

- 400 (`bad_custom_size`): The size is refused (`bad_custom_size`).
- 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`): `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 save configuration”, “could not read configuration” (re-reading after the change), “could not check token”, or “Couldn't save that change. Try again.” (the change could not be recorded, so it was not made). Nothing is half-saved: try again.
- 501: “configuration is read-only here”: this server can't change configuration.

### Example request

```sh
curl --request POST \
  --url https://app.withmestra.com/api/v1/formats/custom \
  --header "Authorization: Bearer $MESTRA_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"w":300,"h":250,"unit":"px"}'
```
