# Reviews

A review is how a team or a client approves a campaign's sizes for one brand. The campaign's results are sent for review in rounds; each size is approved or sent back with comments. Exports collect the approved files.

A review is how a team or a client approves a campaign's sizes for one brand. The campaign's results are sent for review in rounds; each size is approved or sent back with comments. Exports collect the approved files.

## The Review object

The review object. A review is for one campaign and one brand.

- `kind` (string, required): `stills` (a review of images) or `motion` (a review of animated versions). A motion review holds MP4s and posters of a stills review's sizes. One of: `stills`, `motion`.
- `sourceId` (string (uuid), required, nullable): A motion review's stills review, for members; null for a stills review and once the stills review is deleted.
- `approval` (string, required): The latest round's rule. One of: `all`, `any`.
- `due` (string (date), required, nullable): The latest round's due date, or null.
- `overdue` (boolean, required): The due day has ended in Sydney and a size isn't approved. Worked out on the server.
- `assignees` (array of objects, required): The latest round's current assignees.
  - `name` (string, required): The person's name.
  - `outside` (boolean, required): True for an outside reviewer, false for a member.
  - `you` (boolean, required): True when this is the caller.
  - `waiting` (boolean, required): A size of the round needs review and they have no standing decision on it.
  - `userId` (string (uuid), optional): A member; never sent to an outside reviewer.
  - `reviewerId` (string (uuid), optional): An outside reviewer; never sent to an outside reviewer.
- `assignedToYou` (boolean, required): True when the latest round is assigned and the caller is one of the assignees.
- `override` (object, required, nullable): "Approved by <by> on behalf of <for>": the latest standing approvals one owner or editor made for others. Null unless the status is `approved` and the approvals still stand.
  - `by` (string, required): Who approved on behalf of others.
  - `for` (array of strings, required): Whose approvals were made on their behalf.
  - `at` (string (date-time), required): When.
- `canMove` (boolean, required): An owner or editor who didn't send the latest round.
- `archivedAt` (string (date-time), required, nullable): When the review was archived; null for a current review. An archived review is left out of the default list.
- `id` (string (uuid), required): The review's id.
- `campaignKey` (string, required): The campaign under review.
- `site` (string, required): The brand code under review.
- `name` (string, required): The campaign's name now; its key when the setup no longer has it.
- `brandName` (string, required): The brand's name now; its code when the setup no longer has it.
- `status` (string, required): `empty`: nothing sent yet; `needs_review`; `changes_requested`; `approved`. One of: `empty`, `needs_review`, `changes_requested`, `approved`.
- `latestRound` (integer, required): The number of the latest round; 0 before the first.
- `progress` (object, required): How the latest round's sizes stand.
  - `sizes` (integer, required): Sizes in the latest round.
  - `approved` (integer, required): Sizes approved.
  - `changesRequested` (integer, required): Sizes with changes requested.
  - `needsReview` (integer, required): Sizes still waiting for a decision.
- `createdAt` (string (date-time), required): When the review was started.
- `lastActivityAt` (string (date-time), required): When something last happened in the review.
- `expiresAt` (string (date-time), required, nullable): The last activity plus the library's retention; null under Keep everything.

```json
{
  "id": "string",
  "kind": "stills",
  "sourceId": "string",
  "campaignKey": "string",
  "site": "string",
  "name": "string",
  "brandName": "string",
  "status": "empty",
  "latestRound": 0,
  "progress": {
    "sizes": 0,
    "approved": 0,
    "changesRequested": 0,
    "needsReview": 0
  },
  "createdAt": "string",
  "lastActivityAt": "string",
  "expiresAt": "string",
  "approval": "all",
  "assignees": [
    {
      "name": "string",
      "outside": false,
      "you": false,
      "waiting": false
    }
  ],
  "assignedToYou": false,
  "canMove": false,
  "due": "string",
  "overdue": false,
  "archivedAt": "string"
}
```

## Start a review

`POST /api/v1/reviews/campaigns`

Permission: Reviews · Write.

Starts the review of a campaign for one brand, or returns the one that already exists. `201` means a new review was made; `200` returns the existing review for that campaign and brand and changes nothing. Refused while the organisation's account is read-only, and with `409 review_dont_keep` when the organisation's library is set to "Don't keep", because a review needs its files kept.

### Parameters

- `campaignKey` (string, required):
- `site` (string, required): A brand's code; it must be one of the campaign's.

### Returns

The existing review.

An object with:

- `kind` (string, required): `stills` (a review of images) or `motion` (a review of animated versions). A motion review holds MP4s and posters of a stills review's sizes. One of: `stills`, `motion`.
- `sourceId` (string (uuid), required, nullable): A motion review's stills review, for members; null for a stills review and once the stills review is deleted.
- `approval` (string, required): The latest round's rule. One of: `all`, `any`.
- `due` (string (date), required, nullable): The latest round's due date, or null.
- `overdue` (boolean, required): The due day has ended in Sydney and a size isn't approved. Worked out on the server.
- `assignees` (array of objects, required): The latest round's current assignees.
  - `name` (string, required): The person's name.
  - `outside` (boolean, required): True for an outside reviewer, false for a member.
  - `you` (boolean, required): True when this is the caller.
  - `waiting` (boolean, required): A size of the round needs review and they have no standing decision on it.
  - `userId` (string (uuid), optional): A member; never sent to an outside reviewer.
  - `reviewerId` (string (uuid), optional): An outside reviewer; never sent to an outside reviewer.
- `assignedToYou` (boolean, required): True when the latest round is assigned and the caller is one of the assignees.
- `override` (object, required, nullable): "Approved by <by> on behalf of <for>": the latest standing approvals one owner or editor made for others. Null unless the status is `approved` and the approvals still stand.
  - `by` (string, required): Who approved on behalf of others.
  - `for` (array of strings, required): Whose approvals were made on their behalf.
  - `at` (string (date-time), required): When.
- `canMove` (boolean, required): An owner or editor who didn't send the latest round.
- `archivedAt` (string (date-time), required, nullable): When the review was archived; null for a current review. An archived review is left out of the default list.
- `id` (string (uuid), required): The review's id.
- `campaignKey` (string, required): The campaign under review.
- `site` (string, required): The brand code under review.
- `name` (string, required): The campaign's name now; its key when the setup no longer has it.
- `brandName` (string, required): The brand's name now; its code when the setup no longer has it.
- `status` (string, required): `empty`: nothing sent yet; `needs_review`; `changes_requested`; `approved`. One of: `empty`, `needs_review`, `changes_requested`, `approved`.
- `latestRound` (integer, required): The number of the latest round; 0 before the first.
- `progress` (object, required): How the latest round's sizes stand.
  - `sizes` (integer, required): Sizes in the latest round.
  - `approved` (integer, required): Sizes approved.
  - `changesRequested` (integer, required): Sizes with changes requested.
  - `needsReview` (integer, required): Sizes still waiting for a decision.
- `createdAt` (string (date-time), required): When the review was started.
- `lastActivityAt` (string (date-time), required): When something last happened in the review.
- `expiresAt` (string (date-time), required, nullable): The last activity plus the library's retention; null under Keep everything.
- `rounds` (array of objects, required): Every round of the review, oldest first.
  - `number` (integer, required): The round's number, from 1.
  - `source` (string, required): Where the round came from: `plugin`, `applied`, `run`, `motion`, `rules`, or `edited` (a hand edit saved in the editor). One of: `plugin`, `applied`, `run`, `motion`, `rules`, `edited`.
  - `fromRun` (object, optional, nullable): The run a round was sent from (`id`), for members; null for other rounds and for outside reviewers.
    - `id` (string, optional): The run's id.
  - `fromMotion` (object, optional, nullable): The motion version a round was sent from (`jobId`), for members; null for other rounds and for outside reviewers.
    - `jobId` (string, optional): The motion version's id.
  - `tool` (string, required): The app the round was sent from: `indesign`, `figma` or `canva` (`mestra` for a motion round).
  - `note` (string, required): The note the sender left with the round.
  - `author` (object, required): Who sent the round.
    - `name` (string, required): The sender's name.
    - `you` (boolean, required): True when the caller sent it.
  - `createdAt` (string (date-time), required): When the round was sent.
  - `sizes` (integer, required): How many sizes the round holds.
  - `changed` (integer, required): How many of its sizes changed since the round before.
- `you` (object, required): What the caller may do in this review.
  - `canComment` (boolean, required): May comment.
  - `canDecide` (boolean, required): False when the latest round has assignees and you aren't one.
  - `canSend` (boolean, required): May send a new round.
  - `canResolve` (boolean, required): May resolve comments.
  - `canManageLinks` (boolean, required): May manage links for outside reviewers.
  - `canDownload` (boolean, required): May download exports.
  - `canArchive` (boolean, required): May archive and unarchive the review (editors and owners, members only).
  - `canDelete` (boolean, required): May delete the review (owners, members only).

### Errors

- 400: `bad JSON: <error>` or `bad JSON: trailing data after the request object`.
- 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: “That campaign or brand isn't in your setup.”
- 409 (`review_dont_keep`, `api_off`): `review_dont_keep`: “Reviews need the library to keep files. An owner can change this in Settings.” With an API key, `api_off` (“Turn on the API in Developer → API and MCP first.”) when an owner has turned the API off.
- 413: “body exceeds limit (4096 bytes)”
- 500: “could not complete that review change”, “Couldn't save that change. Try again.” (the change could not be recorded, so it was not made), “could not check token”, “could not check session” or “could not read those review notes”.
- 501: “Review isn't available on this server.”

### Example request

```sh
curl --request POST \
  --url https://app.withmestra.com/api/v1/reviews/campaigns \
  --header "Authorization: Bearer $MESTRA_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"campaignKey":"spring-launch","site":"ESP"}'
```

## Retrieve a review

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

Permission: Reviews · Read.

Returns the review with its rounds and what the caller may do in it. A review of another organisation, a missing one and a malformed id are all `404`.

### Parameters

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

### Returns

The review.

An object with:

- `kind` (string, required): `stills` (a review of images) or `motion` (a review of animated versions). A motion review holds MP4s and posters of a stills review's sizes. One of: `stills`, `motion`.
- `sourceId` (string (uuid), required, nullable): A motion review's stills review, for members; null for a stills review and once the stills review is deleted.
- `approval` (string, required): The latest round's rule. One of: `all`, `any`.
- `due` (string (date), required, nullable): The latest round's due date, or null.
- `overdue` (boolean, required): The due day has ended in Sydney and a size isn't approved. Worked out on the server.
- `assignees` (array of objects, required): The latest round's current assignees.
  - `name` (string, required): The person's name.
  - `outside` (boolean, required): True for an outside reviewer, false for a member.
  - `you` (boolean, required): True when this is the caller.
  - `waiting` (boolean, required): A size of the round needs review and they have no standing decision on it.
  - `userId` (string (uuid), optional): A member; never sent to an outside reviewer.
  - `reviewerId` (string (uuid), optional): An outside reviewer; never sent to an outside reviewer.
- `assignedToYou` (boolean, required): True when the latest round is assigned and the caller is one of the assignees.
- `override` (object, required, nullable): "Approved by <by> on behalf of <for>": the latest standing approvals one owner or editor made for others. Null unless the status is `approved` and the approvals still stand.
  - `by` (string, required): Who approved on behalf of others.
  - `for` (array of strings, required): Whose approvals were made on their behalf.
  - `at` (string (date-time), required): When.
- `canMove` (boolean, required): An owner or editor who didn't send the latest round.
- `archivedAt` (string (date-time), required, nullable): When the review was archived; null for a current review. An archived review is left out of the default list.
- `id` (string (uuid), required): The review's id.
- `campaignKey` (string, required): The campaign under review.
- `site` (string, required): The brand code under review.
- `name` (string, required): The campaign's name now; its key when the setup no longer has it.
- `brandName` (string, required): The brand's name now; its code when the setup no longer has it.
- `status` (string, required): `empty`: nothing sent yet; `needs_review`; `changes_requested`; `approved`. One of: `empty`, `needs_review`, `changes_requested`, `approved`.
- `latestRound` (integer, required): The number of the latest round; 0 before the first.
- `progress` (object, required): How the latest round's sizes stand.
  - `sizes` (integer, required): Sizes in the latest round.
  - `approved` (integer, required): Sizes approved.
  - `changesRequested` (integer, required): Sizes with changes requested.
  - `needsReview` (integer, required): Sizes still waiting for a decision.
- `createdAt` (string (date-time), required): When the review was started.
- `lastActivityAt` (string (date-time), required): When something last happened in the review.
- `expiresAt` (string (date-time), required, nullable): The last activity plus the library's retention; null under Keep everything.
- `rounds` (array of objects, required): Every round of the review, oldest first.
  - `number` (integer, required): The round's number, from 1.
  - `source` (string, required): Where the round came from: `plugin`, `applied`, `run`, `motion`, `rules`, or `edited` (a hand edit saved in the editor). One of: `plugin`, `applied`, `run`, `motion`, `rules`, `edited`.
  - `fromRun` (object, optional, nullable): The run a round was sent from (`id`), for members; null for other rounds and for outside reviewers.
    - `id` (string, optional): The run's id.
  - `fromMotion` (object, optional, nullable): The motion version a round was sent from (`jobId`), for members; null for other rounds and for outside reviewers.
    - `jobId` (string, optional): The motion version's id.
  - `tool` (string, required): The app the round was sent from: `indesign`, `figma` or `canva` (`mestra` for a motion round).
  - `note` (string, required): The note the sender left with the round.
  - `author` (object, required): Who sent the round.
    - `name` (string, required): The sender's name.
    - `you` (boolean, required): True when the caller sent it.
  - `createdAt` (string (date-time), required): When the round was sent.
  - `sizes` (integer, required): How many sizes the round holds.
  - `changed` (integer, required): How many of its sizes changed since the round before.
- `you` (object, required): What the caller may do in this review.
  - `canComment` (boolean, required): May comment.
  - `canDecide` (boolean, required): False when the latest round has assignees and you aren't one.
  - `canSend` (boolean, required): May send a new round.
  - `canResolve` (boolean, required): May resolve comments.
  - `canManageLinks` (boolean, required): May manage links for outside reviewers.
  - `canDownload` (boolean, required): May download exports.
  - `canArchive` (boolean, required): May archive and unarchive the review (editors and owners, members only).
  - `canDelete` (boolean, required): May delete the review (owners, members only).

### 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: “That review no longer exists.” (including another organisation's review and a malformed id).
- 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 complete that review change”, “Couldn't save that change. Try again.” (the change could not be recorded, so it was not made), “could not check token”, “could not check session” or “could not read those review notes”.
- 501: “Review isn't available on this server.”

### Example request

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

## List all reviews

`GET /api/v1/reviews/campaigns`

Permission: Reviews · Read.

Returns the organisation's reviews, newest first, each with its campaign, brand and where its latest round stands.

### Parameters

- `archived` (string, optional): `1` lists the archived reviews instead of the current ones. Any other value is ignored. One of: `1`.

### Returns

The reviews, without their rounds.

An object with:

- `campaigns` (array of objects, required):
  - `kind` (string, required): `stills` (a review of images) or `motion` (a review of animated versions). A motion review holds MP4s and posters of a stills review's sizes. One of: `stills`, `motion`.
  - `sourceId` (string (uuid), required, nullable): A motion review's stills review, for members; null for a stills review and once the stills review is deleted.
  - `approval` (string, required): The latest round's rule. One of: `all`, `any`.
  - `due` (string (date), required, nullable): The latest round's due date, or null.
  - `overdue` (boolean, required): The due day has ended in Sydney and a size isn't approved. Worked out on the server.
  - `assignees` (array of objects, required): The latest round's current assignees.
    - `name` (string, required): The person's name.
    - `outside` (boolean, required): True for an outside reviewer, false for a member.
    - `you` (boolean, required): True when this is the caller.
    - `waiting` (boolean, required): A size of the round needs review and they have no standing decision on it.
    - `userId` (string (uuid), optional): A member; never sent to an outside reviewer.
    - `reviewerId` (string (uuid), optional): An outside reviewer; never sent to an outside reviewer.
  - `assignedToYou` (boolean, required): True when the latest round is assigned and the caller is one of the assignees.
  - `override` (object, required, nullable): "Approved by <by> on behalf of <for>": the latest standing approvals one owner or editor made for others. Null unless the status is `approved` and the approvals still stand.
    - `by` (string, required): Who approved on behalf of others.
    - `for` (array of strings, required): Whose approvals were made on their behalf.
    - `at` (string (date-time), required): When.
  - `canMove` (boolean, required): An owner or editor who didn't send the latest round.
  - `archivedAt` (string (date-time), required, nullable): When the review was archived; null for a current review. An archived review is left out of the default list.
  - `id` (string (uuid), required): The review's id.
  - `campaignKey` (string, required): The campaign under review.
  - `site` (string, required): The brand code under review.
  - `name` (string, required): The campaign's name now; its key when the setup no longer has it.
  - `brandName` (string, required): The brand's name now; its code when the setup no longer has it.
  - `status` (string, required): `empty`: nothing sent yet; `needs_review`; `changes_requested`; `approved`. One of: `empty`, `needs_review`, `changes_requested`, `approved`.
  - `latestRound` (integer, required): The number of the latest round; 0 before the first.
  - `progress` (object, required): How the latest round's sizes stand.
    - `sizes` (integer, required): Sizes in the latest round.
    - `approved` (integer, required): Sizes approved.
    - `changesRequested` (integer, required): Sizes with changes requested.
    - `needsReview` (integer, required): Sizes still waiting for a decision.
  - `createdAt` (string (date-time), required): When the review was started.
  - `lastActivityAt` (string (date-time), required): When something last happened in the review.
  - `expiresAt` (string (date-time), required, nullable): The last activity plus the library's retention; null under Keep everything.
- `archivedCount` (integer, required): How many of the organisation's reviews are archived, whichever list this is.

### 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 complete that review change”, “Couldn't save that change. Try again.” (the change could not be recorded, so it was not made), “could not check token”, “could not check session” or “could not read those review notes”.
- 501: “Review isn't available on this server.”

### Example request

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

## Retrieve a round

`GET /api/v1/reviews/campaigns/{id}/rounds/{n}`

Permission: Reviews · Read.

Returns one round of a review: each size with its status, decisions and whether it changed since the round before. A round that doesn't exist is a `404`.

### Parameters

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

### Returns

The round.

An object with:

- `approval` (string, required): `all`: every assignee must approve a size; `any`: the first assignee to approve is enough. One of: `all`, `any`.
- `due` (string (date), required, nullable): The round's due date, or null.
- `overdue` (boolean, required): The due day has ended in Sydney and a size isn't approved. Worked out on the server.
- `assignees` (array of objects, required): The people the round is assigned to; empty when it is open to everyone.
  - `name` (string, required): The person's name.
  - `outside` (boolean, required): True for an outside reviewer, false for a member.
  - `you` (boolean, required): True when this is the caller.
  - `waiting` (boolean, required): A size of the round needs review and they have no standing decision on it.
  - `userId` (string (uuid), optional): A member; never sent to an outside reviewer.
  - `reviewerId` (string (uuid), optional): An outside reviewer; never sent to an outside reviewer.
- `number` (integer, required): The round's number, from 1.
- `source` (string, required): Where the round came from: `plugin`, `run`, `applied`, `motion`, `rules`, or `edited` (a hand edit saved in the editor). One of: `plugin`, `run`, `applied`, `motion`, `rules`, `edited`.
- `fromRun` (object, optional, nullable): The run a round was sent from (`id`), for members; null for other rounds and for outside reviewers.
  - `id` (string, optional): The run's id.
- `fromMotion` (object, optional, nullable): The motion version a round was sent from (`jobId`), for members; null for other rounds and for outside reviewers.
  - `jobId` (string, optional): The motion version's id.
- `tool` (string, required): The app the round was sent from: `indesign`, `figma` or `canva` (`mestra` for a motion round).
- `note` (string, required): The note the sender left with the round.
- `author` (object, required): Who sent the round.
  - `name` (string, required): The sender's name.
  - `you` (boolean, required): True when the caller sent it.
- `appliedFrom` (object, required, nullable): Set when the round came from applying an earlier review; otherwise null.
- `createdAt` (string (date-time), required): When the round was sent.
- `latest` (boolean, required): True for the newest round, the only one that can be decided, assigned or given a due date.
- `sizes` (array of objects, required): The round's sizes.
  - `video` (string, required, nullable): A motion size's MP4, an asset id (its SHA-256) served at `/reviews/campaigns/{id}/assets/{asset}`; null for a stills size. `snapshot` is its poster.
  - `notes` (integer, required, nullable): How many notes (issues and distinct flags; element flags once per code) the size's review notes hold. Null when none were sent, and always null for outside reviewers.
  - `yours` (string, required, nullable): The viewer's own standing decision on the size, if any (one made for them counts). One of: `approve`, `request_changes`, `null`.
  - `size` (string, required): The size's key.
  - `name` (string, required, nullable): The size's display name, set when it was sent; null when none was. Outside reviewers see it too.
  - `width` (number, required): Width of the size.
  - `height` (number, required): Height of the size.
  - `sceneHash` (string, required): A fingerprint (SHA-256) of the size's artwork; it changes when the artwork does.
  - `snapshot` (string, required): The id (SHA-256) of the picture sent with the size.
  - `render` (string, required, nullable): The id of Mestra's own picture of the size, or null when there is none.
  - `status` (string, required): `needs_review`, `approved` or `changes_requested`. One of: `needs_review`, `approved`, `changes_requested`.
  - `changed` (boolean, required): True when the size differs from the round before.
  - `carried` (boolean, required): True when the size is unchanged and its earlier decision carries over.
  - `decision` (object, required, nullable): Null until someone decides; a carried size shows the earlier round's decision.
    - `by` (string, required): Who decided.
    - `outside` (boolean, required): True when an outside reviewer decided.
    - `onBehalfBy` (string, required, nullable): When an owner decided for someone, the owner's name; otherwise null.
    - `at` (string (date-time), required): When the decision was made.
  - `view` (object, optional, nullable): Which render to show by default and what can be exported. Null when renders aren't set up on this server.
    - `default` (string, required): Which picture to show first: `mestra` or `snapshot`. One of: `mestra`, `snapshot`.
    - `reason` (string, required, nullable): Why the snapshot shows by default; null when Mestra's own render does. One of: `lossy`, `fonts`, `checking`, `unchecked`, `fidelity`, `null`.
    - `fidelity` (number, required, nullable): Share of pixels that differ from the snapshot, once scored.
    - `missingFonts` (array of strings, required): Fonts the size needs that are not available.
    - `export` (object, required): Which file types this size can be exported as.
      - `png` (boolean, required): Can be exported as PNG.
      - `jpg` (boolean, required): Can be exported as JPG.
      - `pdf` (boolean, required): Can be exported as PDF.
      - `reason` (string, required, nullable): Why the size can't be exported (or can't be as PDF); null when every format can be.

### 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: “That review no longer exists.” (including another organisation's review and a malformed id).
- 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 complete that review change”, “Couldn't save that change. Try again.” (the change could not be recorded, so it was not made), “could not check token”, “could not check session” or “could not read those review notes”.
- 501: “Review isn't available on this server.”

### Example request

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

## Approve or request changes

`POST /api/v1/reviews/campaigns/{id}/rounds/{n}/decisions`

Permission: Reviews · Write.

Approves sizes of the latest round, or asks for changes to them. The latest decision on a size wins. An empty `sizes` list decides nothing.

When a round has assignees only they can decide (`403 review_not_assigned`), and nobody can decide a round they sent (`403 review_own_round`). An owner can decide for someone else with `onBehalfOf`; the decision is recorded as made on their behalf. The campaign's editors are told about feedback, and they and the owners are told when the round has just become fully approved. Refused while the organisation's account is read-only.

### Parameters

- `id` (string (uuid), required):
- `n` (integer, required):
- `sizes` (one of, required):
- `decision` (string, required):  One of: `approve`, `request_changes`.
- `onBehalfOf` (object, optional, nullable): Owners only. A member's `userId` or a verified outside reviewer's `reviewerId`.
  - `userId` (string (uuid), optional):
  - `reviewerId` (string (uuid), optional):

### Returns

The round.

An object with:

- `approval` (string, required): `all`: every assignee must approve a size; `any`: the first assignee to approve is enough. One of: `all`, `any`.
- `due` (string (date), required, nullable): The round's due date, or null.
- `overdue` (boolean, required): The due day has ended in Sydney and a size isn't approved. Worked out on the server.
- `assignees` (array of objects, required): The people the round is assigned to; empty when it is open to everyone.
  - `name` (string, required): The person's name.
  - `outside` (boolean, required): True for an outside reviewer, false for a member.
  - `you` (boolean, required): True when this is the caller.
  - `waiting` (boolean, required): A size of the round needs review and they have no standing decision on it.
  - `userId` (string (uuid), optional): A member; never sent to an outside reviewer.
  - `reviewerId` (string (uuid), optional): An outside reviewer; never sent to an outside reviewer.
- `number` (integer, required): The round's number, from 1.
- `source` (string, required): Where the round came from: `plugin`, `run`, `applied`, `motion`, `rules`, or `edited` (a hand edit saved in the editor). One of: `plugin`, `run`, `applied`, `motion`, `rules`, `edited`.
- `fromRun` (object, optional, nullable): The run a round was sent from (`id`), for members; null for other rounds and for outside reviewers.
  - `id` (string, optional): The run's id.
- `fromMotion` (object, optional, nullable): The motion version a round was sent from (`jobId`), for members; null for other rounds and for outside reviewers.
  - `jobId` (string, optional): The motion version's id.
- `tool` (string, required): The app the round was sent from: `indesign`, `figma` or `canva` (`mestra` for a motion round).
- `note` (string, required): The note the sender left with the round.
- `author` (object, required): Who sent the round.
  - `name` (string, required): The sender's name.
  - `you` (boolean, required): True when the caller sent it.
- `appliedFrom` (object, required, nullable): Set when the round came from applying an earlier review; otherwise null.
- `createdAt` (string (date-time), required): When the round was sent.
- `latest` (boolean, required): True for the newest round, the only one that can be decided, assigned or given a due date.
- `sizes` (array of objects, required): The round's sizes.
  - `video` (string, required, nullable): A motion size's MP4, an asset id (its SHA-256) served at `/reviews/campaigns/{id}/assets/{asset}`; null for a stills size. `snapshot` is its poster.
  - `notes` (integer, required, nullable): How many notes (issues and distinct flags; element flags once per code) the size's review notes hold. Null when none were sent, and always null for outside reviewers.
  - `yours` (string, required, nullable): The viewer's own standing decision on the size, if any (one made for them counts). One of: `approve`, `request_changes`, `null`.
  - `size` (string, required): The size's key.
  - `name` (string, required, nullable): The size's display name, set when it was sent; null when none was. Outside reviewers see it too.
  - `width` (number, required): Width of the size.
  - `height` (number, required): Height of the size.
  - `sceneHash` (string, required): A fingerprint (SHA-256) of the size's artwork; it changes when the artwork does.
  - `snapshot` (string, required): The id (SHA-256) of the picture sent with the size.
  - `render` (string, required, nullable): The id of Mestra's own picture of the size, or null when there is none.
  - `status` (string, required): `needs_review`, `approved` or `changes_requested`. One of: `needs_review`, `approved`, `changes_requested`.
  - `changed` (boolean, required): True when the size differs from the round before.
  - `carried` (boolean, required): True when the size is unchanged and its earlier decision carries over.
  - `decision` (object, required, nullable): Null until someone decides; a carried size shows the earlier round's decision.
    - `by` (string, required): Who decided.
    - `outside` (boolean, required): True when an outside reviewer decided.
    - `onBehalfBy` (string, required, nullable): When an owner decided for someone, the owner's name; otherwise null.
    - `at` (string (date-time), required): When the decision was made.
  - `view` (object, optional, nullable): Which render to show by default and what can be exported. Null when renders aren't set up on this server.
    - `default` (string, required): Which picture to show first: `mestra` or `snapshot`. One of: `mestra`, `snapshot`.
    - `reason` (string, required, nullable): Why the snapshot shows by default; null when Mestra's own render does. One of: `lossy`, `fonts`, `checking`, `unchecked`, `fidelity`, `null`.
    - `fidelity` (number, required, nullable): Share of pixels that differ from the snapshot, once scored.
    - `missingFonts` (array of strings, required): Fonts the size needs that are not available.
    - `export` (object, required): Which file types this size can be exported as.
      - `png` (boolean, required): Can be exported as PNG.
      - `jpg` (boolean, required): Can be exported as JPG.
      - `pdf` (boolean, required): Can be exported as PDF.
      - `reason` (string, required, nullable): Why the size can't be exported (or can't be as PDF); null when every format can be.

### Errors

- 400 (`review_size`): `review_size` (the round has no such size), or a bad `decision` or `sizes` (with `field`), or `bad JSON: <error>`.
- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`review_own_round`, `review_not_assigned`, `review_on_behalf`, `wrong_key`): `review_own_round` (the person who sent the round can't decide it), `review_not_assigned` (the round has assignees and this isn't one of them), `review_on_behalf` (not an owner, or not someone this review can name, or the round's author), or the role refusal. A key of the wrong kind is `wrong_key`.
- 404: “That review no longer exists.” (including another organisation's review and a malformed id).
- 409 (`review_not_latest`, `api_off`): `review_not_latest`: “This round has been replaced. Open the latest round.” With an API key, `api_off` (“Turn on the API in Developer → API and MCP first.”) when an owner has turned the API off.
- 413: “body exceeds limit (65536 bytes)”
- 500: “could not complete that review change”, “Couldn't save that change. Try again.” (the change could not be recorded, so it was not made), “could not check token”, “could not check session” or “could not read those review notes”.
- 501: “Review isn't available on this server.”

### Example request

```sh
curl --request POST \
  --url https://app.withmestra.com/api/v1/reviews/campaigns/string/rounds/0/decisions \
  --header "Authorization: Bearer $MESTRA_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"sizes":["social-feed"],"decision":"approve"}'
```

## Update a round's assignees

`PUT /api/v1/reviews/campaigns/{id}/rounds/{n}/assignees`

Permission: Reviews · Write.

Sets who the latest round is assigned to and how approval works, replacing the list. Only the latest round can be assigned (`409 review_not_latest`), and never to the person who sent it.

With assignees, only they can decide (everyone else can still view and comment). Under `all` every assignee must approve a size; under `any` the first does; either way an assignee's change request holds the size back. An empty list makes the round open to everyone again. People newly on the list are emailed that a round is waiting. Refused while the organisation's account is read-only.

### Parameters

- `id` (string (uuid), required):
- `n` (integer, required):
- `people` (array of objects, required):
  - `userId` (string (uuid), optional): A member's user id (from `GET .../people`).
  - `reviewerId` (string (uuid), optional): An outside reviewer's id (from `GET .../people`).
- `approval` (string, required):  One of: `all`, `any`.

### Returns

The round.

An object with:

- `approval` (string, required): `all`: every assignee must approve a size; `any`: the first assignee to approve is enough. One of: `all`, `any`.
- `due` (string (date), required, nullable): The round's due date, or null.
- `overdue` (boolean, required): The due day has ended in Sydney and a size isn't approved. Worked out on the server.
- `assignees` (array of objects, required): The people the round is assigned to; empty when it is open to everyone.
  - `name` (string, required): The person's name.
  - `outside` (boolean, required): True for an outside reviewer, false for a member.
  - `you` (boolean, required): True when this is the caller.
  - `waiting` (boolean, required): A size of the round needs review and they have no standing decision on it.
  - `userId` (string (uuid), optional): A member; never sent to an outside reviewer.
  - `reviewerId` (string (uuid), optional): An outside reviewer; never sent to an outside reviewer.
- `number` (integer, required): The round's number, from 1.
- `source` (string, required): Where the round came from: `plugin`, `run`, `applied`, `motion`, `rules`, or `edited` (a hand edit saved in the editor). One of: `plugin`, `run`, `applied`, `motion`, `rules`, `edited`.
- `fromRun` (object, optional, nullable): The run a round was sent from (`id`), for members; null for other rounds and for outside reviewers.
  - `id` (string, optional): The run's id.
- `fromMotion` (object, optional, nullable): The motion version a round was sent from (`jobId`), for members; null for other rounds and for outside reviewers.
  - `jobId` (string, optional): The motion version's id.
- `tool` (string, required): The app the round was sent from: `indesign`, `figma` or `canva` (`mestra` for a motion round).
- `note` (string, required): The note the sender left with the round.
- `author` (object, required): Who sent the round.
  - `name` (string, required): The sender's name.
  - `you` (boolean, required): True when the caller sent it.
- `appliedFrom` (object, required, nullable): Set when the round came from applying an earlier review; otherwise null.
- `createdAt` (string (date-time), required): When the round was sent.
- `latest` (boolean, required): True for the newest round, the only one that can be decided, assigned or given a due date.
- `sizes` (array of objects, required): The round's sizes.
  - `video` (string, required, nullable): A motion size's MP4, an asset id (its SHA-256) served at `/reviews/campaigns/{id}/assets/{asset}`; null for a stills size. `snapshot` is its poster.
  - `notes` (integer, required, nullable): How many notes (issues and distinct flags; element flags once per code) the size's review notes hold. Null when none were sent, and always null for outside reviewers.
  - `yours` (string, required, nullable): The viewer's own standing decision on the size, if any (one made for them counts). One of: `approve`, `request_changes`, `null`.
  - `size` (string, required): The size's key.
  - `name` (string, required, nullable): The size's display name, set when it was sent; null when none was. Outside reviewers see it too.
  - `width` (number, required): Width of the size.
  - `height` (number, required): Height of the size.
  - `sceneHash` (string, required): A fingerprint (SHA-256) of the size's artwork; it changes when the artwork does.
  - `snapshot` (string, required): The id (SHA-256) of the picture sent with the size.
  - `render` (string, required, nullable): The id of Mestra's own picture of the size, or null when there is none.
  - `status` (string, required): `needs_review`, `approved` or `changes_requested`. One of: `needs_review`, `approved`, `changes_requested`.
  - `changed` (boolean, required): True when the size differs from the round before.
  - `carried` (boolean, required): True when the size is unchanged and its earlier decision carries over.
  - `decision` (object, required, nullable): Null until someone decides; a carried size shows the earlier round's decision.
    - `by` (string, required): Who decided.
    - `outside` (boolean, required): True when an outside reviewer decided.
    - `onBehalfBy` (string, required, nullable): When an owner decided for someone, the owner's name; otherwise null.
    - `at` (string (date-time), required): When the decision was made.
  - `view` (object, optional, nullable): Which render to show by default and what can be exported. Null when renders aren't set up on this server.
    - `default` (string, required): Which picture to show first: `mestra` or `snapshot`. One of: `mestra`, `snapshot`.
    - `reason` (string, required, nullable): Why the snapshot shows by default; null when Mestra's own render does. One of: `lossy`, `fonts`, `checking`, `unchecked`, `fidelity`, `null`.
    - `fidelity` (number, required, nullable): Share of pixels that differ from the snapshot, once scored.
    - `missingFonts` (array of strings, required): Fonts the size needs that are not available.
    - `export` (object, required): Which file types this size can be exported as.
      - `png` (boolean, required): Can be exported as PNG.
      - `jpg` (boolean, required): Can be exported as JPG.
      - `pdf` (boolean, required): Can be exported as PDF.
      - `reason` (string, required, nullable): Why the size can't be exported (or can't be as PDF); null when every format can be.

### Errors

- 400 (`review_assign_author`, `review_assignee`): `review_assign_author`, `review_assignee` (someone `people` doesn't list), or a bad `approval` or `people` (with `field`), or `bad JSON: <error>`.
- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`): `403` for a role below the route's minimum (“Your role (\<role>) can't \<action>.”, or “Choose an organisation first.”), or, for an API key without the permission this call needs, code `wrong_key` with “This key needs the \<Area> · \<Read|Write> permission.” (for example “This key needs the Reviews · Write permission.”), or “This key can't do that.” for a call only the Mestra apps make.
- 404: “That review no longer exists.” (including another organisation's review and a malformed id).
- 409 (`review_not_latest`, `api_off`): `review_not_latest`. With an API key, `api_off` (“Turn on the API in Developer → API and MCP first.”) when an owner has turned the API off.
- 413: “body exceeds limit (16384 bytes)”
- 500: “could not complete that review change”, “Couldn't save that change. Try again.” (the change could not be recorded, so it was not made), “could not check token”, “could not check session” or “could not read those review notes”.
- 501: “Review isn't available on this server.”

### Example request

```sh
curl --request PUT \
  --url https://app.withmestra.com/api/v1/reviews/campaigns/string/rounds/0/assignees \
  --header "Authorization: Bearer $MESTRA_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"people":[{"userId":"9b2e7a04-61c5-4f1d-8e3a-2c4d6f8a1b22"}],"approval":"all"}'
```

## Update a round's due date

`PUT /api/v1/reviews/campaigns/{id}/rounds/{n}/due`

Permission: Reviews · Write.

Sets or clears the latest round's due date. Only the latest round's date can change (`409 review_not_latest`). A date runs from today to a year ahead, in Sydney time. Sending the same date again changes nothing. No email goes out when you set it: reminders are sent on their own days. Refused while the organisation's account is read-only.

### Parameters

- `id` (string (uuid), required):
- `n` (integer, required):
- `due` (string (date), required, nullable):

### Returns

The round.

An object with:

- `approval` (string, required): `all`: every assignee must approve a size; `any`: the first assignee to approve is enough. One of: `all`, `any`.
- `due` (string (date), required, nullable): The round's due date, or null.
- `overdue` (boolean, required): The due day has ended in Sydney and a size isn't approved. Worked out on the server.
- `assignees` (array of objects, required): The people the round is assigned to; empty when it is open to everyone.
  - `name` (string, required): The person's name.
  - `outside` (boolean, required): True for an outside reviewer, false for a member.
  - `you` (boolean, required): True when this is the caller.
  - `waiting` (boolean, required): A size of the round needs review and they have no standing decision on it.
  - `userId` (string (uuid), optional): A member; never sent to an outside reviewer.
  - `reviewerId` (string (uuid), optional): An outside reviewer; never sent to an outside reviewer.
- `number` (integer, required): The round's number, from 1.
- `source` (string, required): Where the round came from: `plugin`, `run`, `applied`, `motion`, `rules`, or `edited` (a hand edit saved in the editor). One of: `plugin`, `run`, `applied`, `motion`, `rules`, `edited`.
- `fromRun` (object, optional, nullable): The run a round was sent from (`id`), for members; null for other rounds and for outside reviewers.
  - `id` (string, optional): The run's id.
- `fromMotion` (object, optional, nullable): The motion version a round was sent from (`jobId`), for members; null for other rounds and for outside reviewers.
  - `jobId` (string, optional): The motion version's id.
- `tool` (string, required): The app the round was sent from: `indesign`, `figma` or `canva` (`mestra` for a motion round).
- `note` (string, required): The note the sender left with the round.
- `author` (object, required): Who sent the round.
  - `name` (string, required): The sender's name.
  - `you` (boolean, required): True when the caller sent it.
- `appliedFrom` (object, required, nullable): Set when the round came from applying an earlier review; otherwise null.
- `createdAt` (string (date-time), required): When the round was sent.
- `latest` (boolean, required): True for the newest round, the only one that can be decided, assigned or given a due date.
- `sizes` (array of objects, required): The round's sizes.
  - `video` (string, required, nullable): A motion size's MP4, an asset id (its SHA-256) served at `/reviews/campaigns/{id}/assets/{asset}`; null for a stills size. `snapshot` is its poster.
  - `notes` (integer, required, nullable): How many notes (issues and distinct flags; element flags once per code) the size's review notes hold. Null when none were sent, and always null for outside reviewers.
  - `yours` (string, required, nullable): The viewer's own standing decision on the size, if any (one made for them counts). One of: `approve`, `request_changes`, `null`.
  - `size` (string, required): The size's key.
  - `name` (string, required, nullable): The size's display name, set when it was sent; null when none was. Outside reviewers see it too.
  - `width` (number, required): Width of the size.
  - `height` (number, required): Height of the size.
  - `sceneHash` (string, required): A fingerprint (SHA-256) of the size's artwork; it changes when the artwork does.
  - `snapshot` (string, required): The id (SHA-256) of the picture sent with the size.
  - `render` (string, required, nullable): The id of Mestra's own picture of the size, or null when there is none.
  - `status` (string, required): `needs_review`, `approved` or `changes_requested`. One of: `needs_review`, `approved`, `changes_requested`.
  - `changed` (boolean, required): True when the size differs from the round before.
  - `carried` (boolean, required): True when the size is unchanged and its earlier decision carries over.
  - `decision` (object, required, nullable): Null until someone decides; a carried size shows the earlier round's decision.
    - `by` (string, required): Who decided.
    - `outside` (boolean, required): True when an outside reviewer decided.
    - `onBehalfBy` (string, required, nullable): When an owner decided for someone, the owner's name; otherwise null.
    - `at` (string (date-time), required): When the decision was made.
  - `view` (object, optional, nullable): Which render to show by default and what can be exported. Null when renders aren't set up on this server.
    - `default` (string, required): Which picture to show first: `mestra` or `snapshot`. One of: `mestra`, `snapshot`.
    - `reason` (string, required, nullable): Why the snapshot shows by default; null when Mestra's own render does. One of: `lossy`, `fonts`, `checking`, `unchecked`, `fidelity`, `null`.
    - `fidelity` (number, required, nullable): Share of pixels that differ from the snapshot, once scored.
    - `missingFonts` (array of strings, required): Fonts the size needs that are not available.
    - `export` (object, required): Which file types this size can be exported as.
      - `png` (boolean, required): Can be exported as PNG.
      - `jpg` (boolean, required): Can be exported as JPG.
      - `pdf` (boolean, required): Can be exported as PDF.
      - `reason` (string, required, nullable): Why the size can't be exported (or can't be as PDF); null when every format can be.

### Errors

- 400 (`review_due_past`, `review_due_far`): A `due` that is missing or isn't a date like 2026-10-09 (with `field`), `review_due_past` ("Pick today or a later date.") or `review_due_far` ("Pick a date within the next year."), or `bad JSON: <error>`.
- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`): `403` for a role below the route's minimum (“Your role (\<role>) can't \<action>.”, or “Choose an organisation first.”), or, for an API key without the permission this call needs, code `wrong_key` with “This key needs the \<Area> · \<Read|Write> permission.” (for example “This key needs the Reviews · Write permission.”), or “This key can't do that.” for a call only the Mestra apps make.
- 404: “That review no longer exists.” (including another organisation's review and a malformed id).
- 409 (`review_not_latest`, `api_off`): `review_not_latest`. With an API key, `api_off` (“Turn on the API in Developer → API and MCP first.”) when an owner has turned the API off.
- 413: “body exceeds limit (1024 bytes)”
- 500: “could not complete that review change”, “Couldn't save that change. Try again.” (the change could not be recorded, so it was not made), “could not check token”, “could not check session” or “could not read those review notes”.
- 501: “Review isn't available on this server.”

### Example request

```sh
curl --request PUT \
  --url https://app.withmestra.com/api/v1/reviews/campaigns/string/rounds/0/due \
  --header "Authorization: Bearer $MESTRA_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"due":"2027-09-10"}'
```

## List all people who can be assigned

`GET /api/v1/reviews/campaigns/{id}/people`

Permission: Reviews · Read.

Returns the people a round of this review can be assigned to: members with a mailbox and verified outside reviewers on live links. The person who sent the latest round is left out.

### Parameters

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

### Returns

The people.

An object with:

- `people` (array of objects, required):
  - `name` (string, required):
  - `outside` (boolean, required):
  - `userId` (string (uuid), optional): A member.
  - `reviewerId` (string (uuid), optional): An outside reviewer.

### 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: “That review no longer exists.” (including another organisation's review and a malformed id).
- 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 complete that review change”, “Couldn't save that change. Try again.” (the change could not be recorded, so it was not made), “could not check token”, “could not check session” or “could not read those review notes”.
- 501: “Review isn't available on this server.”

### Example request

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

## List all comments

`GET /api/v1/reviews/campaigns/{id}/comments`

Permission: Reviews · Read.

Returns every comment on the review, oldest first. Comment text comes from people: it is returned exactly as written, so escape it before you show it.

### Parameters

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

### Returns

The comments.

An object with:

- `comments` (array of objects, required):
  - `at` (number, required, nullable): Seconds into a motion size's video the comment is about; null for a stills size and for replies.
  - `pinLabel` (string, required, nullable): What the pinned element is called (for example `Headline`), for a pin on a motion size; null otherwise.
  - `id` (string (uuid), required): The comment's id.
  - `round` (integer, required): The round the comment is on.
  - `size` (string, required, nullable): The size the comment is on, or null for a comment on the whole round.
  - `parentId` (string (uuid), required, nullable): The comment this replies to, or null for a first comment.
  - `author` (object, required): Who wrote it.
    - `name` (string, required): The author's name.
    - `outside` (boolean, required): True for an outside reviewer.
    - `you` (boolean, required): True when the caller wrote it.
  - `body` (string, required): Untrusted text, stored as given. Escape it when showing it.
  - `pin` (object, required, nullable): Where on the size the comment points, or null.
    - `x` (number, required): Horizontal position, in the size's own pixels.
    - `y` (number, required): Vertical position, in the size's own pixels.
  - `suggested` (boolean, required): True when the comment suggests a change rather than only noting a point.
  - `mentions` (array of objects, required): The people the comment mentions.
    - `userId` (string (uuid), optional): A member's user id.
    - `reviewerId` (string (uuid), optional): An outside reviewer's id.
    - `name` (string, optional): The person's name.
  - `resolved` (object, required, nullable): Set when the comment was resolved; null while it is open.
    - `by` (string, required): Who resolved it.
    - `at` (string (date-time), required): When.
  - `createdAt` (string (date-time), required): When the comment was written.

### 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: “That review no longer exists.” (including another organisation's review and a malformed id).
- 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 complete that review change”, “Couldn't save that change. Try again.” (the change could not be recorded, so it was not made), “could not check token”, “could not check session” or “could not read those review notes”.
- 501: “Review isn't available on this server.”

### Example request

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

## Add a comment

`POST /api/v1/reviews/campaigns/{id}/comments`

Permission: Reviews · Write.

Comments on a round, on one size, or on a point of a size, or replies to a comment. The text is saved as given (trimmed). The campaign's editors are sent the feedback in a batched email, and each person mentioned is emailed at once. A mention must name a member of the organisation, or an outside reviewer of this review whose link is live. Refused while the organisation's account is read-only.

### Parameters

- `id` (string (uuid), required):
- `round` (integer, required):
- `size` (string, optional, nullable): Absent for a comment on the whole round. A pin needs it.
- `parentId` (string (uuid), optional, nullable): A top-level comment of this review; a reply has no pin.
- `body` (string, required):
- `pin` (object, optional, nullable): A point inside the size, in its own pixels.
  - `x` (number, required):
  - `y` (number, required):
- `at` (number, optional, nullable): Seconds into the video, for a top-level comment on a motion size. Refused on a reply, on a stills size, and outside 0 to 60. A pin on a motion size needs it.
- `elementId` (string, optional): The scene element under a pin on a motion size, required there and refused anywhere else. It must be on that round's design; the comment's `pinLabel` is derived from it.
- `suggested` (boolean, optional):
- `mentions` (object, optional): At most 20 people in all.
  - `userIds` (array of strings, optional):
  - `reviewerIds` (array of strings, optional):

### Returns

The comment.

An object with:

- `at` (number, required, nullable): Seconds into a motion size's video the comment is about; null for a stills size and for replies.
- `pinLabel` (string, required, nullable): What the pinned element is called (for example `Headline`), for a pin on a motion size; null otherwise.
- `id` (string (uuid), required): The comment's id.
- `round` (integer, required): The round the comment is on.
- `size` (string, required, nullable): The size the comment is on, or null for a comment on the whole round.
- `parentId` (string (uuid), required, nullable): The comment this replies to, or null for a first comment.
- `author` (object, required): Who wrote it.
  - `name` (string, required): The author's name.
  - `outside` (boolean, required): True for an outside reviewer.
  - `you` (boolean, required): True when the caller wrote it.
- `body` (string, required): Untrusted text, stored as given. Escape it when showing it.
- `pin` (object, required, nullable): Where on the size the comment points, or null.
  - `x` (number, required): Horizontal position, in the size's own pixels.
  - `y` (number, required): Vertical position, in the size's own pixels.
- `suggested` (boolean, required): True when the comment suggests a change rather than only noting a point.
- `mentions` (array of objects, required): The people the comment mentions.
  - `userId` (string (uuid), optional): A member's user id.
  - `reviewerId` (string (uuid), optional): An outside reviewer's id.
  - `name` (string, optional): The person's name.
- `resolved` (object, required, nullable): Set when the comment was resolved; null while it is open.
  - `by` (string, required): Who resolved it.
  - `at` (string (date-time), required): When.
- `createdAt` (string (date-time), required): When the comment was written.

### Errors

- 400: A refusal naming its `field`: `body`, `round`, `size`, `pin`, `parentId` or `mentions`; or `bad JSON: <error>`.
- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`): `403` for a role below the route's minimum (“Your role (\<role>) can't \<action>.”, or “Choose an organisation first.”), or, for an API key without the permission this call needs, code `wrong_key` with “This key needs the \<Area> · \<Read|Write> permission.” (for example “This key needs the Reviews · Write permission.”), or “This key can't do that.” for a call only the Mestra apps make.
- 404: “That review no longer exists.” (including another organisation's review and a malformed id).
- 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.
- 413: “body exceeds limit (65536 bytes)”
- 500: “could not complete that review change”, “Couldn't save that change. Try again.” (the change could not be recorded, so it was not made), “could not check token”, “could not check session” or “could not read those review notes”.
- 501: “Review isn't available on this server.”

### Example request

```sh
curl --request POST \
  --url https://app.withmestra.com/api/v1/reviews/campaigns/string/comments \
  --header "Authorization: Bearer $MESTRA_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"round":2,"size":"social-feed","body":"Can the headline sit a little higher?","pin":{"x":452,"y":196}}'
```

## Resolve a comment

`POST /api/v1/reviews/campaigns/{id}/comments/{comment}/resolve`

Permission: Reviews · Write.

Marks a comment resolved, or reopens it with `resolved: false`. A comment that isn't in this review is a `404`. Refused while the organisation's account is read-only.

### Parameters

- `id` (string (uuid), required):
- `comment` (string (uuid), required):
- `resolved` (boolean, required): true resolves; false reopens. Required: a request without it is a 400.

### Returns

The comment.

An object with:

- `at` (number, required, nullable): Seconds into a motion size's video the comment is about; null for a stills size and for replies.
- `pinLabel` (string, required, nullable): What the pinned element is called (for example `Headline`), for a pin on a motion size; null otherwise.
- `id` (string (uuid), required): The comment's id.
- `round` (integer, required): The round the comment is on.
- `size` (string, required, nullable): The size the comment is on, or null for a comment on the whole round.
- `parentId` (string (uuid), required, nullable): The comment this replies to, or null for a first comment.
- `author` (object, required): Who wrote it.
  - `name` (string, required): The author's name.
  - `outside` (boolean, required): True for an outside reviewer.
  - `you` (boolean, required): True when the caller wrote it.
- `body` (string, required): Untrusted text, stored as given. Escape it when showing it.
- `pin` (object, required, nullable): Where on the size the comment points, or null.
  - `x` (number, required): Horizontal position, in the size's own pixels.
  - `y` (number, required): Vertical position, in the size's own pixels.
- `suggested` (boolean, required): True when the comment suggests a change rather than only noting a point.
- `mentions` (array of objects, required): The people the comment mentions.
  - `userId` (string (uuid), optional): A member's user id.
  - `reviewerId` (string (uuid), optional): An outside reviewer's id.
  - `name` (string, optional): The person's name.
- `resolved` (object, required, nullable): Set when the comment was resolved; null while it is open.
  - `by` (string, required): Who resolved it.
  - `at` (string (date-time), required): When.
- `createdAt` (string (date-time), required): When the comment was written.

### Errors

- 400: `resolved` missing or not true or false (with `field`), or `bad JSON: <error>`.
- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`): `403` for a role below the route's minimum (“Your role (\<role>) can't \<action>.”, or “Choose an organisation first.”), or, for an API key without the permission this call needs, code `wrong_key` with “This key needs the \<Area> · \<Read|Write> permission.” (for example “This key needs the Reviews · Write permission.”), or “This key can't do that.” for a call only the Mestra apps make.
- 404: “That review no longer exists.” (including another organisation's review and a malformed id).
- 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 complete that review change”, “Couldn't save that change. Try again.” (the change could not be recorded, so it was not made), “could not check token”, “could not check session” or “could not read those review notes”.
- 501: “Review isn't available on this server.”

### Example request

```sh
curl --request POST \
  --url https://app.withmestra.com/api/v1/reviews/campaigns/string/comments/string/resolve \
  --header "Authorization: Bearer $MESTRA_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"resolved":true}'
```

## Start an export

`POST /api/v1/reviews/campaigns/{id}/rounds/{n}/exports`

Permission: Reviews · Write.

Starts an export of a round's sizes as PNG, JPG or PDF. It runs in the background: poll Retrieve an export, then download the zip or a single file. Files are kept for 7 days. Exports count no sizes, and one export runs per organisation at a time (`409 export_busy`).

`sizes` is `"all"` (the default) or a list of the round's sizes; an export has 100 sizes at most (`400 export_too_many_sizes`). A size that can't be exported yet (still being checked, snapshot only, missing fonts, a font that can't go in a PDF, too many pixels, or an image that is too big) is left out and named in `skipped` with its reason. A PDF is always scale 1. Refused while the organisation's account is read-only; `501` when exports aren't available.

### Parameters

- `id` (string (uuid), required):
- `n` (integer, required):
- `format` (string, required):  One of: `png`, `jpg`, `pdf`.
- `scale` (number, optional):
- `sizes` (one of, optional): `all`, or a non-empty list of the round's sizes. Leave it out for all; `null` is refused.

### Returns

Queued.

An object with:

- `export` (object, required):
  - `id` (string (uuid), required): The export's id.
  - `round` (integer, required): The round exported.
  - `format` (string, required): The file type: `png`, `jpg` or `pdf`. One of: `png`, `jpg`, `pdf`.
  - `scale` (number, required): The scale the files were made at.
  - `status` (string, required): `queued`, `running`, `done` or `failed`. One of: `queued`, `running`, `done`, `failed`.
  - `by` (object, required): Who started the export.
    - `name` (string, required): The name of the person who started the export.
  - `createdAt` (string (date-time), required): When the export was requested.
  - `finishedAt` (string (date-time), required, nullable): When it finished; null while it runs.
  - `expiresAt` (string (date-time), required): When its files are deleted (7 days after it was made).
  - `skipped` (object, required): Sizes left out, each with its reason (`checking`, `unchecked`, `fidelity`, `fonts`, `lossy`, `pdf-licence`, `too-large` or an asset reason).
  - `files` (array of objects, required): One entry for each size in the export.
    - `size` (string, required): The size's key.
    - `status` (string, required): `queued`, `done` or `failed`. One of: `queued`, `done`, `failed`.
    - `bytes` (integer, required, nullable): The file's size in bytes once done; otherwise null.
    - `reason` (string, required, nullable): Why the file failed; otherwise null.

### Errors

- 400 (`review_size`, `export_too_many_sizes`, `export_none`): A bad `format`, `scale` or `sizes` (with `field`); `review_size` (the round has no such size); `export_too_many_sizes` (more than 100 sizes); or `export_none` (none of the sizes can be exported yet), with `skipped` naming each size's reason.
- 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: “That review no longer exists.” (including another organisation's review and a malformed id).
- 409 (`export_busy`, `api_off`): `export_busy`: “Your organisation already has an export running. Try again when it finishes.” With an API key, `api_off` (“Turn on the API in Developer → API and MCP first.”) when an owner has turned the API off.
- 413: “body exceeds limit (16384 bytes)”
- 500: “could not complete that review change”, “Couldn't save that change. Try again.” (the change could not be recorded, so it was not made), “could not check token”, “could not check session” or “could not read those review notes”.
- 501: “Review isn't available on this server.”, or “Export isn't set up on this server.” (no render service).

### Example request

```sh
curl --request POST \
  --url https://app.withmestra.com/api/v1/reviews/campaigns/string/rounds/0/exports \
  --header "Authorization: Bearer $MESTRA_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"format":"png","scale":1,"sizes":"all"}'
```

## List all exports

`GET /api/v1/reviews/campaigns/{id}/exports`

Permission: Reviews · Read.

Returns the review's exports that haven't expired, newest first, 20 at most.

### Parameters

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

### Returns

The exports.

An object with:

- `exports` (array of objects, required):
  - `id` (string (uuid), required): The export's id.
  - `round` (integer, required): The round exported.
  - `format` (string, required): The file type: `png`, `jpg` or `pdf`. One of: `png`, `jpg`, `pdf`.
  - `scale` (number, required): The scale the files were made at.
  - `status` (string, required): `queued`, `running`, `done` or `failed`. One of: `queued`, `running`, `done`, `failed`.
  - `by` (object, required): Who started the export.
    - `name` (string, required): The name of the person who started the export.
  - `createdAt` (string (date-time), required): When the export was requested.
  - `finishedAt` (string (date-time), required, nullable): When it finished; null while it runs.
  - `expiresAt` (string (date-time), required): When its files are deleted (7 days after it was made).
  - `skipped` (object, required): Sizes left out, each with its reason (`checking`, `unchecked`, `fidelity`, `fonts`, `lossy`, `pdf-licence`, `too-large` or an asset reason).
  - `files` (array of objects, required): One entry for each size in the export.
    - `size` (string, required): The size's key.
    - `status` (string, required): `queued`, `done` or `failed`. One of: `queued`, `done`, `failed`.
    - `bytes` (integer, required, nullable): The file's size in bytes once done; otherwise null.
    - `reason` (string, required, nullable): Why the file failed; otherwise null.

### 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: “That review no longer exists.” (including another organisation's review and a malformed id).
- 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 complete that review change”, “Couldn't save that change. Try again.” (the change could not be recorded, so it was not made), “could not check token”, “could not check session” or “could not read those review notes”.
- 501: “Review isn't available on this server.”, or “Export isn't set up on this server.” (no render service).

### Example request

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

## Retrieve an export

`GET /api/v1/reviews/campaigns/{id}/exports/{export}`

Permission: Reviews · Read.

Returns the export's progress and the status of each size. An export of another organisation, an expired one and a malformed id are all `404`.

### Parameters

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

### Returns

The export.

An object with:

- `id` (string (uuid), required): The export's id.
- `round` (integer, required): The round exported.
- `format` (string, required): The file type: `png`, `jpg` or `pdf`. One of: `png`, `jpg`, `pdf`.
- `scale` (number, required): The scale the files were made at.
- `status` (string, required): `queued`, `running`, `done` or `failed`. One of: `queued`, `running`, `done`, `failed`.
- `by` (object, required): Who started the export.
  - `name` (string, required): The name of the person who started the export.
- `createdAt` (string (date-time), required): When the export was requested.
- `finishedAt` (string (date-time), required, nullable): When it finished; null while it runs.
- `expiresAt` (string (date-time), required): When its files are deleted (7 days after it was made).
- `skipped` (object, required): Sizes left out, each with its reason (`checking`, `unchecked`, `fidelity`, `fonts`, `lossy`, `pdf-licence`, `too-large` or an asset reason).
- `files` (array of objects, required): One entry for each size in the export.
  - `size` (string, required): The size's key.
  - `status` (string, required): `queued`, `done` or `failed`. One of: `queued`, `done`, `failed`.
  - `bytes` (integer, required, nullable): The file's size in bytes once done; otherwise null.
  - `reason` (string, required, nullable): Why the file failed; otherwise null.

### 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: “That review no longer exists.” (including another organisation's review and a malformed id).
- 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 complete that review change”, “Couldn't save that change. Try again.” (the change could not be recorded, so it was not made), “could not check token”, “could not check session” or “could not read those review notes”.
- 501: “Review isn't available on this server.”, or “Export isn't set up on this server.” (no render service).

### Example request

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

## Download an export

`GET /api/v1/reviews/campaigns/{id}/exports/{export}/download`

Permission: Reviews · Read.

Downloads the export's finished files as one zip, with a file per finished size, named `<campaign>-round-<n>-<format>.zip`. The zip is stored, not compressed, and streamed: its length isn't known up front, and a failure part-way ends the connection rather than finishing a broken file.

### Parameters

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

### Returns

The zip.

### 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: “That review no longer exists.” (including another organisation's review and a malformed id).
- 409 (`export_not_ready`, `api_off`): `export_not_ready`: “This export is still being made. Try again in a minute.” (queued or running) or “This export failed, so there is nothing to download. Make a new one.” (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.
- 500: “could not complete that review change”, “Couldn't save that change. Try again.” (the change could not be recorded, so it was not made), “could not check token”, “could not check session” or “could not read those review notes”.
- 501: “Review isn't available on this server.”, or “Export isn't set up on this server.” (no render service).

### Example request

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

## Download a file from an export

`GET /api/v1/reviews/campaigns/{id}/exports/{export}/files/{size}`

Permission: Reviews · Read.

Downloads one finished file of the export as an attachment. A size that isn't finished, or isn't in the export, is a `404`.

### Parameters

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

### Returns

The file.

### 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: “That review no longer exists.” (including another organisation's review and a malformed id).
- 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 complete that review change”, “Couldn't save that change. Try again.” (the change could not be recorded, so it was not made), “could not check token”, “could not check session” or “could not read those review notes”.
- 501: “Review isn't available on this server.”, or “Export isn't set up on this server.” (no render service).

### Example request

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