# Scheduling

Scheduling puts content on screens. Add pictures, videos and HTML5 packages to the content library, then book them on screens, sites or groups for a date range. Bookings can be grouped into campaigns, and each booking can be sent live, retried or ended.

Scheduling puts content on screens. Add pictures, videos and HTML5 packages to the content library, then book them on screens, sites or groups for a date range. Bookings can be grouped into campaigns, and each booking can be sent live, retried or ended.

## The Booking object

A booking: one file from the content library on some screens for a date range and schedule, with its status, counts and whether it can be sent live, retried or ended.

- `id` (string (uuid), required):
- `name` (string, required):
- `source` (string, required):  One of: `upload`, `review`, `run`, `motion`, `dynamic`, `network`.
- `status` (string, required):
- `campaign` (object, required, nullable):
  - `id` (string, optional):
  - `name` (string, optional):
- `content` (array of objects, required):
  - `id` (string, optional):
  - `name` (string, optional):
  - `kind` (string, optional):
  - `sha256` (string, optional):
  - `thumb` (string, optional):
  - `durationMs` (integer, optional):
  - `checks` (string, optional):
- `screens` (array of objects, required):
  - `id` (string, optional):
  - `name` (string, optional):
  - `site` (object, optional, nullable):
    - `key` (string, optional):
    - `name` (string, optional):
  - `kind` (string, optional):  One of: `single`, `group`.
  - `state` (string, optional):  One of: `pending`, `draft`, `live`, `replaced`, `failed`, `ended`.
  - `cantPlay` (boolean, optional):
- `startDate` (string, required):
- `endDate` (string, required):
- `schedule` (object, required, nullable):
- `slots` (integer, required):
- `counts` (object, required):
  - `pending` (integer, optional):
  - `draft` (integer, optional):
  - `live` (integer, optional):
  - `replaced` (integer, optional):
  - `failed` (integer, optional):
  - `ended` (integer, optional):
- `live` (boolean, required):
- `canGoLive` (boolean, required):
- `canEnd` (boolean, required):
- `canRetry` (boolean, required):
- `createdAt` (string (date-time), required):
- `createdBy` (string, required):
- `plays` (object, required, nullable): With plays=1, once a play is stored.
- `links` (object, required): Main-app paths of a publish made there: `published`, and `review` when it came from a review. Empty for content booked here.
  - `published` (string, optional):
  - `review` (string, optional):
- `customer` (object, required, nullable): Who the booking is for.
  - `id` (string (uuid), optional):
  - `name` (string, optional):
  - `category` (string, optional):
- `priority` (string, required):  One of: `paid`, `house`.
- `policy` (object, required): Loop rules; a rule that is null or left out is not set.
  - `sharePct` (integer, optional, nullable):
  - `playsPerHour` (integer, optional, nullable):
  - `playsPerDay` (integer, optional, nullable):
- `outsideCampaign` (string, required, nullable): In words, why its campaign's dates or hours keep it from playing, for example `Outside its campaign's hours: won't play until 14 Dec`. `null` when it is inside them, or in no campaign.
- `zones` (array of strings, required): The time zones its screens keep, sorted (for example `Australia/Sydney`); its days and hours run on those clocks. Empty before it is made.

```json
{
  "id": "string",
  "name": "string",
  "source": "upload",
  "status": "string",
  "campaign": {
    "id": "string",
    "name": "string"
  },
  "content": [
    {
      "id": "string",
      "name": "string",
      "kind": "string",
      "sha256": "string",
      "thumb": "string",
      "durationMs": 0,
      "checks": "string"
    }
  ],
  "screens": [
    {
      "id": "string",
      "name": "string",
      "site": {
        "key": "string",
        "name": "string"
      },
      "kind": "single",
      "state": "pending",
      "cantPlay": false
    }
  ],
  "startDate": "string",
  "endDate": "string",
  "schedule": {},
  "slots": 0,
  "counts": {
    "pending": 0,
    "draft": 0,
    "live": 0,
    "replaced": 0,
    "failed": 0,
    "ended": 0
  },
  "live": false,
  "canGoLive": false,
  "canEnd": false,
  "canRetry": false,
  "createdAt": "string",
  "createdBy": "string",
  "plays": {},
  "links": {
    "published": "string",
    "review": "string"
  },
  "customer": {
    "id": "string",
    "name": "string",
    "category": "string"
  },
  "priority": "paid",
  "policy": {
    "sharePct": 0,
    "playsPerHour": 0,
    "playsPerDay": 0
  },
  "outsideCampaign": "string",
  "zones": [
    "string"
  ]
}
```

## Add content

`POST /api/v1/player/content`

Permission: Screens · Write.

Needs the Screens write permission and an editor. Adds a picture (PNG or JPEG), an MP4 video or an HTML5 package (a .zip) to the organisation's content library, to book on screens. The body is the file's bytes, sent with its `Content-Type` and its name in `X-Mestra-File-Name` (percent-encoded). An HTML5 package may send its length in milliseconds in `X-Mestra-Duration-Ms`. Names are unique in the library, in any case: a name already used is 409 `name_taken`. Mestra screens must be on and connected, and the plan must include scheduling (403 `plan_refused`).

### Parameters

- `X-Mestra-File-Name` (string, required): The file's name, percent-encoded. Unique in the library.
- `X-Mestra-Duration-Ms` (integer, optional): An HTML5 package's length in milliseconds.

### Returns

The file was added.

An object with:

- `id` (string (uuid), required):
- `name` (string, required):
- `kind` (string, required):  One of: `image`, `video`, `html5`.
- `mime` (string, required):
- `sha256` (string, required):
- `size` (integer (int64), required):
- `width` (integer, required): 0 when unknown.
- `height` (integer, required): 0 when unknown.
- `durationMs` (integer, required): A video's or package's length; 0 for a picture.
- `checks` (string, required):  One of: `none`.
- `uploadedBy` (string, required): The user who added it; empty when none.
- `createdAt` (string (date-time), required):
- `thumb` (string, required): The address of a picture's small preview, or empty.
- `bookedOn` (integer, required): Live or draft bookings that use it.

### Errors

- 400: The name is missing or not usable, or the package's length is not valid.
- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`, `plan_refused`): `wrong_key` (the key or role can't add content), or `plan_refused`.
- 409 (`name_taken`, `integration_off`, `api_off`): `name_taken`, `integration_off`, or `api_off` (an owner hasn't turned the API on).
- 413: “body exceeds limit (\<n> bytes)”.
- 415: The file is not a PNG, JPEG, MP4 or HTML5 package.
- 501: The player is not available on this server.

### Example request

```sh
curl --request POST \
  --url https://app.withmestra.com/api/v1/player/content \
  --header "Authorization: Bearer $MESTRA_TOKEN" \
  --header 'X-Mestra-File-Name: string'
```

## List all content

`GET /api/v1/player/content`

Permission: Screens · Read.

Needs the Screens read permission; any member's session (a viewer too) will do. The organisation's content library, newest first. `kind` narrows it to `image`, `video` or `html5`. `next` is the `after` value for the following page, or empty on the last.

### Parameters

- `kind` (string, optional):  One of: `image`, `video`, `html5`.
- `after` (string (uuid), optional): The `next` of the page before.
- `limit` (integer, optional):

### Returns

The files.

A list of objects, each with:

- `id` (string (uuid), required):
- `name` (string, required):
- `kind` (string, required):  One of: `image`, `video`, `html5`.
- `mime` (string, required):
- `sha256` (string, required):
- `size` (integer (int64), required):
- `width` (integer, required): 0 when unknown.
- `height` (integer, required): 0 when unknown.
- `durationMs` (integer, required): A video's or package's length; 0 for a picture.
- `checks` (string, required):  One of: `none`.
- `uploadedBy` (string, required): The user who added it; empty when none.
- `createdAt` (string (date-time), required):
- `thumb` (string, required): The address of a picture's small preview, or empty.
- `bookedOn` (integer, required): Live or draft bookings that use it.

### Errors

- 400: `kind`, `after` or `limit` is not valid.
- 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 (`not_connected`): `not_connected`.
- 409 (`api_off`, `integration_off`): `api_off` (an owner hasn't turned the API on), or `integration_off`.
- 501: The player is not available on this server.

### Example request

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

## Retrieve content

`GET /api/v1/player/content/{id}`

Permission: Screens · Read.

Needs the Screens read permission; any member's session (a viewer too) will do. One file of the content library.

### Parameters

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

### Returns

The file.

An object with:

- `id` (string (uuid), required):
- `name` (string, required):
- `kind` (string, required):  One of: `image`, `video`, `html5`.
- `mime` (string, required):
- `sha256` (string, required):
- `size` (integer (int64), required):
- `width` (integer, required): 0 when unknown.
- `height` (integer, required): 0 when unknown.
- `durationMs` (integer, required): A video's or package's length; 0 for a picture.
- `checks` (string, required):  One of: `none`.
- `uploadedBy` (string, required): The user who added it; empty when none.
- `createdAt` (string (date-time), required):
- `thumb` (string, required): The address of a picture's small preview, or empty.
- `bookedOn` (integer, required): Live or draft bookings that use it.
- `bookings` (array of objects, required): The draft and live bookings that use the file, newest first. `bookedOn` is their number.
  - `id` (string (uuid), required):
  - `name` (string, required):
  - `state` (string, required):  One of: `draft`, `live`.

### 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 (`not_connected`): No such file in this organisation, or `not_connected`.
- 409 (`api_off`, `integration_off`): `api_off` (an owner hasn't turned the API on), or `integration_off`.
- 501: The player is not available on this server.

### Example request

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

## Delete content

`DELETE /api/v1/player/content/{id}`

Permission: Screens · Write.

Needs the Screens write permission and an editor. Removes the file from the library. A booking that already plays it keeps playing it until the booking ends; `bookedOn` says how many bookings that is.

### Parameters

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

### Returns

The file was deleted.

An object with:

- `deleted` (boolean, required):
- `bookedOn` (integer, required):

### Errors

- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`, `plan_refused`): `wrong_key` (the key or role can't delete content), or `plan_refused`.
- 404 (`not_connected`): No such file in this organisation, or `not_connected`.
- 409 (`api_off`, `integration_off`): `api_off` (an owner hasn't turned the API on), or `integration_off`.
- 501: The player is not available on this server.

### Example request

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

## Create a booking

`POST /api/v1/player/bookings`

Permission: Screens · Write.

Needs the Screens write permission and an editor. Books files from the content library on screens, sites and groups for a date range and schedule. One booking is made for each file.

### Parameters

- `idempotencyKey` (string (uuid), required):
- `name` (string, optional): Empty takes the file's name.
- `campaign` (string, optional): A campaign id to put the booking in, or empty for none. An unknown or archived campaign is 409 `campaign_gone`.
- `content` (array of objects, required):
  - `id` (string (uuid), required):
  - `playLengthSeconds` (integer, optional):
- `screens` (array of strings, optional):
- `sites` (array of strings, optional): Site codes.
- `groups` (array of strings, optional):
- `startDate` (string (date), required):
- `endDate` (string (date), required):
- `schedule` (object, optional, nullable):
- `slots` (integer, optional):
- `goLive` (boolean, optional):
- `customer` (string (uuid), optional): The customer it is for, from `listMestraCustomers`. Empty for none: a booking in a campaign that has a customer is for it. An unknown customer is 404 `unknown_customer`, an archived one 409 `customer_archived`.
- `priority` (string, optional): `paid` (the default), or `house` for content that fills what paid bookings leave in a loop. A house booking needs no customer. One of: `paid`, `house`.
- `scale` (array of objects, optional): Where Scale to fit is ticked. A place that is the same shape as the file but another size (the check lists it with `scalable: true`) is booked only for a tick; the booking records who ticked it and when. A tick on a place the file already fits, or on one of another shape, is refused (`cant_play`). Needs a signed-in person.
  - `content` (string (uuid), required): The library file's id, as in `content`.
  - `frame` (string (uuid), required): The place: a frame's id, or the screen's id for its whole window.
- `policy` (object, optional): Loop rules; a rule that is null or left out is not set.
  - `sharePct` (integer, optional, nullable):
  - `playsPerHour` (integer, optional, nullable):
  - `playsPerDay` (integer, optional, nullable):

### Returns

A repeat of an earlier request: the same bookings.

An object with:

- `bookings` (array of objects, required):
  - `id` (string (uuid), required):
  - `name` (string, required):
  - `source` (string, required):  One of: `upload`, `review`, `run`, `motion`, `dynamic`, `network`.
  - `status` (string, required):
  - `campaign` (object, required, nullable):
    - `id` (string, optional):
    - `name` (string, optional):
  - `content` (array of objects, required):
    - `id` (string, optional):
    - `name` (string, optional):
    - `kind` (string, optional):
    - `sha256` (string, optional):
    - `thumb` (string, optional):
    - `durationMs` (integer, optional):
    - `checks` (string, optional):
  - `screens` (array of objects, required):
    - `id` (string, optional):
    - `name` (string, optional):
    - `site` (object, optional, nullable):
      - `key` (string, optional):
      - `name` (string, optional):
    - `kind` (string, optional):  One of: `single`, `group`.
    - `state` (string, optional):  One of: `pending`, `draft`, `live`, `replaced`, `failed`, `ended`.
    - `cantPlay` (boolean, optional):
  - `startDate` (string, required):
  - `endDate` (string, required):
  - `schedule` (object, required, nullable):
  - `slots` (integer, required):
  - `counts` (object, required):
    - `pending` (integer, optional):
    - `draft` (integer, optional):
    - `live` (integer, optional):
    - `replaced` (integer, optional):
    - `failed` (integer, optional):
    - `ended` (integer, optional):
  - `live` (boolean, required):
  - `canGoLive` (boolean, required):
  - `canEnd` (boolean, required):
  - `canRetry` (boolean, required):
  - `createdAt` (string (date-time), required):
  - `createdBy` (string, required):
  - `plays` (object, required, nullable): With plays=1, once a play is stored.
  - `links` (object, required): Main-app paths of a publish made there: `published`, and `review` when it came from a review. Empty for content booked here.
    - `published` (string, optional):
    - `review` (string, optional):
  - `customer` (object, required, nullable): Who the booking is for.
    - `id` (string (uuid), optional):
    - `name` (string, optional):
    - `category` (string, optional):
  - `priority` (string, required):  One of: `paid`, `house`.
  - `policy` (object, required): Loop rules; a rule that is null or left out is not set.
    - `sharePct` (integer, optional, nullable):
    - `playsPerHour` (integer, optional, nullable):
    - `playsPerDay` (integer, optional, nullable):
  - `outsideCampaign` (string, required, nullable): In words, why its campaign's dates or hours keep it from playing, for example `Outside its campaign's hours: won't play until 14 Dec`. `null` when it is inside them, or in no campaign.
  - `zones` (array of strings, required): The time zones its screens keep, sorted (for example `Australia/Sydney`); its days and hours run on those clocks. Empty before it is made.

### Errors

- 400: A field is missing or not usable (`idempotencyKey`, `content`, `screens`, `campaign`, `name`, `groups`).
- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`, `plan_refused`, `sales_paused`): `wrong_key` (the key or role can't do this), `plan_refused`, or `sales_paused` (new bookings are paused until an overdue invoice is paid).
- 404 (`unknown_customer`, `not_connected`): No such booking, screen or site in this key's reach, `unknown_customer` (the `customer` named is not one of the organisation's), or `not_connected`.
- 409 (`customer_archived`, `api_off`, `integration_off`, `play_length`, `publish_changed`, `cant_play`): `customer_archived` (the `customer` named is archived), `api_off`, `integration_off`, or the publish engine's own refusal (`play_length`, `publish_changed`, `cant_play` (a file the screen can't play, is another size to, or can't decode: a video that would need more pictures a second than the screen has measured, with its decoding in words), a date or capacity refusal).

### Example request

```sh
curl --request POST \
  --url https://app.withmestra.com/api/v1/player/bookings \
  --header "Authorization: Bearer $MESTRA_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"idempotencyKey":"3f6c1e7a-9b2d-4a58-8c3e-7d1f0a2b4c5d","name":"Spring sale","campaign":"c3a94d18-6e20-4b7f-8f15-2a9d0e7b4c63","content":[{"id":"5e2c8a40-91d7-4f63-b0a8-7d14c9e2f365","playLengthSeconds":10}],"screens":["2d8f6a10-5c3b-4e97-a1d4-9b0e3c7f5a28"],"startDate":"2026-12-01","endDate":"2026-12-31","slots":1,"goLive":true}'
```

## List all bookings

`GET /api/v1/player/bookings`

Permission: Screens · Read.

Needs the Screens read permission; any member's session (a viewer too) will do. Every publication to Mestra screens, newest first: bookings made here and publishes from the main app.

### Parameters

- `before` (string, optional): The `next` of the previous page.
- `plays` (string, optional): `1` for each booking's plays. One of: `1`.
- `status` (string, optional): Only bookings with this status; `live` is any booking with a live item. One of: `queued`, `running`, `done`, `partial`, `failed`, `live`.
- `campaign` (string (uuid), optional): Only bookings in this campaign.
- `customer` (string (uuid), optional): Only bookings for this customer.
- `screen` (string, optional): Only bookings with an item on this screen. A screen outside the key's reach is 404 `unknown_screen`.
- `site` (string, optional): Only bookings with an item on a screen of this site (a site code). An unknown site is 404 `unknown_site`.

### Returns

The bookings.

### Errors

- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`, `plan_refused`): `wrong_key` (the key or role can't do this), or `plan_refused`.
- 404 (`not_connected`): No such booking, screen or site in this key's reach, or `not_connected`.
- 409 (`api_off`, `integration_off`, `play_length`, `publish_changed`, `cant_play`): `api_off`, `integration_off`, or the publish engine's own refusal (`play_length`, `publish_changed`, `cant_play` (a file the screen can't play, or is another size to), a date or capacity refusal).

### Example request

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

## Retrieve a booking

`GET /api/v1/player/bookings/{id}`

Permission: Screens · Read.

Needs the Screens read permission; any member's session (a viewer too) will do. One booking.

### Parameters

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

### Returns

The booking.

### Errors

- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`, `plan_refused`): `wrong_key` (the key or role can't do this), or `plan_refused`.
- 404 (`not_connected`): No such booking, screen or site in this key's reach, or `not_connected`.
- 409 (`api_off`, `integration_off`, `play_length`, `publish_changed`, `cant_play`): `api_off`, `integration_off`, or the publish engine's own refusal (`play_length`, `publish_changed`, `cant_play` (a file the screen can't play, or is another size to), a date or capacity refusal).

### Example request

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

## Update a booking

`PATCH /api/v1/player/bookings/{id}`

Permission: Screens · Write.

Needs the Screens write permission and an editor. Renames a booking made from content, or moves it into a campaign or out of one. `customer` (a customer id, or `null` to take the customer off), `priority` (`paid`, the default, or `house` for content that fills what paid bookings leave in a loop; a house booking needs no customer) and `policy` (the booking's own caps: `sharePct`, `playsPerHour` and `playsPerDay`) change who it is for and how it takes its place in the loop. In `policy`, a rule left out stays as it is and `null` clears it. An unknown customer is 404 `unknown_customer`; an archived one is 409 `customer_archived`, though a booking keeps the archived customer it already has.

### Parameters

- `id` (string (uuid), required):
- `name` (string, optional):
- `campaign` (string, optional):
- `customer` (string (uuid), optional, nullable): The customer it is for, by id; `null` takes the customer off. An unknown customer is 404 `unknown_customer`, an archived one 409 `customer_archived`.
- `priority` (string, optional): `paid` (the default), or `house` for content that fills what paid bookings leave in a loop. A house booking needs no customer. One of: `paid`, `house`.
- `policy` (object, optional): The booking's own caps (`sharePct`, `playsPerHour`, `playsPerDay`). A rule left out stays as it is; `null` clears it.
  - `sharePct` (integer, optional, nullable):
  - `playsPerHour` (integer, optional, nullable):
  - `playsPerDay` (integer, optional, nullable):

### Returns

The booking.

### Errors

- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`, `plan_refused`): `wrong_key` (the key or role can't do this), or `plan_refused`.
- 404 (`unknown_customer`, `not_connected`): No such booking, screen or site in this key's reach, `unknown_customer` (the `customer` named is not one of the organisation's), or `not_connected`.
- 409 (`customer_archived`, `api_off`, `integration_off`, `play_length`, `publish_changed`, `cant_play`): `customer_archived` (the `customer` named is archived), `api_off`, `integration_off`, or the publish engine's own refusal (`play_length`, `publish_changed`, `cant_play` (a file the screen can't play, or is another size to), a date or capacity refusal).

### Example request

```sh
curl --request PATCH \
  --url https://app.withmestra.com/api/v1/player/bookings/string \
  --header "Authorization: Bearer $MESTRA_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"name":"Spring sale, week 2","campaign":"c3a94d18-6e20-4b7f-8f15-2a9d0e7b4c63","customer":"5b1f0c7e-3a42-4d8e-9a67-0c2e4f6a8b10","policy":{"sharePct":25,"playsPerHour":null}}'
```

## Start a booking on its screens

`POST /api/v1/player/bookings/{id}/go-live`

Permission: Screens · Write.

Needs the Screens write permission and an editor. Sends the booking's drafts to the screens.

### Parameters

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

### Returns

Accepted: the runner will do it.

An object with:

- `id` (string, optional):
- `sending` (integer, optional):
- `items` (integer, optional):

### Errors

- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`, `plan_refused`, `sales_paused`): `wrong_key` (the key or role can't do this), `plan_refused`, or `sales_paused` (new bookings are paused until an overdue invoice is paid).
- 404 (`not_connected`): No such booking, screen or site in this key's reach, or `not_connected`.
- 409 (`api_off`, `integration_off`, `play_length`, `publish_changed`, `cant_play`): `api_off`, `integration_off`, or the publish engine's own refusal (`play_length`, `publish_changed`, `cant_play` (a file the screen can't play, or is another size to), a date or capacity refusal).

### Example request

```sh
curl --request POST \
  --url https://app.withmestra.com/api/v1/player/bookings/string/go-live \
  --header "Authorization: Bearer $MESTRA_TOKEN"
```

## Start a booking again

`POST /api/v1/player/bookings/{id}/retry`

Permission: Screens · Write.

Needs the Screens write permission and an editor. Tries a booking's failed screens again.

### Parameters

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

### Returns

Accepted: the runner will do it.

An object with:

- `id` (string, optional):
- `sending` (integer, optional):
- `items` (integer, optional):

### Errors

- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`, `plan_refused`): `wrong_key` (the key or role can't do this), or `plan_refused`.
- 404 (`not_connected`): No such booking, screen or site in this key's reach, or `not_connected`.
- 409 (`api_off`, `integration_off`, `play_length`, `publish_changed`, `cant_play`): `api_off`, `integration_off`, or the publish engine's own refusal (`play_length`, `publish_changed`, `cant_play` (a file the screen can't play, or is another size to), a date or capacity refusal).

### Example request

```sh
curl --request POST \
  --url https://app.withmestra.com/api/v1/player/bookings/string/retry \
  --header "Authorization: Bearer $MESTRA_TOKEN"
```

## Stop a booking

`POST /api/v1/player/bookings/{id}/end`

Permission: Screens · Write.

Needs the Screens write permission and an editor. Takes a booking off every screen it plays on, and answers the takedown that confirms each screen.

### Parameters

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

### Returns

The key was already used for this booking. The takedown it made.

Returns the Takedown object (/docs/api/stop-and-takedowns/#object).

### Errors

- 400: `idempotencyKey` or `reason` (with `field`).
- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`, `screens_limited`): `wrong_key` (the key or role can't do this), or a key limited to some screens (`screens_limited`).
- 404 (`not_connected`): No such booking, screen or site in this key's reach, or `not_connected`.
- 409 (`idempotency_conflict`, `publication_busy`, `api_off`, `integration_off`): `idempotency_conflict`, `publication_busy`, `api_off` or `integration_off`.

### Example request

```sh
curl --request POST \
  --url https://app.withmestra.com/api/v1/player/bookings/string/end \
  --header "Authorization: Bearer $MESTRA_TOKEN"
```

## List all screen campaigns

`GET /api/v1/player/campaigns`

Permission: Screens · Read.

Needs the Screens read permission; any member's session (a viewer too) will do. The campaigns that group bookings, with how many bookings each holds.

### Parameters

- `customer` (string (uuid), optional): Only the campaigns that are for this customer.

### Returns

The campaigns.

An object with:

- `campaigns` (array of objects, required):
  - `id` (string (uuid), required):
  - `name` (string, required):
  - `startDate` (string, required): A note, `YYYY-MM-DD`, or empty. It gates nothing.
  - `endDate` (string, required): A note, `YYYY-MM-DD`, or empty.
  - `archived` (boolean, required):
  - `bookings` (integer, required): Bookings in the campaign.
  - `live` (integer, required): Those with a file on a screen now.
  - `customer` (object, required, nullable): Who the campaign is for. Its bookings with no customer of their own are for it.
    - `id` (string (uuid), optional):
    - `name` (string, optional):
    - `category` (string, optional):
  - `policy` (object, required): Loop rules; a rule that is null or left out is not set.
    - `sharePct` (integer, optional, nullable):
    - `playsPerHour` (integer, optional, nullable):
    - `playsPerDay` (integer, optional, nullable):
  - `window` (object, required, nullable): The daily window its bookings play in (`null` for none).
    - `start` (string, optional):
    - `end` (string, optional):
    - `days` (array of strings, optional):

### Errors

- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`): `wrong_key` (the key or role can't do this).
- 404 (`not_connected`): `not_connected`.
- 409 (`api_off`, `integration_off`): `api_off` or `integration_off`.

### Example request

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

## Create a screen campaign

`POST /api/v1/player/campaigns`

Permission: Screens · Write.

Needs the Screens write permission and an editor. A named group of bookings. Its dates are a note and gate nothing.

### Parameters

- `name` (string, required):
- `startDate` (string, optional):
- `endDate` (string, optional):
- `customer` (string (uuid), optional):
- `policy` (object, optional): Loop rules; a rule that is null or left out is not set.
  - `sharePct` (integer, optional, nullable):
  - `playsPerHour` (integer, optional, nullable):
  - `playsPerDay` (integer, optional, nullable):
- `window` (object, optional): The daily window its bookings play in; its dates and window keep them from playing outside them. `start` and `end` are `HH:MM` (empty clears them); `days` are mon to sun (empty is every day).
  - `start` (string, optional):
  - `end` (string, optional):
  - `days` (array of strings, optional):

### Returns

The campaign.

An object with:

- `id` (string (uuid), required):
- `name` (string, required):
- `startDate` (string, required): A note, `YYYY-MM-DD`, or empty. It gates nothing.
- `endDate` (string, required): A note, `YYYY-MM-DD`, or empty.
- `archived` (boolean, required):
- `bookings` (integer, required): Bookings in the campaign.
- `live` (integer, required): Those with a file on a screen now.
- `customer` (object, required, nullable): Who the campaign is for. Its bookings with no customer of their own are for it.
  - `id` (string (uuid), optional):
  - `name` (string, optional):
  - `category` (string, optional):
- `policy` (object, required): Loop rules; a rule that is null or left out is not set.
  - `sharePct` (integer, optional, nullable):
  - `playsPerHour` (integer, optional, nullable):
  - `playsPerDay` (integer, optional, nullable):
- `window` (object, required, nullable): The daily window its bookings play in (`null` for none).
  - `start` (string, optional):
  - `end` (string, optional):
  - `days` (array of strings, optional):

### Errors

- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`, `plan_refused`): `wrong_key` (the key or role can't do this), a key limited to some screens, or `plan_refused`.
- 404 (`not_connected`): `not_connected`.
- 409 (`name_taken`, `api_off`, `integration_off`): `name_taken`, `api_off` or `integration_off`.

### Example request

```sh
curl --request POST \
  --url https://app.withmestra.com/api/v1/player/campaigns \
  --header "Authorization: Bearer $MESTRA_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"name":"Spring sale","startDate":"2026-12-01","endDate":"2026-12-31"}'
```

## Retrieve a screen campaign

`GET /api/v1/player/campaigns/{id}`

Permission: Screens · Read.

Needs the Screens read permission; any member's session (a viewer too) will do. One campaign, archived or not.

### Parameters

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

### Returns

The campaign.

An object with:

- `id` (string (uuid), required):
- `name` (string, required):
- `startDate` (string, required): A note, `YYYY-MM-DD`, or empty. It gates nothing.
- `endDate` (string, required): A note, `YYYY-MM-DD`, or empty.
- `archived` (boolean, required):
- `bookings` (integer, required): Bookings in the campaign.
- `live` (integer, required): Those with a file on a screen now.
- `customer` (object, required, nullable): Who the campaign is for. Its bookings with no customer of their own are for it.
  - `id` (string (uuid), optional):
  - `name` (string, optional):
  - `category` (string, optional):
- `policy` (object, required): Loop rules; a rule that is null or left out is not set.
  - `sharePct` (integer, optional, nullable):
  - `playsPerHour` (integer, optional, nullable):
  - `playsPerDay` (integer, optional, nullable):
- `window` (object, required, nullable): The daily window its bookings play in (`null` for none).
  - `start` (string, optional):
  - `end` (string, optional):
  - `days` (array of strings, optional):

### Errors

- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`): `wrong_key` (the key or role can't do this).
- 404: No such campaign.
- 409 (`api_off`, `integration_off`): `api_off` or `integration_off`.

### Example request

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

## Update a screen campaign

`PATCH /api/v1/player/campaigns/{id}`

Permission: Screens · Write.

Needs the Screens write permission and an editor. Renames a campaign or changes its dates.

### Parameters

- `id` (string (uuid), required):
- `name` (string, optional):
- `startDate` (string, optional):
- `endDate` (string, optional):
- `customer` (string (uuid), optional, nullable):
- `policy` (object, optional): Loop rules; a rule set to null is cleared and one left out is kept.
  - `sharePct` (integer, optional, nullable):
  - `playsPerHour` (integer, optional, nullable):
  - `playsPerDay` (integer, optional, nullable):
- `window` (object, optional): Send only what changes: `start` and `end` are `HH:MM` (empty clears them); `days` are mon to sun (empty is every day).
  - `start` (string, optional):
  - `end` (string, optional):
  - `days` (array of strings, optional):

### Returns

The campaign.

An object with:

- `id` (string (uuid), required):
- `name` (string, required):
- `startDate` (string, required): A note, `YYYY-MM-DD`, or empty. It gates nothing.
- `endDate` (string, required): A note, `YYYY-MM-DD`, or empty.
- `archived` (boolean, required):
- `bookings` (integer, required): Bookings in the campaign.
- `live` (integer, required): Those with a file on a screen now.
- `customer` (object, required, nullable): Who the campaign is for. Its bookings with no customer of their own are for it.
  - `id` (string (uuid), optional):
  - `name` (string, optional):
  - `category` (string, optional):
- `policy` (object, required): Loop rules; a rule that is null or left out is not set.
  - `sharePct` (integer, optional, nullable):
  - `playsPerHour` (integer, optional, nullable):
  - `playsPerDay` (integer, optional, nullable):
- `window` (object, required, nullable): The daily window its bookings play in (`null` for none).
  - `start` (string, optional):
  - `end` (string, optional):
  - `days` (array of strings, optional):

### Errors

- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`, `plan_refused`): `wrong_key` (the key or role can't do this), a key limited to some screens, or `plan_refused`.
- 404: No such campaign.
- 409 (`name_taken`, `api_off`, `integration_off`): `name_taken`, `api_off` or `integration_off`.

### Example request

```sh
curl --request PATCH \
  --url https://app.withmestra.com/api/v1/player/campaigns/string \
  --header "Authorization: Bearer $MESTRA_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"endDate":"2027-01-15"}'
```

## Update a screen campaign to archived

`POST /api/v1/player/campaigns/{id}/archive`

Permission: Screens · Write.

Needs the Screens write permission and an editor. Takes a campaign off the pick-list; its bookings stay in it.

### Parameters

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

### Returns

The campaign, archived.

An object with:

- `id` (string (uuid), required):
- `name` (string, required):
- `startDate` (string, required): A note, `YYYY-MM-DD`, or empty. It gates nothing.
- `endDate` (string, required): A note, `YYYY-MM-DD`, or empty.
- `archived` (boolean, required):
- `bookings` (integer, required): Bookings in the campaign.
- `live` (integer, required): Those with a file on a screen now.
- `customer` (object, required, nullable): Who the campaign is for. Its bookings with no customer of their own are for it.
  - `id` (string (uuid), optional):
  - `name` (string, optional):
  - `category` (string, optional):
- `policy` (object, required): Loop rules; a rule that is null or left out is not set.
  - `sharePct` (integer, optional, nullable):
  - `playsPerHour` (integer, optional, nullable):
  - `playsPerDay` (integer, optional, nullable):
- `window` (object, required, nullable): The daily window its bookings play in (`null` for none).
  - `start` (string, optional):
  - `end` (string, optional):
  - `days` (array of strings, optional):

### Errors

- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`, `plan_refused`): `wrong_key` (the key or role can't do this), a key limited to some screens, or `plan_refused`.
- 404: No such campaign.
- 409 (`api_off`, `integration_off`): `api_off` or `integration_off`.

### Example request

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

## Update a booking's volume

`PATCH /api/v1/player/entries/{id}`

Permission: Screens · Write.

Needs the Screens write permission and an owner. `volume` is 0 to 100, or `null` to play the booking muted. It is heard only at a screen whose sound is on. A key limited to some screens may set it only for a booking that plays on its own screens alone (403 `screens_limited`).

### Parameters

- `id` (string (uuid), required):
- `volume` (integer, required, nullable):

### Returns

The booking's volume as it is now.

An object with:

- `id` (string, optional):
- `volume` (integer, optional, nullable):

### Errors

- 400: A volume that is not 0 to 100 or null (with `field`).
- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`, `screens_limited`): `wrong_key`, `screens_limited`, or a role below an owner's.
- 404 (`unknown_booking`, `not_connected`): `unknown_booking` (not a booking of the organisation), or `not_connected`.
- 409 (`api_off`, `integration_off`): `api_off` (an owner hasn't turned the API on), or `integration_off`.
- 413: “body exceeds limit (\<n> bytes)”.
- 501: The player is not available on this server.

### Example request

```sh
curl --request PATCH \
  --url https://app.withmestra.com/api/v1/player/entries/string \
  --header "Authorization: Bearer $MESTRA_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"volume":40}'
```

## Retrieve a content preview

`GET /api/v1/player/content/{id}/thumb`

Permission: Screens · Read.

Needs the Screens read permission; any member's session (a viewer too) will do. The small PNG preview of a content picture or video, at the address in its `thumb`.

### Parameters

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

### Returns

The PNG.

### 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 (`not_connected`): No such file in this organisation, no preview, or `not_connected`.
- 409 (`api_off`, `integration_off`): `api_off` (an owner hasn't turned the API on), or `integration_off`.

### Example request

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