# Brands

A site is a brand or site that campaigns run in: its colours, QR address and layout rules. Its logos are uploaded separately (see Logos). Every run is for one brand.

A site is a brand or site that campaigns run in: its colours, QR address and layout rules. Its logos are uploaded separately (see Logos). Every run is for one brand.

## The Brand object

The brand object. A brand is identified by its `code`.

- `name` (string, required): The site's display name.
- `code` (string, required): The brand's code: its identifier in campaigns and runs. Unique in the organisation.
- `styles` (object, optional): A brand's saved styles: its text styles, its looks and its named colours. Every list may be empty. A save replaces the whole document, so a save that leaves a list out clears it.
  - `text` (array of objects, optional):
    - `name` (string, required): 1 to 60 characters; unique among the text styles, ignoring case.
    - `role` (string, optional): The role it is meant for (headline, subhead, body, cta, legal...); empty for none.
    - `font` (object, required):
      - `family` (string, required):
      - `style` (string, required):
      - `axes` (object, optional):
      - `opticalSize` (string, optional):  One of: `auto`.
    - `size` (number, required): Points, above 0.
    - `leading` (number, required): Points; 0 is automatic.
    - `tracking` (number, required): Thousandths of an em.
    - `align` (string, required):  One of: `left`, `center`, `right`, `justify`.
    - `caps` (string, required):  One of: `normal`, `allCaps`, `smallCaps`, `capToSmallCaps`.
    - `color` (string, optional): A #RRGGBB colour; empty to leave the colour as it is.
  - `looks` (array of objects, optional):
    - `name` (string, required): 1 to 60 characters; unique among the looks, ignoring case.
    - `look` (object, required): The composition's own look (`blend`, `effects`, `fills`, `stroke`, `levels` and the rest): at least one setting, every effect editable, no `picture`, `notes` or `reach`.
  - `colours` (array of objects, optional):
    - `name` (string, required): 1 to 60 characters; unique among the colours, ignoring case.
    - `hex` (string, required): A #RRGGBB colour of the brand's palette (its brand colours, white or black); stored upper case.
- `logos` (object, optional, nullable): InDesign file paths by variant. Each must be a file on the user's computer (`C:\...`, `/...` or a relative path); a network or web address (`//host`, `\\host`, `file:`, `smb:`, `http:` or any other scheme) is refused with `400`, as InDesign would otherwise connect to that host.
- `brandColours` (array of strings, optional, nullable): The brand's brand colours as hex values (for example `#1B3A5C`). Null for none.
- `colourInks` (object, optional): CMYK inks for brand colours, keyed by the lower-case hex value (for example `#1b3a5c`); four numbers from 0 to 1 (C, M, Y, K). Each key must be one of `brandColours`. Omitted when none are set.
- `colourNames` (object, optional): Optional names for brand colours, keyed by the lower-case hex value (for example `#1b3a5c`): `{"#1b3a5c": "Navy"}`. Each key must be one of `brandColours`; a colour with no entry is unnamed. A name is at most 40 characters with no quotes or angle brackets (refused with `400` and field `colourNames`). `brandColours` stays a list of hex strings, so clients that send only hex values keep working. Omitted when none are set.
- `qrBaseUrl` (string, optional): The address QR codes for this brand start from. Empty for none.
- `brandRules` (object, optional):
  - `logo` (object, optional, nullable): Rules for the logo; null for none.
    - `minWidthPct` (number, optional): The smallest logo width, as a share of the page width (0.12 is 12%).
    - `clearSpacePct` (number, optional): The clear space kept around the logo, as a share (for example 0.5).
  - `typography` (object, optional, nullable): Rules for type; null for none.
    - `allowedFamilies` (array of strings, optional, nullable): The font families layouts may use. Null for any.
    - `headlineMaxLines` (integer, optional): The most lines a headline may take.
  - `alignment` (object, optional, nullable): Rules for alignment; null for none.
    - `grid` (number, optional): The grid that positions snap to.
  - `spacing` (object, optional, nullable): Rules for spacing; null for none.
    - `minGapPct` (number, optional): The smallest gap between elements, as a share of the page height (0.02 is 2%).
  - `notes` (string, optional): Free-text brand notes the layout planner follows, up to 4,000 characters. Set on a brand; a campaign's override must leave it empty (put campaign notes on the campaign).
- `formatsAdd` (array of strings, optional): Format keys added to every campaign's format set for this brand.
- `formatsSkip` (array of strings, optional): Format keys left out of every campaign's format set for this brand.

```json
{
  "name": "Eastside Plaza",
  "code": "ESP",
  "logos": {},
  "brandColours": [
    "#1B3A5C",
    "#F2A900"
  ],
  "qrBaseUrl": "https://example.com/eastside",
  "brandRules": {
    "logo": {
      "minWidthPct": 0.12,
      "clearSpacePct": 0.5
    },
    "typography": {
      "allowedFamilies": [
        "Jost",
        "Source Serif 4"
      ],
      "headlineMaxLines": 2
    },
    "alignment": {
      "grid": 4
    },
    "spacing": {
      "minGapPct": 0.02
    }
  }
}
```

## Retrieve a brand

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

Permission: Brand · Read.

Returns the site with this code, exactly as it was saved. Uploaded logos are listed under Logos.

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

## Create or update a brand

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

Permission: Brand · Write.

Creates the brand with this code, or replaces it if it already exists. The body is strict JSON, and its `code` must equal the one in the path. Creating a brand beyond the plan's brand allowance is refused. 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 site's display name.
- `code` (string, required): The brand's code: its identifier in campaigns and runs. Unique in the organisation.
- `styles` (object, optional): A brand's saved styles: its text styles, its looks and its named colours. Every list may be empty. A save replaces the whole document, so a save that leaves a list out clears it.
  - `text` (array of objects, optional):
    - `name` (string, required): 1 to 60 characters; unique among the text styles, ignoring case.
    - `role` (string, optional): The role it is meant for (headline, subhead, body, cta, legal...); empty for none.
    - `font` (object, required):
      - `family` (string, required):
      - `style` (string, required):
      - `axes` (object, optional):
      - `opticalSize` (string, optional):  One of: `auto`.
    - `size` (number, required): Points, above 0.
    - `leading` (number, required): Points; 0 is automatic.
    - `tracking` (number, required): Thousandths of an em.
    - `align` (string, required):  One of: `left`, `center`, `right`, `justify`.
    - `caps` (string, required):  One of: `normal`, `allCaps`, `smallCaps`, `capToSmallCaps`.
    - `color` (string, optional): A #RRGGBB colour; empty to leave the colour as it is.
  - `looks` (array of objects, optional):
    - `name` (string, required): 1 to 60 characters; unique among the looks, ignoring case.
    - `look` (object, required): The composition's own look (`blend`, `effects`, `fills`, `stroke`, `levels` and the rest): at least one setting, every effect editable, no `picture`, `notes` or `reach`.
  - `colours` (array of objects, optional):
    - `name` (string, required): 1 to 60 characters; unique among the colours, ignoring case.
    - `hex` (string, required): A #RRGGBB colour of the brand's palette (its brand colours, white or black); stored upper case.
- `logos` (object, optional, nullable): InDesign file paths by variant. Each must be a file on the user's computer (`C:\...`, `/...` or a relative path); a network or web address (`//host`, `\\host`, `file:`, `smb:`, `http:` or any other scheme) is refused with `400`, as InDesign would otherwise connect to that host.
- `brandColours` (array of strings, optional, nullable): The brand's brand colours as hex values (for example `#1B3A5C`). Null for none.
- `colourInks` (object, optional): CMYK inks for brand colours, keyed by the lower-case hex value (for example `#1b3a5c`); four numbers from 0 to 1 (C, M, Y, K). Each key must be one of `brandColours`. Omitted when none are set.
- `colourNames` (object, optional): Optional names for brand colours, keyed by the lower-case hex value (for example `#1b3a5c`): `{"#1b3a5c": "Navy"}`. Each key must be one of `brandColours`; a colour with no entry is unnamed. A name is at most 40 characters with no quotes or angle brackets (refused with `400` and field `colourNames`). `brandColours` stays a list of hex strings, so clients that send only hex values keep working. Omitted when none are set.
- `qrBaseUrl` (string, optional): The address QR codes for this brand start from. Empty for none.
- `brandRules` (object, optional):
  - `logo` (object, optional, nullable): Rules for the logo; null for none.
    - `minWidthPct` (number, optional): The smallest logo width, as a share of the page width (0.12 is 12%).
    - `clearSpacePct` (number, optional): The clear space kept around the logo, as a share (for example 0.5).
  - `typography` (object, optional, nullable): Rules for type; null for none.
    - `allowedFamilies` (array of strings, optional, nullable): The font families layouts may use. Null for any.
    - `headlineMaxLines` (integer, optional): The most lines a headline may take.
  - `alignment` (object, optional, nullable): Rules for alignment; null for none.
    - `grid` (number, optional): The grid that positions snap to.
  - `spacing` (object, optional, nullable): Rules for spacing; null for none.
    - `minGapPct` (number, optional): The smallest gap between elements, as a share of the page height (0.02 is 2%).
  - `notes` (string, optional): Free-text brand notes the layout planner follows, up to 4,000 characters. Set on a brand; a campaign's override must leave it empty (put campaign notes on the campaign).
- `formatsAdd` (array of strings, optional): Format keys added to every campaign's format set for this brand.
- `formatsSkip` (array of strings, optional): Format keys left out of every campaign's format set for this brand.

### 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/sites/string \
  --header "Authorization: Bearer $MESTRA_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"name":"Eastside Plaza","code":"ESP","logos":{},"brandColours":["#1B3A5C","#F2A900"],"qrBaseUrl":"https://example.com/eastside","brandRules":{"logo":{"minWidthPct":0.12,"clearSpacePct":0.5},"typography":{"allowedFamilies":["Jost","Source Serif 4"],"headlineMaxLines":2},"alignment":{"grid":4},"spacing":{"minGapPct":0.02}}}'
```

## List all brands

`GET /api/v1/sites`

Permission: Brand · Read.

Returns every site (a brand or site that campaigns run in) the organisation has, sorted by code.

### Returns

Every brand.

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

## Delete a brand

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

Permission: Brand · Write.

Deletes the brand. Its uploaded logos are deleted with 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 brand”
- 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/sites/string \
  --header "Authorization: Bearer $MESTRA_TOKEN"
```

## Retrieve a brand's styles

`GET /api/v1/sites/{key}/styles`

Permission: Designs · Read.

Returns the site's saved text styles, looks and colours (`saved`), the site's palette (`palette`, read-only: its brand colours, then white and black, each `#RRGGBB` upper case, which is what the editor's paint operations accept), and the ones its masters already use (`fromMasters`), found when you ask and kept nowhere: each distinct look of an element in the latest version of the site's masters, named by its layer and master (looks drawn from a saved picture or holding an effect the editor cannot edit are left out), and each distinct paragraph style by role. Needs the Designs read permission. The answer carries `X-Mestra-Updated-At`, the site's own, to send back with a save.

### Parameters

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

### Returns

The styles.

An object with:

- `saved` (object, required):
  - `text` (array of objects, required):
    - `name` (string, required): 1 to 60 characters; unique among the text styles, ignoring case.
    - `role` (string, optional): The role it is meant for (headline, subhead, body, cta, legal...); empty for none.
    - `font` (object, required):
      - `family` (string, required):
      - `style` (string, required):
      - `axes` (object, optional):
      - `opticalSize` (string, optional):  One of: `auto`.
    - `size` (number, required): Points, above 0.
    - `leading` (number, required): Points; 0 is automatic.
    - `tracking` (number, required): Thousandths of an em.
    - `align` (string, required):  One of: `left`, `center`, `right`, `justify`.
    - `caps` (string, required):  One of: `normal`, `allCaps`, `smallCaps`, `capToSmallCaps`.
    - `color` (string, optional): A #RRGGBB colour; empty to leave the colour as it is.
  - `looks` (array of objects, required):
    - `name` (string, required): 1 to 60 characters; unique among the looks, ignoring case.
    - `look` (object, required): The composition's own look (`blend`, `effects`, `fills`, `stroke`, `levels` and the rest): at least one setting, every effect editable, no `picture`, `notes` or `reach`.
  - `colours` (array of objects, required):
    - `name` (string, required): 1 to 60 characters; unique among the colours, ignoring case.
    - `hex` (string, required): A #RRGGBB colour of the brand's palette (its brand colours, white or black); stored upper case.
- `palette` (array of strings, required): The brand's palette, read-only: its brand colours, then white and black. Not part of what a save sends.
- `fromMasters` (object, required):
  - `text` (array of objects, required): A text style found in a master: a `TextStyle` (its `name` made from its role, face and size) and the master it was first seen in.
    - `name` (string, required): 1 to 60 characters; unique among the text styles, ignoring case.
    - `role` (string, optional): The role it is meant for (headline, subhead, body, cta, legal...); empty for none.
    - `font` (object, required):
      - `family` (string, required):
      - `style` (string, required):
      - `axes` (object, optional):
      - `opticalSize` (string, optional):  One of: `auto`.
    - `size` (number, required): Points, above 0.
    - `leading` (number, required): Points; 0 is automatic.
    - `tracking` (number, required): Thousandths of an em.
    - `align` (string, required):  One of: `left`, `center`, `right`, `justify`.
    - `caps` (string, required):  One of: `normal`, `allCaps`, `smallCaps`, `capToSmallCaps`.
    - `color` (string, optional): A #RRGGBB colour; empty to leave the colour as it is.
    - `master` (string, required):
  - `looks` (array of objects, required):
    - `name` (string, required): The layer's name, or the kind of element and its master when it has none.
    - `master` (string, required): The master it was first seen in.
    - `layer` (string, required): The layer's name; empty when it has none.
    - `look` (object, required): The composition's own look.

### 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 brand”: no such site in the organisation (or a Network customer asked).
- 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/sites/string/styles \
  --header "Authorization: Bearer $MESTRA_TOKEN"
```

## Update a brand's styles

`PUT /api/v1/sites/{key}/styles`

Permission: Designs · Write.

Replaces the brand's saved styles whole with the body and answers the saved styles. Any editor may save a style: this needs the Designs write permission, not the brand settings'. Names are 1 to 60 characters and unique in their list, ignoring case; a saved colour (`colours`: `{name, hex}`) is a `#RRGGBB` (kept upper case) that the brand's palette holds, `400` with `field` `colours[i].hex` otherwise; a look holds only effects the editor can edit and none of the server's own `picture`, `notes` and `reach`; a text style's family must be one the brand allows when it restricts families. A refusal is `400` with `field` naming the place (`looks[2].look.effects[0]`, `text[1].name`). Send the `X-Mestra-Updated-At` of the read to get `412` when the brand changed since.

### Parameters

- `key` (string, required): The document's key (a brand's code).
- `X-Mestra-Updated-At` (string (date-time), optional): The brand's `updatedAt` the person read; `412` when it has changed. Without it the save is checked against the document just read.
- `text` (array of objects, optional):
  - `name` (string, required): 1 to 60 characters; unique among the text styles, ignoring case.
  - `role` (string, optional): The role it is meant for (headline, subhead, body, cta, legal...); empty for none.
  - `font` (object, required):
    - `family` (string, required):
    - `style` (string, required):
    - `axes` (object, optional):
    - `opticalSize` (string, optional):  One of: `auto`.
  - `size` (number, required): Points, above 0.
  - `leading` (number, required): Points; 0 is automatic.
  - `tracking` (number, required): Thousandths of an em.
  - `align` (string, required):  One of: `left`, `center`, `right`, `justify`.
  - `caps` (string, required):  One of: `normal`, `allCaps`, `smallCaps`, `capToSmallCaps`.
  - `color` (string, optional): A #RRGGBB colour; empty to leave the colour as it is.
- `looks` (array of objects, optional):
  - `name` (string, required): 1 to 60 characters; unique among the looks, ignoring case.
  - `look` (object, required): The composition's own look (`blend`, `effects`, `fills`, `stroke`, `levels` and the rest): at least one setting, every effect editable, no `picture`, `notes` or `reach`.
- `colours` (array of objects, optional):
  - `name` (string, required): 1 to 60 characters; unique among the colours, ignoring case.
  - `hex` (string, required): A #RRGGBB colour of the brand's palette (its brand colours, white or black); stored upper case.

### Returns

The saved styles.

An object with:

- `text` (array of objects, required):
  - `name` (string, required): 1 to 60 characters; unique among the text styles, ignoring case.
  - `role` (string, optional): The role it is meant for (headline, subhead, body, cta, legal...); empty for none.
  - `font` (object, required):
    - `family` (string, required):
    - `style` (string, required):
    - `axes` (object, optional):
    - `opticalSize` (string, optional):  One of: `auto`.
  - `size` (number, required): Points, above 0.
  - `leading` (number, required): Points; 0 is automatic.
  - `tracking` (number, required): Thousandths of an em.
  - `align` (string, required):  One of: `left`, `center`, `right`, `justify`.
  - `caps` (string, required):  One of: `normal`, `allCaps`, `smallCaps`, `capToSmallCaps`.
  - `color` (string, optional): A #RRGGBB colour; empty to leave the colour as it is.
- `looks` (array of objects, required):
  - `name` (string, required): 1 to 60 characters; unique among the looks, ignoring case.
  - `look` (object, required): The composition's own look (`blend`, `effects`, `fills`, `stroke`, `levels` and the rest): at least one setting, every effect editable, no `picture`, `notes` or `reach`.
- `colours` (array of objects, required):
  - `name` (string, required): 1 to 60 characters; unique among the colours, ignoring case.
  - `hex` (string, required): A #RRGGBB colour of the brand's palette (its brand colours, white or black); stored upper case.

### Errors

- 400: A refusal with `field` (`text[1].name`, `looks[2].look.effects[0]`, `text[0].font.family`, `colours[0].hex`) and the reason, or `bad JSON: <error>`.
- 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 brand”.
- 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.
- 413: “body exceeds limit (65536 bytes)”
- 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 PUT \
  --url https://app.withmestra.com/api/v1/sites/string/styles \
  --header "Authorization: Bearer $MESTRA_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"text":[{"name":"Headline","role":"headline","font":{"family":"Jost","style":"Bold"},"size":48,"leading":52,"tracking":0,"align":"left","caps":"normal","color":"#1B3A5C"}],"looks":[{"name":"Soft shadow","look":{"effects":[{"type":"dropShadow","x":0,"y":4,"blur":12,"spread":0,"color":"#0A0A0A","opacity":0.25,"blend":"normal"}]}}],"colours":[{"name":"Brand blue","hex":"#1B3A5C"}]}'
```
