# Starting a run

Start a run of a saved master from your code, with or without a campaign, and make a format for a typed size.

You can build a saved master's sizes from your own code, with no design app open. A run can belong to a campaign, or to none: send `campaignKey` `"no-campaign"` and name the brands and sizes yourself. Agents can use the MCP op `runs.start`.

## What you need

- A key with the **Runs · Write** permission. See [Authentication](https://withmestra.com/docs/api/authentication/).
- A saved master that is `ready`. A master that is still `checking` or `not_ready` is refused with `409` and `not_ready`, with its `reasons`.
- For a campaign: its key. For no campaign: the codes of your brands (the `centres`) and at least one size.
- To read the brands and sizes you can pick from, **Campaigns · Read**. With a key that has Runs · Write or Designs · Write and **Brand · Read**, `GET /api/v1/campaigns/no-campaign` also works without it. It lists only brands and sizes.

## Start a run for a campaign

```bash
curl -X POST https://app.withmestra.com/api/v1/masters/$MASTER_ID/runs \
  -H "Authorization: Bearer $MESTRA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignKey": "spring-launch",
    "centres": ["ESP"],
    "formats": ["social-feed", "social-story"],
    "idempotencyKey": "6e1f0c2a-4b3d-4a57-9c8e-0d2b4f6a8c10"
  }'
```

- `campaignKey`: the campaign's key.
- `centres`: brand codes. Left out, every brand of the campaign.
- `formats`: format keys from the campaign's sizes: its format set's and any formats it lists itself. Left out, all of them.
- `idempotencyKey`: a UUID you make. It is required unless `dryRun` is `true`. Send the same key with the same request and you get the run it made (`200`, no second run, no second charge). The same key with a different request is `409` `idempotency_conflict`.
- `dryRun`: `true` makes and charges nothing. It answers `200` with `sizes` (what it would make), `formats`, `skipped` and `reasons`.

A started run answers `202`:

```json
{
  "runId": "9b2e7a04-61c5-4f1d-8e3a-2c4d6f8a1b22",
  "jobs": [{ "jobId": "7d3a9c51e08b42f6", "centre": "ESP" }],
  "skipped": [{ "centre": "ESP", "format": "poster-a3", "reason": "Needs a design app" }]
}
```

A campaign no longer needs a format set. It can list its own formats, or none yet. A campaign with no sizes answers `409` with `no_sizes` and "This campaign has no sizes yet. Add sizes to the campaign." Add sizes to the campaign (its `formatSet` and `formats` fields) and start again.

## Start a run with no campaign

Send `campaignKey` `"no-campaign"`. It isn't a stored campaign. Every brand you name gets every size you name, from `formats` and `customSizes` together.

```bash
curl -X POST https://app.withmestra.com/api/v1/masters/$MASTER_ID/runs \
  -H "Authorization: Bearer $MESTRA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignKey": "no-campaign",
    "centres": ["ESP", "NTH"],
    "formats": ["social-feed"],
    "customSizes": [{ "w": 300, "h": 250, "unit": "px" }],
    "idempotencyKey": "0f7b3d9e-2a64-4c18-b5e0-91d4a7c3e6f2"
  }'
```

- `centres` is required: the codes of your own brands.
- `formats` are keys of your organisation's own formats. They are all optional if `customSizes` has an entry.
- `customSizes` is a list of `{"w", "h", "unit"}`. `unit` is `px` or `mm` (blank is `px`). Each side is from 1 to 20,000. Each size is made a format of your organisation if it has none like it, and joins `formats`. `customSizes` is only for `no-campaign`.
- You need at least one size from `formats` and `customSizes` together.

This request builds 2 brands by 2 sizes, 4 formats. The answer has the same shape as for a campaign run, one job for each brand. In `GET /api/v1/runs` and a run's detail, the run's `campaignKey` is `no-campaign` and `campaignName` is `No campaign`.

A run with no campaign can go to review and to motion. It can't be published to screens: the publish call is refused with `409` and `needs_campaign`, "Screens need a campaign. Run this design in a campaign to publish it."

### Read the brands and sizes you can pick

`GET /api/v1/campaigns/no-campaign` answers the same shape as a campaign:

```json
{
  "campaign": { "key": "no-campaign", "name": "No campaign", "centres": ["ESP", "NTH"] },
  "formats": [{ "key": "social-feed", "name": "Social feed", "width": 1080, "height": 1080, "unit": "px" }],
  "centres": [{ "code": "ESP", "name": "Eastpark" }]
}
```

`centres` lists every brand with its `uploadedLogos`, and `formats` every size your organisation has. There is no `centreSizes` or `extraFormats`: each brand gets each size.

## Make a format for a typed size

`POST /api/v1/formats/custom` answers your organisation's format for a width, height and unit, making one if there is none. It needs **Campaigns · Write**.

```bash
curl -X POST https://app.withmestra.com/api/v1/formats/custom \
  -H "Authorization: Bearer $MESTRA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"w": 300, "h": 250, "unit": "px"}'
```

```json
{ "key": "custom-300x250-px", "name": "300 × 250 px", "width": 300, "height": 250, "unit": "px" }
```

- `w` and `h` are each from 1 to 20,000. `unit` is `px` or `mm`; blank is `px`.
- If your organisation already has a format with the same width, height and unit, you get its key (the lowest key if several match). A print format is never reused.
- Otherwise a format is made. Its key is `custom-<w>x<h>-<unit>` (a decimal keeps its dot, for example `custom-99.5x210-mm`), with `-2`, `-3` and so on added if that key is a different size's. Its name is `<w> × <h> <unit>`. A format in mm is made at 150 dpi. It reviews always and exports `indd`, `png` and `jpg`, with no bleed or safe margin.
- A run's `customSizes` makes these formats for you. Call this endpoint when you want the key first, for example to list the size in a campaign's `formats`.

## When it goes wrong

| You get                                                                             | What to do                                                                                                  |
| ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `400` with a `field` of `idempotencyKey`                                            | Send a UUID as `idempotencyKey`, unless `dryRun` is `true`.                                                 |
| `400` `unknown_centre`, field `centres[i]`                                          | A brand code isn't one of your brands (with `no-campaign`), or isn't in the campaign. Check the code.       |
| `400` on `centres`                                                                  | With `no-campaign`, name at least one brand.                                                                |
| `400` `unknown_format`, field `formats[i]`                                          | The format key isn't one of your formats.                                                                   |
| `400` `bad_custom_size`, field `customSizes[i]` (or `w`, `h`), with `min` and `max` | Use a unit of `px` or `mm`, and sides from 1 to 20,000.                                                     |
| `400` on `customSizes`                                                              | `customSizes` is only for `no-campaign`. For a campaign, add the size to the campaign.                      |
| `400` `no_sizes`, "Choose at least one size."                                       | With `no-campaign`, send at least one entry in `formats` or `customSizes`.                                  |
| `409` `no_sizes`, "This campaign has no sizes yet. Add sizes to the campaign."      | Add sizes to the campaign.                                                                                  |
| `409` `not_ready`                                                                   | The master isn't `ready`. Read its `reasons`, then wait or fix it.                                          |
| `409` `nothing_to_make`                                                             | Every size would be skipped (print sizes, or brands without the fonts). Read `skipped`. Nothing is charged. |
| `409` `needs_campaign`                                                              | Screens need a campaign. Run the master in a campaign to publish it.                                        |
| `409` `api_off`                                                                     | An owner turns the API on in **Developer** > **API and MCP**.                                               |
| `404` `unknown campaign`                                                            | Check `campaignKey`.                                                                                        |

The full list of errors is in [Errors](https://withmestra.com/docs/api/errors/), and every field is in the [API reference](https://withmestra.com/docs/api/).
