# Campaigns

A campaign is a brief: the copy, the dates, and the brands and formats to make. It points at a format set and one or more brands. Runs make a campaign's artwork from a master, and reviews follow a campaign's results.

A campaign is a brief: the copy, the dates, and the brands and formats to make. It points at a format set and one or more brands. Runs make a campaign's artwork from a master, and reviews follow a campaign's results.

## The Campaign object

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

- `name` (string, required): The campaign's display name.
- `key` (string, required): The campaign's key: its identifier in URLs and in runs. Letters, digits and dashes, unique in the organisation.
- `externalRef` (object, optional): A link to the same campaign in another system, for your own reference. Mestra does not read from it.
  - `system` (string, optional): The name of the other system (for example `Asana`). Empty when there is none.
  - `id` (string, optional, nullable): The campaign's id in that system, or null.
  - `url` (string, optional, nullable): A link to the campaign in that system, or null.
  - `syncedAt` (string, optional, nullable): When the link was last refreshed from that system, or null.
- `formatSet` (string, optional): The key of the format set this campaign makes: the group of sizes each run builds. Optional: a campaign can list its sizes in `formats` alone.
- `formats` (array of strings, optional, nullable): The campaign's own sizes, as format keys, added to the format set's. Each key once. A campaign with neither a format set nor formats has no sizes until some are added.
- `centres` (array of strings, required, nullable): The codes of the brands this campaign runs in. At least one.
- `copy` (object, optional, nullable): Fixed wording for the campaign, by role (for example `headline` or `cta`). A run uses it exactly as written. Each value is up to 2,000 characters.
- `qrUrl` (string, optional): The address a QR code in the campaign's artwork points to. Empty for none.
- `startDate` (string, optional): Optional, YYYY-MM-DD: prefills a publish to screens.
- `endDate` (string, optional): Optional, YYYY-MM-DD, not before startDate.
- `notes` (string, optional): Free-text notes for this campaign that the layout planner follows, up to 4,000 characters.
- `brandRulesOverride` (object, optional, nullable): Brand rules that replace the brand's own for this campaign; null to use the brand's.
  - `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).
- `centreFormats` (map of objects, optional): Per-centre changes to the format set, by brand code: sizes added and sizes skipped. These win over the brand's own lists.
  - `add` (array of strings, optional):
  - `skip` (array of strings, optional):
- `copyRows` (array of objects, optional, nullable): The campaign's copy sheet: copy for one brand and format, used word for word. For a brand and format, a run takes the campaign's `copy`, then the national row for all formats, the national row for the format, the brand's row for all formats and the brand's row for the format, each later one winning per role. At most 5,000 rows, one per brand and format.
  - `centre` (string, optional): A brand code. Empty for every brand.
  - `format` (string, optional): A format key. Empty for every format.
  - `copy` (object, required): Text by role (`headline`, `subhead`, `body`, `legal`, `cta`), up to 2,000 characters each.

```json
{
  "name": "Spring launch",
  "key": "spring-launch",
  "externalRef": {
    "system": "",
    "id": null,
    "url": null,
    "syncedAt": null
  },
  "formatSet": "social-launch",
  "centres": [
    "ESP",
    "RVW"
  ],
  "copy": {
    "headline": "Fresh for spring",
    "cta": "Shop now"
  },
  "qrUrl": "https://example.com/spring",
  "startDate": "2027-09-01",
  "endDate": "2027-11-30",
  "brandRulesOverride": null
}
```

## Retrieve a campaign

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

Permission: Campaigns · Read.

Returns the campaign together with the formats and sites it uses. The key `no-campaign` is readable without Campaigns · Read by a key that has Runs · Write or Designs · Write and Brand · Read (it lists only brands and sizes; any other campaign key still needs Campaigns · Read). A site code that isn't defined is listed under `missingSites` instead of being dropped. `limits` says how many reviews and review passes the organisation has.

The key `no-campaign` is not a stored campaign: it answers the same shape for a run that belongs to none. `campaign` is `{"key": "no-campaign", "name": "No campaign", "centres": [...]}` with every brand of the organisation, `formats` is every size the organisation has, and `sites` is every brand (with its `uploadedLogos`). There are no `siteSizes` or `extraFormats`: each brand gets each size. A run with no campaign names its brands in `sites` and its sizes in `formats` and `customSizes` (`POST /masters/{id}/runs` with `campaignKey` `no-campaign`; `customSizes` is a list of `{"w", "h", "unit"}` with `unit` `px` or `mm`, each made a format of the organisation if it has none like it, see `POST /formats/custom`).

### Parameters

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

### Returns

The campaign.

An object with:

- `campaign` (object, required): The campaign object. A campaign is identified by its `key`.
  - `name` (string, required): The campaign's display name.
  - `key` (string, required): The campaign's key: its identifier in URLs and in runs. Letters, digits and dashes, unique in the organisation.
  - `externalRef` (object, optional): A link to the same campaign in another system, for your own reference. Mestra does not read from it.
    - `system` (string, optional): The name of the other system (for example `Asana`). Empty when there is none.
    - `id` (string, optional, nullable): The campaign's id in that system, or null.
    - `url` (string, optional, nullable): A link to the campaign in that system, or null.
    - `syncedAt` (string, optional, nullable): When the link was last refreshed from that system, or null.
  - `formatSet` (string, optional): The key of the format set this campaign makes: the group of sizes each run builds. Optional: a campaign can list its sizes in `formats` alone.
  - `formats` (array of strings, optional, nullable): The campaign's own sizes, as format keys, added to the format set's. Each key once. A campaign with neither a format set nor formats has no sizes until some are added.
  - `centres` (array of strings, required, nullable): The codes of the brands this campaign runs in. At least one.
  - `copy` (object, optional, nullable): Fixed wording for the campaign, by role (for example `headline` or `cta`). A run uses it exactly as written. Each value is up to 2,000 characters.
  - `qrUrl` (string, optional): The address a QR code in the campaign's artwork points to. Empty for none.
  - `startDate` (string, optional): Optional, YYYY-MM-DD: prefills a publish to screens.
  - `endDate` (string, optional): Optional, YYYY-MM-DD, not before startDate.
  - `notes` (string, optional): Free-text notes for this campaign that the layout planner follows, up to 4,000 characters.
  - `brandRulesOverride` (object, optional, nullable): Brand rules that replace the brand's own for this campaign; null to use the brand's.
    - `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).
  - `centreFormats` (map of objects, optional): Per-centre changes to the format set, by brand code: sizes added and sizes skipped. These win over the brand's own lists.
    - `add` (array of strings, optional):
    - `skip` (array of strings, optional):
  - `copyRows` (array of objects, optional, nullable): The campaign's copy sheet: copy for one brand and format, used word for word. For a brand and format, a run takes the campaign's `copy`, then the national row for all formats, the national row for the format, the brand's row for all formats and the brand's row for the format, each later one winning per role. At most 5,000 rows, one per brand and format.
    - `centre` (string, optional): A brand code. Empty for every brand.
    - `format` (string, optional): A format key. Empty for every format.
    - `copy` (object, required): Text by role (`headline`, `subhead`, `body`, `legal`, `cta`), up to 2,000 characters each.
- `limits` (object, required): The organisation's review slots (`reviews`) and how many review passes its apps may run (`passes`).
  - `reviews` (integer, required):
  - `passes` (integer, required):
- `formats` (array of objects, required):
  - `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.
- `extraFormats` (array of objects, optional): Full definitions of the formats that appear in a brand's `siteSizes` list but not in `formats`. Present only when there are any.
  - `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.
- `siteSizes` (object, optional): The sizes to build for each brand whose list differs from `formats` (the campaign's format set), by brand code. Brands on the format set are not listed. Present only when at least one differs.
- `sites` (array of objects, required):
  - `name` (string, optional): The site's display name.
  - `code` (string, optional): The brand's code.
  - `logos` (object, optional, nullable): The logo files named in the configuration, by variant. Uploaded logos are in `uploadedLogos`.
  - `brandColours` (array of strings, optional, nullable): The brand's brand colours as hex values. 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.
  - `uploadedLogos` (array of objects, required): The uploaded variants (primary, then reversed); `[]` when none or logos aren't set up.
    - `variant` (string, required): `primary` or `reversed`: the slot the logo is uploaded to. One of: `primary`, `reversed`.
    - `contentType` (string, required): `image/png` or `image/svg+xml`. One of: `image/png`, `image/svg+xml`.
    - `sha256` (string, required): The file's SHA-256, in lower-case hex.
    - `luminance` (number, optional, nullable): The logo's mean relative luminance (WCAG; 0 black, 1 white), measured when it was uploaded; null when it can't be measured. An app picks the upload that contrasts more with the artwork by this, not by the slot name ("reversed" is only a name).
    - `trim` (object, optional, nullable): The box of the logo's visible artwork (alpha at least 8/255) as shares of its canvas, measured when it was uploaded; null for an SVG or when it can't be measured. An app fits this box, not the canvas, into the logo frame, so a transparent margin doesn't shrink the logo.
      - `x` (number, required): Left edge of the visible artwork, as a share (0 to 1) of the logo's width.
      - `y` (number, required): Top edge of the visible artwork, as a share (0 to 1) of the logo's height.
      - `w` (number, required): Width of the visible artwork, as a share (0 to 1) of the logo's width.
      - `h` (number, required): Height of the visible artwork, as a share (0 to 1) of the logo's height.
- `missingSites` (array of strings, optional): Present only when a brand code does not resolve.

### Errors

- 400: The campaign names a format set or format the organisation doesn't have; the message says which.
- 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 campaign”
- 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”, “could not resolve the campaign's formats”, “could not read logos” or “could not check token”.

### Example request

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

## Create or update a campaign

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

Permission: Campaigns · Write.

Creates the campaign 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. Copy values are up to 2,000 characters. 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 campaign's display name.
- `key` (string, required): The campaign's key: its identifier in URLs and in runs. Letters, digits and dashes, unique in the organisation.
- `externalRef` (object, optional): A link to the same campaign in another system, for your own reference. Mestra does not read from it.
  - `system` (string, optional): The name of the other system (for example `Asana`). Empty when there is none.
  - `id` (string, optional, nullable): The campaign's id in that system, or null.
  - `url` (string, optional, nullable): A link to the campaign in that system, or null.
  - `syncedAt` (string, optional, nullable): When the link was last refreshed from that system, or null.
- `formatSet` (string, optional): The key of the format set this campaign makes: the group of sizes each run builds. Optional: a campaign can list its sizes in `formats` alone.
- `formats` (array of strings, optional, nullable): The campaign's own sizes, as format keys, added to the format set's. Each key once. A campaign with neither a format set nor formats has no sizes until some are added.
- `centres` (array of strings, required, nullable): The codes of the brands this campaign runs in. At least one.
- `copy` (object, optional, nullable): Fixed wording for the campaign, by role (for example `headline` or `cta`). A run uses it exactly as written. Each value is up to 2,000 characters.
- `qrUrl` (string, optional): The address a QR code in the campaign's artwork points to. Empty for none.
- `startDate` (string, optional): Optional, YYYY-MM-DD: prefills a publish to screens.
- `endDate` (string, optional): Optional, YYYY-MM-DD, not before startDate.
- `notes` (string, optional): Free-text notes for this campaign that the layout planner follows, up to 4,000 characters.
- `brandRulesOverride` (object, optional, nullable): Brand rules that replace the brand's own for this campaign; null to use the brand's.
  - `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).
- `centreFormats` (map of objects, optional): Per-centre changes to the format set, by brand code: sizes added and sizes skipped. These win over the brand's own lists.
  - `add` (array of strings, optional):
  - `skip` (array of strings, optional):
- `copyRows` (array of objects, optional, nullable): The campaign's copy sheet: copy for one brand and format, used word for word. For a brand and format, a run takes the campaign's `copy`, then the national row for all formats, the national row for the format, the brand's row for all formats and the brand's row for the format, each later one winning per role. At most 5,000 rows, one per brand and format.
  - `centre` (string, optional): A brand code. Empty for every brand.
  - `format` (string, optional): A format key. Empty for every format.
  - `copy` (object, required): Text by role (`headline`, `subhead`, `body`, `legal`, `cta`), up to 2,000 characters each.

### 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/campaigns/string \
  --header "Authorization: Bearer $MESTRA_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"name":"Spring launch","key":"spring-launch","externalRef":{"system":"","id":null,"url":null,"syncedAt":null},"formatSet":"social-launch","centres":["ESP","RVW"],"copy":{"headline":"Fresh for spring","cta":"Shop now"},"qrUrl":"https://example.com/spring","startDate":"2027-09-01","endDate":"2027-11-30","brandRulesOverride":null}'
```

## List all campaigns

`GET /api/v1/campaigns`

Permission: Campaigns · Read.

Returns every campaign the organisation has, sorted by key. Send `limit` or `offset` to page through them: the answer is then that page, and the `X-Total-Count` header says how many there are in all.

### Parameters

- `limit` (integer, optional): 1 to 200; every campaign when neither limit nor offset is sent.
- `offset` (integer, optional):

### Returns

Every campaign, or the page asked for.

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

## Delete a campaign

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

Permission: Campaigns · Write.

Deletes the campaign. Runs and reviews already made from it are not affected.

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

## Retrieve the dynamic content table

`GET /api/v1/campaigns/{key}/dynamic`

Permission: Campaigns · Read.

Returns the campaign's dynamic content table (its columns and rows), the approved rules the rows draw on, and the signals a column can read. `version` is null until a table is saved. `rules.approved` is false until the campaign's rules are approved. Each row's `needsApproval` lists the fields (`copy.<role>`, `colourway`, `master`) that use a value the approved rules don't list; such a row is saved but never rendered as ready, chosen or published. `rules.mastersAvailable` lists the organisation's current ready master versions. `rulesChanged` is true when the saved table no longer passes the shape checks.

### Parameters

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

### Returns

The table.

An object with:

- `version` (object, required, nullable): The saved version, or null before the first save.
  - `number` (integer, optional):
  - `hash` (string, optional):
  - `source` (string, optional):
  - `createdAt` (string (date-time), optional):
- `columns` (array of objects, required):
- `rows` (array of objects, required):
- `rulesChanged` (boolean, required):
- `signals` (array of strings, required): The signals a column can read.
- `errors` (array of objects, required):
  - `row` (string, optional):
  - `field` (string, optional):
  - `msg` (string, optional):
- `started` (integer, optional): Renders started by a save.
- `renderError` (string, optional): A save's renders could not be started; the table is saved.
- `switching` (string, optional): Whether the published artwork switches between variants by itself: `on`, `stopped` once an editor stopped it, empty before the first publish. One of: \`\`, `on`, `stopped`.

### 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: “unknown campaign”
- 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 dynamic content.”
- 501: “Dynamic content isn't set up on this server.”

### Example request

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

## Create or update the dynamic content table

`PUT /api/v1/campaigns/{key}/dynamic`

Permission: Campaigns · Write.

Saves the table as a new version and starts the renders it needs. The body is JSON with `columns` and `rows`; every row is checked against the campaign's approved rules, and a table with problems is refused (`422`) with the list. The same table as the latest version saves nothing new. The rules must be approved first (`409` `rules_not_approved`). The answer is the same as the read, plus `started` (renders started) or `renderError` when the table was saved but its renders could not start.

### Parameters

- `key` (string, required): The document's key (a brand's code).
- `columns` (array of objects, required):
  - `name` (string, required): Lower case letters, digits and underscores, up to 40.
  - `type` (string, required):
  - `signal` (string, required): The signal the column reads, such as `time` or `city`.
- `rows` (array of objects, required):
  - `id` (string, required):
  - `label` (string, required):
  - `active` (boolean, required):
  - `default` (boolean, required): The row used when no other applies.
  - `copy` (object, optional): Text for each role; blank keeps the rules' default choice.
  - `colourway` (string, required):
  - `master` (string, required): A master version id from the approved rules.
  - `when` (object, optional): The condition for each column.

### Returns

The saved table.

An object with:

- `version` (object, required, nullable): The saved version, or null before the first save.
  - `number` (integer, optional):
  - `hash` (string, optional):
  - `source` (string, optional):
  - `createdAt` (string (date-time), optional):
- `columns` (array of objects, required):
- `rows` (array of objects, required):
- `rulesChanged` (boolean, required):
- `signals` (array of strings, required): The signals a column can read.
- `errors` (array of objects, required):
  - `row` (string, optional):
  - `field` (string, optional):
  - `msg` (string, optional):
- `started` (integer, optional): Renders started by a save.
- `renderError` (string, optional): A save's renders could not be started; the table is saved.
- `switching` (string, optional): Whether the published artwork switches between variants by itself: `on`, `stopped` once an editor stopped it, empty before the first publish. One of: \`\`, `on`, `stopped`.

### Errors

- 400: The body could not be read.
- 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 campaign”
- 409 (`api_off`): Code `api_off` when an owner hasn't turned the API on.
- 413: The body is over 2 MB.
- 422: “The table has problems.” with `errors`, up to 100 “{row, field, msg}”.
- 500: “Could not save the dynamic content.”
- 501: “Dynamic content isn't set up on this server.”

### Example request

```sh
curl --request PUT \
  --url https://app.withmestra.com/api/v1/campaigns/string/dynamic \
  --header "Authorization: Bearer $MESTRA_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"columns":[{"name":"city","type":"text","signal":"city"}],"rows":[{"id":"perth-morning","label":"Perth mornings","active":true,"default":false,"copy":{"headline":"Good morning, Perth"},"colourway":"Sunrise","master":"9f2c4e6a-8b0d-4f3a-9c7e-1b3d5f7a9c1e","when":{"city":"Perth"}},{"id":"everyone","label":"Everyone else","active":true,"default":true,"copy":{},"colourway":"Sunrise","master":"9f2c4e6a-8b0d-4f3a-9c7e-1b3d5f7a9c1e","when":{}}]}'
```

## Retrieve the row a screen would get

`POST /api/v1/campaigns/{key}/dynamic/decide`

Permission: Campaigns · Write.

Picks the row the saved table would show for a screen (`screenId`, from your last screen read) and any signal values you give (`signals`, which win over the screen's own). Nothing is changed. The answer has the chosen `rowId` (empty when none), whether it is the `default` row, the `reasons` for the choice, the `signals` used and `files`, the ready file of the chosen row by format. `409` `no_table` until a table is saved.

### Parameters

- `key` (string, required): The document's key (a brand's code).
- `screenId` (string, optional): A screen from the last screen read.
- `timezone` (string, optional): An IANA zone such as `Australia/Perth`. With no `screenId`, the `time`, `day` and `date` signals follow this zone; blank means UTC. An unknown zone is refused with 400.
- `signals` (object, optional): Signal values to test with, such as `time` or `city`.

### Returns

The choice.

An object with:

- `rowId` (string, required):
- `default` (boolean, required):
- `reasons` (array of strings, required):
- `signals` (object, required):
- `files` (object, required): The chosen row's ready file for each format.

### Errors

- 400: The body could not be read.
- 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 campaign”, or “That screen isn't in your last screen read.”
- 409 (`rules_not_approved`, `no_table`, `api_off`): `rules_not_approved` (“Approve the rules first”), `no_table` (“Save the table first”), or code `api_off`.
- 500: “Could not read the dynamic content.”
- 501: “Dynamic content isn't set up on this server.”

### Example request

```sh
curl --request POST \
  --url https://app.withmestra.com/api/v1/campaigns/string/dynamic/decide \
  --header "Authorization: Bearer $MESTRA_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"screenId":"scr_123","signals":{"city":"Perth"}}'
```
