# Format sets

A format set is a named group of formats, such as "Social launch". A campaign names one format set, and each of its formats is built once for each brand.

A format set is a named group of formats, such as "Social launch". A campaign names one format set, and each of its formats is built once for each brand.

## The Format set object

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

- `name` (string, required): The format set's display name.
- `key` (string, required): The format set's key. Unique in the organisation.
- `formats` (array of strings, optional, nullable): The keys of the formats in this set, in the order they are made.

```json
{
  "name": "Social launch",
  "key": "social-launch",
  "formats": [
    "social-feed",
    "social-story"
  ]
}
```

## Retrieve a format set

`GET /api/v1/format-sets/{key}`

Permission: Brand · Read.

Returns the format set 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-set”
- 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/format-sets/string \
  --header "Authorization: Bearer $MESTRA_TOKEN"
```

## Create or update a format set

`PUT /api/v1/format-sets/{key}`

Permission: Brand · Write.

Creates the format set with this key, or replaces it if it already exists. The body is strict JSON, and its `key` must equal the one in the path. Every format it lists must exist, or the request is refused with `400` and `field`. 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 set's display name.
- `key` (string, required): The format set's key. Unique in the organisation.
- `formats` (array of strings, optional, nullable): The keys of the formats in this set, in the order they are made.

### 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/format-sets/string \
  --header "Authorization: Bearer $MESTRA_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"name":"Social launch","key":"social-launch","formats":["social-feed","social-story"]}'
```

## List all format sets

`GET /api/v1/format-sets`

Permission: Brand · Read.

Returns every format set (a named group of formats) the organisation has, sorted by key.

### Returns

Every format set.

### 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/format-sets \
  --header "Authorization: Bearer $MESTRA_TOKEN"
```

## Delete a format set

`DELETE /api/v1/format-sets/{key}`

Permission: Brand · Write.

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

### 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-set”
- 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/format-sets/string \
  --header "Authorization: Bearer $MESTRA_TOKEN"
```
