# Server runs

A server run builds a campaign's sizes from a saved master on Mestra's servers, with no design app open. This is how you start a run from the API: save a master once, then start server runs from it. Runs started in InDesign, Figma or Canva are listed under App runs.

A server run builds a campaign's sizes from a saved master on Mestra's servers, with no design app open. This is how you start a run from the API: save a master once, then start server runs from it. Runs started in InDesign, Figma or Canva are listed under App runs.

## The Server run object

The server run object. It has one entry per brand and, in each, one per size.

- `runId` (string (uuid), required): The run's id.
- `status` (string, required): `queued`, `running`, `done`, `failed` or `cancelled`. One of: `queued`, `running`, `done`, `failed`, `cancelled`.
- `masterId` (string, required): The saved master; empty when it was deleted while the run existed.
- `campaignKey` (string, required): The campaign the run makes sizes for; `no-campaign` for a run that belongs to none.
- `campaignName` (string, optional): Only on a run with no campaign: `No campaign`, the name to show for `no-campaign`.
- `reason` (string, optional): Only on a failed run: why, in a fixed line (the master's own reason when it changed, `The master was deleted.`, or `The run couldn't be completed. Run it again.`). The sizes that were still open read the same line.
- `sites` (array of objects, required): One entry per brand, in the order asked for.
  - `site` (string, required): The brand.
  - `jobId` (string, required): The id of the brand's run (16 hex characters).
  - `sizes` (array of objects, required): One entry per format, in the order asked for.
    - `format` (string, required): The format key.
    - `status` (string, required): `queued`, `building`, `reviewing`, `done`, `failed` or `skipped`. One of: `queued`, `building`, `reviewing`, `done`, `failed`, `skipped`.
    - `reason` (string, optional): Why a size is skipped or failed (`Needs a design app`, `Add font: <family>`, `Cancelled`, ...). A size left out for one brand is skipped with `not-for-site` (the brand's size list doesn't have it) or `unknown-format` (no such size is defined).
    - `links` (object, optional): Only on a size that is done.
      - `job` (string, required): The brand's run, `/jobs/{jobId}`.
      - `files` (string, required): The brand's kept files as a zip, `/library/runs/{jobId}.zip`.

```json
{
  "runId": "9b2e7a04-61c5-4f1d-8e3a-2c4d6f8a1b22",
  "status": "running",
  "masterId": "3f6c1b52-8d3e-4c7a-9a41-5b0e2f7d8c11",
  "campaignKey": "spring-launch",
  "sites": [
    {
      "site": "ESP",
      "jobId": "7d3a9c51e08b42f6",
      "sizes": [
        {
          "format": "social-feed",
          "status": "done",
          "links": {
            "job": "/jobs/7d3a9c51e08b42f6",
            "files": "/library/runs/7d3a9c51e08b42f6.zip"
          }
        },
        {
          "format": "social-story",
          "status": "building"
        }
      ]
    }
  ]
}
```

## Start a server run

`POST /api/v1/masters/{id}/runs`

Permission: Runs · Write.

Builds a campaign's sizes from a saved master on Mestra's servers, one run per brand. Only a `ready` master can run; one that is `checking` or `not_ready` is refused with `409 not_ready` and its `reasons`. A site that is not marked as a Studio brand (one Mestra Network staff added) is refused with `409 not_studio_brand`: `Mark this site as a Studio brand to use it in Studio.`

Print sizes and sizes of a brand whose fonts are missing are not built: they come back in `skipped` with a reason (`Needs a design app`, `Add font: <family>`). Each size that will be built counts as a size made.

`idempotencyKey` (a UUID) is required unless `dryRun` is true. Sending the same key with the same request returns the run it made (`200`, no second run, no second charge); the same key with a different request is `409 idempotency_conflict`. Keys are per organisation. `dryRun: true` creates and charges nothing: it answers `200` with `sizes` (the sizes it would make), `credits`, `formats` (per format: its `sizes` and, when none, why), `skipped` and `reasons`.

### Parameters

- `id` (string (uuid), required): The saved master to run.
- `campaignKey` (string, required): The campaign to make sizes for, or `no-campaign` for a run that belongs to none (then `sites` is required and every chosen brand gets every chosen size).
- `sites` (array of strings, optional): Site codes in the campaign. Defaults to all of the campaign's brands. Required with `campaignKey` `no-campaign`: the organisation's own brands (`400` `unknown_site`, field `sites[i]`; none named is `400` on `sites`).
- `formats` (array of strings, optional): Format keys in the campaign's sizes (its format set and its own `formats`). Defaults to all of them. With `campaignKey` `no-campaign` the organisation's own format keys (`400` `unknown_format`, field `formats[i]`).
- `customSizes` (array of objects, optional): Only with `campaignKey` `no-campaign`: typed sizes, `[{"w": 300, "h": 250, "unit": "px"}]` (`px` or `mm`, each side 1 to 20000). Each is made a format of the organisation if it has none like it (as `POST /formats/custom` does) and joins `formats`. `400` `bad_custom_size` (field `customSizes[i]`) for a size that isn't valid, and `400` on `customSizes` with a real campaign. A no-campaign run needs at least one size from `formats` and `customSizes` together (`400` `no_sizes`, `Choose at least one size.`).
  - `w` (number, required):
  - `h` (number, required):
  - `unit` (string, optional):  One of: `px`, `mm`.
- `idempotencyKey` (string (uuid), optional): Required unless `dryRun` is true.
- `dryRun` (boolean, optional): Answer what a run would make and cost; create nothing.
- `choice` (object, optional): Picks the copy and colourway from the campaign's approved rules: `copy` (role to one of the listed values) and `colourway` (a listed name). Omit it to take the default. A different `choice` under a repeated `idempotencyKey` is `409 idempotency_conflict`. `400` (field `choice`) when the campaign has no approved rules or a value is not listed.

### Returns

A dry run's estimate, or a repeat of a run already made under the key.

An object with:

- `runId` (string (uuid), optional): The run's id. Absent on a dry run.
- `jobs` (array of objects, required): One entry per brand the run makes sizes for, each with the id of that brand's run. Empty on a dry run.
  - `jobId` (string, required): The id of the brand's run (16 hex characters).
  - `site` (string, required): The brand the run is for.
- `skipped` (array of objects, required): Sizes that will not be made, each with a reason.
  - `site` (string, required): The brand the size would have been for.
  - `format` (string, required): The format that is skipped.
  - `reason` (string, required): `Needs a design app` or `Add font: <family> <style>` (for example `Add font: Jost Bold`).
- `sizes` (integer, optional): Dry run only: how many sizes the run will make (every brand's sizes that are not skipped, the sample brand's included).
- `credits` (integer, optional): Dry run only: what those sizes cost in billable credits (0 on plans that bill none).
- `formats` (array of objects, optional): Dry run only: for each format the run could make, how many sizes it makes of it and, when it makes none, why.
  - `format` (string, required): The format key.
  - `sizes` (integer, required): Sizes of it the run makes: one for each brand that gets the format and can have it made on the server.
  - `skipped` (string, optional): Present when `sizes` is 0: why (`Needs a design app` or `Add font: <family> <style>`). A format with `Needs a design app` is made in the design app, so a caller should not ask for it here.
- `reasons` (array of objects, optional): Dry run only: why the master can't run (empty when it can).
  - `code` (string, required): A short code: `font`, `artwork`, `snapshot`, `invalid` or `resave`.
  - `element` (string, optional): The composition element the reason is about, when it is about one.
  - `text` (string, required): What to do, as the apps and the web show it (`Add font: Jost Bold`).
  - `family` (string, optional): A `font` reason: the family to add, apart from the style in `text`.

### Errors

- 400 (`unknown_site`, `unknown_format`, `bad_custom_size`, `no_sizes`): `idempotencyKey` missing or not a UUID (a field error), a brand named twice, a brand not in the campaign, or formats outside the campaign's sizes. With `campaignKey` `no-campaign`, field errors (`field` names the entry): `unknown_site`, `unknown_format`, `bad_custom_size` (with `min` and `max`), `no_sizes` (“Choose at least one size.”) and no brand named; `customSizes` with a real campaign is refused (field `customSizes`).
- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`): `403` for a role below the route's minimum (“Your role (\<role>) can't \<action>.”, or “Choose an organisation first.”), or, for an API key without the permission this call needs, code `wrong_key` with “This key needs the \<Area> · \<Read|Write> permission.” (for example “This key needs the Reviews · Write permission.”), or “This key can't do that.” for a call only the Mestra apps make.
- 404 (`headless_off`): `headless_off`, “That master isn't here any more.” or “unknown campaign”.
- 409 (`not_ready`, `no_sizes`, `nothing_to_make`, `dont_keep`, `idempotency_conflict`, `api_off`): `not_ready` (with `reasons`), `no_sizes` (a real campaign has no sizes yet: “This campaign has no sizes yet. Add sizes to the campaign.”), `nothing_to_make` (every size would be skipped: print sizes, or sites without the fonts; with the `skipped` list; no run is made and nothing is charged; a `dryRun` reports the same skips with a 200 instead), `dont_keep` (the library doesn't keep work), `idempotency_conflict`, or a billing refusal with its code (trial sizes used up, trial ended, and so on). With an API key, `api_off` (“Turn on the API in Developer → API and MCP first.”) when an owner has turned the API off.
- 501: Runs need the render service, which this server doesn't have.

### Example request

```sh
curl --request POST \
  --url https://app.withmestra.com/api/v1/masters/string/runs \
  --header "Authorization: Bearer $MESTRA_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"campaignKey":"spring-launch","sites":["ESP"],"formats":["social-feed","social-story"],"idempotencyKey":"6e1f0c2a-4b3d-4a57-9c8e-0d2b4f6a8c10"}'
```

## Retrieve a server run

`GET /api/v1/runs/{runId}`

Permission: Runs · Read.

Returns the run and the status of each size: `queued`, `building`, `reviewing`, `done`, `failed` (with a reason) or `skipped`. A finished size has links to its run and its files. Poll this until `status` is `done`, `failed` or `cancelled`. A run of another organisation is a `404`.

### Parameters

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

### Returns

The run.

### Errors

- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403: “Your role (\<role>) can't \<action>.” (the role is below the route's minimum) or “Choose an organisation first.” (the session has no organisation).
- 404 (`headless_off`): `headless_off`, or no such run in this organisation.
- 409 (`api_off`): `409` with code `api_off` (“Turn on the API in Developer → API and MCP first.”): an owner hasn't turned the API on for this organisation, so no API key works yet. An owner turns it on in Settings, then API.

### Example request

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

## List all server runs for a master

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

Permission: Runs · Read.

Returns the master's latest server runs, newest first: 10 unless you send `limit` (up to 200), and `offset` for the next page. Each has the same fields as Retrieve a server run, plus `createdAt` and `images`: for every site and format with a kept thumbnail, its `thumbId` and, when kept, the PNG or JPG `fileId`. Fetch either with Download a kept file. An unknown master gives an empty list.

### Parameters

- `id` (string (uuid), required): The saved master to run.
- `limit` (integer, optional): 1 to 200.
- `offset` (integer, optional):

### Returns

The runs.

An object with:

- `runs` (array of objects, required):
  - `runId` (string, optional):
  - `status` (string, optional):
  - `campaignKey` (string, optional):
  - `createdAt` (string (date-time), optional):
  - `version` (integer, optional, nullable): The master version the run is pinned to; null when unpinned.
  - `sites` (array of objects, optional):
  - `images` (array of objects, optional):
    - `site` (string, optional):
    - `jobId` (string, optional):
    - `format` (string, optional):
    - `thumbId` (string, optional):
    - `fileId` (string, optional):

### 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.

### Example request

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

## Cancel a server run

`DELETE /api/v1/runs/{runId}`

Permission: Runs · Write.

Stops a queued or running server run. It then reads `cancelled`, its open sizes read `failed` with the reason `Cancelled`, and sizes already built stay. Cancelling a run that is already cancelled answers `204` again.

### Parameters

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

### Returns

Cancelled (or already cancelled).

### Errors

- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`): `403` for a role below the route's minimum (“Your role (\<role>) can't \<action>.”, or “Choose an organisation first.”), or, for an API key without the permission this call needs, code `wrong_key` with “This key needs the \<Area> · \<Read|Write> permission.” (for example “This key needs the Reviews · Write permission.”), or “This key can't do that.” for a call only the Mestra apps make.
- 404 (`headless_off`): `headless_off`, or “no such run” in this organisation.
- 409 (`api_off`): “That run has already finished.” (done or failed). With an API key, `api_off` (“Turn on the API in Developer → API and MCP first.”) when an owner has turned the API off.

### Example request

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