Skip to content

API reference

Reviews

The Review object

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

Attributes

  • kindstringRequired

    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.

    Possible valuesstillsmotion

  • sourceIdstring (uuid)RequiredNullable

    A motion review’s stills review, for members; null for a stills review and once the stills review is deleted.

  • approvalstringRequired

    The latest round’s rule.

    Possible valuesallany

  • duestring (date)RequiredNullable

    The latest round’s due date, or null.

  • overduebooleanRequired

    The due day has ended in Sydney and a size isn’t approved. Worked out on the server.

  • assigneesarray of objectsRequired

    The latest round’s current assignees.

    Show child attributesHide child attributes
    • namestringRequired

      The person’s name.

    • outsidebooleanRequired

      True for an outside reviewer, false for a member.

    • youbooleanRequired

      True when this is the caller.

    • waitingbooleanRequired

      A size of the round needs review and they have no standing decision on it.

    • userIdstring (uuid)Optional

      A member; never sent to an outside reviewer.

    • reviewerIdstring (uuid)Optional

      An outside reviewer; never sent to an outside reviewer.

  • assignedToYoubooleanRequired

    True when the latest round is assigned and the caller is one of the assignees.

  • overrideobjectRequiredNullable

    “Approved by on behalf of ”: the latest standing approvals one owner or editor made for others. Null unless the status is approved and the approvals still stand.

    Show child attributesHide child attributes
    • bystringRequired

      Who approved on behalf of others.

    • forarray of stringsRequired

      Whose approvals were made on their behalf.

    • atstring (date-time)Required

      When.

  • canMovebooleanRequired

    An owner or editor who didn’t send the latest round.

  • archivedAtstring (date-time)RequiredNullable

    When the review was archived; null for a current review. An archived review is left out of the default list.

  • idstring (uuid)Required

    The review’s id.

  • campaignKeystringRequired

    The campaign under review.

  • sitestringRequired

    The brand code under review.

  • namestringRequired

    The campaign’s name now; its key when the setup no longer has it.

  • brandNamestringRequired

    The brand’s name now; its code when the setup no longer has it.

  • statusstringRequired

    empty: nothing sent yet; needs_review; changes_requested; approved.

    Possible valuesemptyneeds_reviewchanges_requestedapproved

  • latestRoundintegerRequired

    The number of the latest round; 0 before the first.

  • progressobjectRequired

    How the latest round’s sizes stand.

    Show child attributesHide child attributes
    • sizesintegerRequired

      Sizes in the latest round.

    • approvedintegerRequired

      Sizes approved.

    • changesRequestedintegerRequired

      Sizes with changes requested.

    • needsReviewintegerRequired

      Sizes still waiting for a decision.

  • createdAtstring (date-time)Required

    When the review was started.

  • lastActivityAtstring (date-time)Required

    When something last happened in the review.

  • expiresAtstring (date-time)RequiredNullable

    The last activity plus the library’s retention; null under Keep everything.

Start a review

PermissionReviews · 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.

Body parameters

  • campaignKeystringRequired
  • sitestringRequired

    A brand’s code; it must be one of the campaign’s.

Returns

The existing review.

An object with:

  • kindstringRequired

    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.

    Possible valuesstillsmotion

  • sourceIdstring (uuid)RequiredNullable

    A motion review’s stills review, for members; null for a stills review and once the stills review is deleted.

  • approvalstringRequired

    The latest round’s rule.

    Possible valuesallany

  • duestring (date)RequiredNullable

    The latest round’s due date, or null.

  • overduebooleanRequired

    The due day has ended in Sydney and a size isn’t approved. Worked out on the server.

  • assigneesarray of objectsRequired

    The latest round’s current assignees.

    Show child attributesHide child attributes
    • namestringRequired

      The person’s name.

    • outsidebooleanRequired

      True for an outside reviewer, false for a member.

    • youbooleanRequired

      True when this is the caller.

    • waitingbooleanRequired

      A size of the round needs review and they have no standing decision on it.

    • userIdstring (uuid)Optional

      A member; never sent to an outside reviewer.

    • reviewerIdstring (uuid)Optional

      An outside reviewer; never sent to an outside reviewer.

  • assignedToYoubooleanRequired

    True when the latest round is assigned and the caller is one of the assignees.

  • overrideobjectRequiredNullable

    “Approved by on behalf of ”: the latest standing approvals one owner or editor made for others. Null unless the status is approved and the approvals still stand.

    Show child attributesHide child attributes
    • bystringRequired

      Who approved on behalf of others.

    • forarray of stringsRequired

      Whose approvals were made on their behalf.

    • atstring (date-time)Required

      When.

  • canMovebooleanRequired

    An owner or editor who didn’t send the latest round.

  • archivedAtstring (date-time)RequiredNullable

    When the review was archived; null for a current review. An archived review is left out of the default list.

  • idstring (uuid)Required

    The review’s id.

  • campaignKeystringRequired

    The campaign under review.

  • sitestringRequired

    The brand code under review.

  • namestringRequired

    The campaign’s name now; its key when the setup no longer has it.

  • brandNamestringRequired

    The brand’s name now; its code when the setup no longer has it.

  • statusstringRequired

    empty: nothing sent yet; needs_review; changes_requested; approved.

    Possible valuesemptyneeds_reviewchanges_requestedapproved

  • latestRoundintegerRequired

    The number of the latest round; 0 before the first.

  • progressobjectRequired

    How the latest round’s sizes stand.

    Show child attributesHide child attributes
    • sizesintegerRequired

      Sizes in the latest round.

    • approvedintegerRequired

      Sizes approved.

    • changesRequestedintegerRequired

      Sizes with changes requested.

    • needsReviewintegerRequired

      Sizes still waiting for a decision.

  • createdAtstring (date-time)Required

    When the review was started.

  • lastActivityAtstring (date-time)Required

    When something last happened in the review.

  • expiresAtstring (date-time)RequiredNullable

    The last activity plus the library’s retention; null under Keep everything.

  • roundsarray of objectsRequired

    Every round of the review, oldest first.

    Show child attributesHide child attributes
    • numberintegerRequired

      The round’s number, from 1.

    • sourcestringRequired

      Where the round came from: plugin, applied, run, motion, rules, or edited (a hand edit saved in the editor).

      Possible valuespluginappliedrunmotionrulesedited

    • fromRunobjectOptionalNullable

      The run a round was sent from (id), for members; null for other rounds and for outside reviewers.

      Show child attributesHide child attributes
      • idstringOptional

        The run’s id.

    • fromMotionobjectOptionalNullable

      The motion version a round was sent from (jobId), for members; null for other rounds and for outside reviewers.

      Show child attributesHide child attributes
      • jobIdstringOptional

        The motion version’s id.

    • toolstringRequired

      The app the round was sent from: indesign, figma or canva (mestra for a motion round).

    • notestringRequired

      The note the sender left with the round.

    • authorobjectRequired

      Who sent the round.

      Show child attributesHide child attributes
      • namestringRequired

        The sender’s name.

      • youbooleanRequired

        True when the caller sent it.

    • createdAtstring (date-time)Required

      When the round was sent.

    • sizesintegerRequired

      How many sizes the round holds.

    • changedintegerRequired

      How many of its sizes changed since the round before.

  • youobjectRequired

    What the caller may do in this review.

    Show child attributesHide child attributes
    • canCommentbooleanRequired

      May comment.

    • canDecidebooleanRequired

      False when the latest round has assignees and you aren’t one.

    • canSendbooleanRequired

      May send a new round.

    • canResolvebooleanRequired

      May resolve comments.

    • canManageLinksbooleanRequired

      May manage links for outside reviewers.

    • canDownloadbooleanRequired

      May download exports.

    • canArchivebooleanRequired

      May archive and unarchive the review (editors and owners, members only).

    • canDeletebooleanRequired

      May delete the review (owners, members only).

Errors

StatusCodeMeaning
400

bad JSON: <error> or bad JSON: trailing data after the request object.

401invalid_token

The key is missing, unknown, revoked or expired (code invalid_token). Send it as Authorization: Bearer <key>.

403wrong_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.”

409review_dont_keepapi_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.”

Retrieve a review

PermissionReviews · 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.

Path parameters

  • idstring (uuid)Required

Returns

The review.

An object with:

  • kindstringRequired

    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.

    Possible valuesstillsmotion

  • sourceIdstring (uuid)RequiredNullable

    A motion review’s stills review, for members; null for a stills review and once the stills review is deleted.

  • approvalstringRequired

    The latest round’s rule.

    Possible valuesallany

  • duestring (date)RequiredNullable

    The latest round’s due date, or null.

  • overduebooleanRequired

    The due day has ended in Sydney and a size isn’t approved. Worked out on the server.

  • assigneesarray of objectsRequired

    The latest round’s current assignees.

    Show child attributesHide child attributes
    • namestringRequired

      The person’s name.

    • outsidebooleanRequired

      True for an outside reviewer, false for a member.

    • youbooleanRequired

      True when this is the caller.

    • waitingbooleanRequired

      A size of the round needs review and they have no standing decision on it.

    • userIdstring (uuid)Optional

      A member; never sent to an outside reviewer.

    • reviewerIdstring (uuid)Optional

      An outside reviewer; never sent to an outside reviewer.

  • assignedToYoubooleanRequired

    True when the latest round is assigned and the caller is one of the assignees.

  • overrideobjectRequiredNullable

    “Approved by on behalf of ”: the latest standing approvals one owner or editor made for others. Null unless the status is approved and the approvals still stand.

    Show child attributesHide child attributes
    • bystringRequired

      Who approved on behalf of others.

    • forarray of stringsRequired

      Whose approvals were made on their behalf.

    • atstring (date-time)Required

      When.

  • canMovebooleanRequired

    An owner or editor who didn’t send the latest round.

  • archivedAtstring (date-time)RequiredNullable

    When the review was archived; null for a current review. An archived review is left out of the default list.

  • idstring (uuid)Required

    The review’s id.

  • campaignKeystringRequired

    The campaign under review.

  • sitestringRequired

    The brand code under review.

  • namestringRequired

    The campaign’s name now; its key when the setup no longer has it.

  • brandNamestringRequired

    The brand’s name now; its code when the setup no longer has it.

  • statusstringRequired

    empty: nothing sent yet; needs_review; changes_requested; approved.

    Possible valuesemptyneeds_reviewchanges_requestedapproved

  • latestRoundintegerRequired

    The number of the latest round; 0 before the first.

  • progressobjectRequired

    How the latest round’s sizes stand.

    Show child attributesHide child attributes
    • sizesintegerRequired

      Sizes in the latest round.

    • approvedintegerRequired

      Sizes approved.

    • changesRequestedintegerRequired

      Sizes with changes requested.

    • needsReviewintegerRequired

      Sizes still waiting for a decision.

  • createdAtstring (date-time)Required

    When the review was started.

  • lastActivityAtstring (date-time)Required

    When something last happened in the review.

  • expiresAtstring (date-time)RequiredNullable

    The last activity plus the library’s retention; null under Keep everything.

  • roundsarray of objectsRequired

    Every round of the review, oldest first.

    Show child attributesHide child attributes
    • numberintegerRequired

      The round’s number, from 1.

    • sourcestringRequired

      Where the round came from: plugin, applied, run, motion, rules, or edited (a hand edit saved in the editor).

      Possible valuespluginappliedrunmotionrulesedited

    • fromRunobjectOptionalNullable

      The run a round was sent from (id), for members; null for other rounds and for outside reviewers.

      Show child attributesHide child attributes
      • idstringOptional

        The run’s id.

    • fromMotionobjectOptionalNullable

      The motion version a round was sent from (jobId), for members; null for other rounds and for outside reviewers.

      Show child attributesHide child attributes
      • jobIdstringOptional

        The motion version’s id.

    • toolstringRequired

      The app the round was sent from: indesign, figma or canva (mestra for a motion round).

    • notestringRequired

      The note the sender left with the round.

    • authorobjectRequired

      Who sent the round.

      Show child attributesHide child attributes
      • namestringRequired

        The sender’s name.

      • youbooleanRequired

        True when the caller sent it.

    • createdAtstring (date-time)Required

      When the round was sent.

    • sizesintegerRequired

      How many sizes the round holds.

    • changedintegerRequired

      How many of its sizes changed since the round before.

  • youobjectRequired

    What the caller may do in this review.

    Show child attributesHide child attributes
    • canCommentbooleanRequired

      May comment.

    • canDecidebooleanRequired

      False when the latest round has assignees and you aren’t one.

    • canSendbooleanRequired

      May send a new round.

    • canResolvebooleanRequired

      May resolve comments.

    • canManageLinksbooleanRequired

      May manage links for outside reviewers.

    • canDownloadbooleanRequired

      May download exports.

    • canArchivebooleanRequired

      May archive and unarchive the review (editors and owners, members only).

    • canDeletebooleanRequired

      May delete the review (owners, members only).

Errors

StatusCodeMeaning
401invalid_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).

409api_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.”

List all reviews

PermissionReviews · Read

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

Query parameters

  • archivedstringOptional

    1 lists the archived reviews instead of the current ones. Any other value is ignored.

    Possible values1

Returns

The reviews, without their rounds.

An object with:

  • campaignsarray of objectsRequired
    Show child attributesHide child attributes
    • kindstringRequired

      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.

      Possible valuesstillsmotion

    • sourceIdstring (uuid)RequiredNullable

      A motion review’s stills review, for members; null for a stills review and once the stills review is deleted.

    • approvalstringRequired

      The latest round’s rule.

      Possible valuesallany

    • duestring (date)RequiredNullable

      The latest round’s due date, or null.

    • overduebooleanRequired

      The due day has ended in Sydney and a size isn’t approved. Worked out on the server.

    • assigneesarray of objectsRequired

      The latest round’s current assignees.

      Show child attributesHide child attributes
      • namestringRequired

        The person’s name.

      • outsidebooleanRequired

        True for an outside reviewer, false for a member.

      • youbooleanRequired

        True when this is the caller.

      • waitingbooleanRequired

        A size of the round needs review and they have no standing decision on it.

      • userIdstring (uuid)Optional

        A member; never sent to an outside reviewer.

      • reviewerIdstring (uuid)Optional

        An outside reviewer; never sent to an outside reviewer.

    • assignedToYoubooleanRequired

      True when the latest round is assigned and the caller is one of the assignees.

    • overrideobjectRequiredNullable

      “Approved by on behalf of ”: the latest standing approvals one owner or editor made for others. Null unless the status is approved and the approvals still stand.

      Show child attributesHide child attributes
      • bystringRequired

        Who approved on behalf of others.

      • forarray of stringsRequired

        Whose approvals were made on their behalf.

      • atstring (date-time)Required

        When.

    • canMovebooleanRequired

      An owner or editor who didn’t send the latest round.

    • archivedAtstring (date-time)RequiredNullable

      When the review was archived; null for a current review. An archived review is left out of the default list.

    • idstring (uuid)Required

      The review’s id.

    • campaignKeystringRequired

      The campaign under review.

    • sitestringRequired

      The brand code under review.

    • namestringRequired

      The campaign’s name now; its key when the setup no longer has it.

    • brandNamestringRequired

      The brand’s name now; its code when the setup no longer has it.

    • statusstringRequired

      empty: nothing sent yet; needs_review; changes_requested; approved.

      Possible valuesemptyneeds_reviewchanges_requestedapproved

    • latestRoundintegerRequired

      The number of the latest round; 0 before the first.

    • progressobjectRequired

      How the latest round’s sizes stand.

      Show child attributesHide child attributes
      • sizesintegerRequired

        Sizes in the latest round.

      • approvedintegerRequired

        Sizes approved.

      • changesRequestedintegerRequired

        Sizes with changes requested.

      • needsReviewintegerRequired

        Sizes still waiting for a decision.

    • createdAtstring (date-time)Required

      When the review was started.

    • lastActivityAtstring (date-time)Required

      When something last happened in the review.

    • expiresAtstring (date-time)RequiredNullable

      The last activity plus the library’s retention; null under Keep everything.

  • archivedCountintegerRequired

    How many of the organisation’s reviews are archived, whichever list this is.

Errors

StatusCodeMeaning
401invalid_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).

409api_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.”

Retrieve a round

PermissionReviews · 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.

Path parameters

  • idstring (uuid)Required
  • nintegerRequired

Returns

The round.

An object with:

  • approvalstringRequired

    all: every assignee must approve a size; any: the first assignee to approve is enough.

    Possible valuesallany

  • duestring (date)RequiredNullable

    The round’s due date, or null.

  • overduebooleanRequired

    The due day has ended in Sydney and a size isn’t approved. Worked out on the server.

  • assigneesarray of objectsRequired

    The people the round is assigned to; empty when it is open to everyone.

    Show child attributesHide child attributes
    • namestringRequired

      The person’s name.

    • outsidebooleanRequired

      True for an outside reviewer, false for a member.

    • youbooleanRequired

      True when this is the caller.

    • waitingbooleanRequired

      A size of the round needs review and they have no standing decision on it.

    • userIdstring (uuid)Optional

      A member; never sent to an outside reviewer.

    • reviewerIdstring (uuid)Optional

      An outside reviewer; never sent to an outside reviewer.

  • numberintegerRequired

    The round’s number, from 1.

  • sourcestringRequired

    Where the round came from: plugin, run, applied, motion, rules, or edited (a hand edit saved in the editor).

    Possible valuespluginrunappliedmotionrulesedited

  • fromRunobjectOptionalNullable

    The run a round was sent from (id), for members; null for other rounds and for outside reviewers.

    Show child attributesHide child attributes
    • idstringOptional

      The run’s id.

  • fromMotionobjectOptionalNullable

    The motion version a round was sent from (jobId), for members; null for other rounds and for outside reviewers.

    Show child attributesHide child attributes
    • jobIdstringOptional

      The motion version’s id.

  • toolstringRequired

    The app the round was sent from: indesign, figma or canva (mestra for a motion round).

  • notestringRequired

    The note the sender left with the round.

  • authorobjectRequired

    Who sent the round.

    Show child attributesHide child attributes
    • namestringRequired

      The sender’s name.

    • youbooleanRequired

      True when the caller sent it.

  • appliedFromobjectRequiredNullable

    Set when the round came from applying an earlier review; otherwise null.

  • createdAtstring (date-time)Required

    When the round was sent.

  • latestbooleanRequired

    True for the newest round, the only one that can be decided, assigned or given a due date.

  • sizesarray of objectsRequired

    The round’s sizes.

    Show child attributesHide child attributes
    • videostringRequiredNullable

      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.

    • notesintegerRequiredNullable

      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.

    • yoursstringRequiredNullable

      The viewer’s own standing decision on the size, if any (one made for them counts).

      Possible valuesapproverequest_changesnull

    • sizestringRequired

      The size’s key.

    • namestringRequiredNullable

      The size’s display name, set when it was sent; null when none was. Outside reviewers see it too.

    • widthnumberRequired

      Width of the size.

    • heightnumberRequired

      Height of the size.

    • sceneHashstringRequired

      A fingerprint (SHA-256) of the size’s artwork; it changes when the artwork does.

    • snapshotstringRequired

      The id (SHA-256) of the picture sent with the size.

    • renderstringRequiredNullable

      The id of Mestra’s own picture of the size, or null when there is none.

    • statusstringRequired

      needs_review, approved or changes_requested.

      Possible valuesneeds_reviewapprovedchanges_requested

    • changedbooleanRequired

      True when the size differs from the round before.

    • carriedbooleanRequired

      True when the size is unchanged and its earlier decision carries over.

    • decisionobjectRequiredNullable

      Null until someone decides; a carried size shows the earlier round’s decision.

      Show child attributesHide child attributes
      • bystringRequired

        Who decided.

      • outsidebooleanRequired

        True when an outside reviewer decided.

      • onBehalfBystringRequiredNullable

        When an owner decided for someone, the owner’s name; otherwise null.

      • atstring (date-time)Required

        When the decision was made.

    • viewobjectOptionalNullable

      Which render to show by default and what can be exported. Null when renders aren’t set up on this server.

      Show child attributesHide child attributes
      • defaultstringRequired

        Which picture to show first: mestra or snapshot.

        Possible valuesmestrasnapshot

      • reasonstringRequiredNullable

        Why the snapshot shows by default; null when Mestra’s own render does.

        Possible valueslossyfontscheckinguncheckedfidelitynull

      • fidelitynumberRequiredNullable

        Share of pixels that differ from the snapshot, once scored.

      • missingFontsarray of stringsRequired

        Fonts the size needs that are not available.

      • exportobjectRequired

        Which file types this size can be exported as.

        Show child attributesHide child attributes
        • pngbooleanRequired

          Can be exported as PNG.

        • jpgbooleanRequired

          Can be exported as JPG.

        • pdfbooleanRequired

          Can be exported as PDF.

        • reasonstringRequiredNullable

          Why the size can’t be exported (or can’t be as PDF); null when every format can be.

Errors

StatusCodeMeaning
401invalid_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).

409api_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.”

Approve or request changes

PermissionReviews · 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.

Path parameters

  • idstring (uuid)Required
  • nintegerRequired

Body parameters

  • sizesone ofRequired

    One of

    string

    Possible valuesall

    array
  • decisionstringRequired

    Possible valuesapproverequest_changes

  • onBehalfOfobjectOptionalNullable

    Owners only. A member’s userId or a verified outside reviewer’s reviewerId.

    Show child attributesHide child attributes
    • userIdstring (uuid)Optional
    • reviewerIdstring (uuid)Optional

Returns

The round.

An object with:

  • approvalstringRequired

    all: every assignee must approve a size; any: the first assignee to approve is enough.

    Possible valuesallany

  • duestring (date)RequiredNullable

    The round’s due date, or null.

  • overduebooleanRequired

    The due day has ended in Sydney and a size isn’t approved. Worked out on the server.

  • assigneesarray of objectsRequired

    The people the round is assigned to; empty when it is open to everyone.

    Show child attributesHide child attributes
    • namestringRequired

      The person’s name.

    • outsidebooleanRequired

      True for an outside reviewer, false for a member.

    • youbooleanRequired

      True when this is the caller.

    • waitingbooleanRequired

      A size of the round needs review and they have no standing decision on it.

    • userIdstring (uuid)Optional

      A member; never sent to an outside reviewer.

    • reviewerIdstring (uuid)Optional

      An outside reviewer; never sent to an outside reviewer.

  • numberintegerRequired

    The round’s number, from 1.

  • sourcestringRequired

    Where the round came from: plugin, run, applied, motion, rules, or edited (a hand edit saved in the editor).

    Possible valuespluginrunappliedmotionrulesedited

  • fromRunobjectOptionalNullable

    The run a round was sent from (id), for members; null for other rounds and for outside reviewers.

    Show child attributesHide child attributes
    • idstringOptional

      The run’s id.

  • fromMotionobjectOptionalNullable

    The motion version a round was sent from (jobId), for members; null for other rounds and for outside reviewers.

    Show child attributesHide child attributes
    • jobIdstringOptional

      The motion version’s id.

  • toolstringRequired

    The app the round was sent from: indesign, figma or canva (mestra for a motion round).

  • notestringRequired

    The note the sender left with the round.

  • authorobjectRequired

    Who sent the round.

    Show child attributesHide child attributes
    • namestringRequired

      The sender’s name.

    • youbooleanRequired

      True when the caller sent it.

  • appliedFromobjectRequiredNullable

    Set when the round came from applying an earlier review; otherwise null.

  • createdAtstring (date-time)Required

    When the round was sent.

  • latestbooleanRequired

    True for the newest round, the only one that can be decided, assigned or given a due date.

  • sizesarray of objectsRequired

    The round’s sizes.

    Show child attributesHide child attributes
    • videostringRequiredNullable

      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.

    • notesintegerRequiredNullable

      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.

    • yoursstringRequiredNullable

      The viewer’s own standing decision on the size, if any (one made for them counts).

      Possible valuesapproverequest_changesnull

    • sizestringRequired

      The size’s key.

    • namestringRequiredNullable

      The size’s display name, set when it was sent; null when none was. Outside reviewers see it too.

    • widthnumberRequired

      Width of the size.

    • heightnumberRequired

      Height of the size.

    • sceneHashstringRequired

      A fingerprint (SHA-256) of the size’s artwork; it changes when the artwork does.

    • snapshotstringRequired

      The id (SHA-256) of the picture sent with the size.

    • renderstringRequiredNullable

      The id of Mestra’s own picture of the size, or null when there is none.

    • statusstringRequired

      needs_review, approved or changes_requested.

      Possible valuesneeds_reviewapprovedchanges_requested

    • changedbooleanRequired

      True when the size differs from the round before.

    • carriedbooleanRequired

      True when the size is unchanged and its earlier decision carries over.

    • decisionobjectRequiredNullable

      Null until someone decides; a carried size shows the earlier round’s decision.

      Show child attributesHide child attributes
      • bystringRequired

        Who decided.

      • outsidebooleanRequired

        True when an outside reviewer decided.

      • onBehalfBystringRequiredNullable

        When an owner decided for someone, the owner’s name; otherwise null.

      • atstring (date-time)Required

        When the decision was made.

    • viewobjectOptionalNullable

      Which render to show by default and what can be exported. Null when renders aren’t set up on this server.

      Show child attributesHide child attributes
      • defaultstringRequired

        Which picture to show first: mestra or snapshot.

        Possible valuesmestrasnapshot

      • reasonstringRequiredNullable

        Why the snapshot shows by default; null when Mestra’s own render does.

        Possible valueslossyfontscheckinguncheckedfidelitynull

      • fidelitynumberRequiredNullable

        Share of pixels that differ from the snapshot, once scored.

      • missingFontsarray of stringsRequired

        Fonts the size needs that are not available.

      • exportobjectRequired

        Which file types this size can be exported as.

        Show child attributesHide child attributes
        • pngbooleanRequired

          Can be exported as PNG.

        • jpgbooleanRequired

          Can be exported as JPG.

        • pdfbooleanRequired

          Can be exported as PDF.

        • reasonstringRequiredNullable

          Why the size can’t be exported (or can’t be as PDF); null when every format can be.

Errors

StatusCodeMeaning
400review_size

review_size (the round has no such size), or a bad decision or sizes (with field), or bad JSON: <error>.

401invalid_token

The key is missing, unknown, revoked or expired (code invalid_token). Send it as Authorization: Bearer <key>.

403review_own_roundreview_not_assignedreview_on_behalfwrong_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).

409review_not_latestapi_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.”

Update a round's assignees

PermissionReviews · 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.

Path parameters

  • idstring (uuid)Required
  • nintegerRequired

Body parameters

  • peoplearray of objectsRequired
    Show child attributesHide child attributes
    • userIdstring (uuid)Optional

      A member’s user id (from GET .../people).

    • reviewerIdstring (uuid)Optional

      An outside reviewer’s id (from GET .../people).

  • approvalstringRequired

    Possible valuesallany

Returns

The round.

An object with:

  • approvalstringRequired

    all: every assignee must approve a size; any: the first assignee to approve is enough.

    Possible valuesallany

  • duestring (date)RequiredNullable

    The round’s due date, or null.

  • overduebooleanRequired

    The due day has ended in Sydney and a size isn’t approved. Worked out on the server.

  • assigneesarray of objectsRequired

    The people the round is assigned to; empty when it is open to everyone.

    Show child attributesHide child attributes
    • namestringRequired

      The person’s name.

    • outsidebooleanRequired

      True for an outside reviewer, false for a member.

    • youbooleanRequired

      True when this is the caller.

    • waitingbooleanRequired

      A size of the round needs review and they have no standing decision on it.

    • userIdstring (uuid)Optional

      A member; never sent to an outside reviewer.

    • reviewerIdstring (uuid)Optional

      An outside reviewer; never sent to an outside reviewer.

  • numberintegerRequired

    The round’s number, from 1.

  • sourcestringRequired

    Where the round came from: plugin, run, applied, motion, rules, or edited (a hand edit saved in the editor).

    Possible valuespluginrunappliedmotionrulesedited

  • fromRunobjectOptionalNullable

    The run a round was sent from (id), for members; null for other rounds and for outside reviewers.

    Show child attributesHide child attributes
    • idstringOptional

      The run’s id.

  • fromMotionobjectOptionalNullable

    The motion version a round was sent from (jobId), for members; null for other rounds and for outside reviewers.

    Show child attributesHide child attributes
    • jobIdstringOptional

      The motion version’s id.

  • toolstringRequired

    The app the round was sent from: indesign, figma or canva (mestra for a motion round).

  • notestringRequired

    The note the sender left with the round.

  • authorobjectRequired

    Who sent the round.

    Show child attributesHide child attributes
    • namestringRequired

      The sender’s name.

    • youbooleanRequired

      True when the caller sent it.

  • appliedFromobjectRequiredNullable

    Set when the round came from applying an earlier review; otherwise null.

  • createdAtstring (date-time)Required

    When the round was sent.

  • latestbooleanRequired

    True for the newest round, the only one that can be decided, assigned or given a due date.

  • sizesarray of objectsRequired

    The round’s sizes.

    Show child attributesHide child attributes
    • videostringRequiredNullable

      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.

    • notesintegerRequiredNullable

      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.

    • yoursstringRequiredNullable

      The viewer’s own standing decision on the size, if any (one made for them counts).

      Possible valuesapproverequest_changesnull

    • sizestringRequired

      The size’s key.

    • namestringRequiredNullable

      The size’s display name, set when it was sent; null when none was. Outside reviewers see it too.

    • widthnumberRequired

      Width of the size.

    • heightnumberRequired

      Height of the size.

    • sceneHashstringRequired

      A fingerprint (SHA-256) of the size’s artwork; it changes when the artwork does.

    • snapshotstringRequired

      The id (SHA-256) of the picture sent with the size.

    • renderstringRequiredNullable

      The id of Mestra’s own picture of the size, or null when there is none.

    • statusstringRequired

      needs_review, approved or changes_requested.

      Possible valuesneeds_reviewapprovedchanges_requested

    • changedbooleanRequired

      True when the size differs from the round before.

    • carriedbooleanRequired

      True when the size is unchanged and its earlier decision carries over.

    • decisionobjectRequiredNullable

      Null until someone decides; a carried size shows the earlier round’s decision.

      Show child attributesHide child attributes
      • bystringRequired

        Who decided.

      • outsidebooleanRequired

        True when an outside reviewer decided.

      • onBehalfBystringRequiredNullable

        When an owner decided for someone, the owner’s name; otherwise null.

      • atstring (date-time)Required

        When the decision was made.

    • viewobjectOptionalNullable

      Which render to show by default and what can be exported. Null when renders aren’t set up on this server.

      Show child attributesHide child attributes
      • defaultstringRequired

        Which picture to show first: mestra or snapshot.

        Possible valuesmestrasnapshot

      • reasonstringRequiredNullable

        Why the snapshot shows by default; null when Mestra’s own render does.

        Possible valueslossyfontscheckinguncheckedfidelitynull

      • fidelitynumberRequiredNullable

        Share of pixels that differ from the snapshot, once scored.

      • missingFontsarray of stringsRequired

        Fonts the size needs that are not available.

      • exportobjectRequired

        Which file types this size can be exported as.

        Show child attributesHide child attributes
        • pngbooleanRequired

          Can be exported as PNG.

        • jpgbooleanRequired

          Can be exported as JPG.

        • pdfbooleanRequired

          Can be exported as PDF.

        • reasonstringRequiredNullable

          Why the size can’t be exported (or can’t be as PDF); null when every format can be.

Errors

StatusCodeMeaning
400review_assign_authorreview_assignee

review_assign_author, review_assignee (someone people doesn’t list), or a bad approval or people (with field), or bad JSON: <error>.

401invalid_token

The key is missing, unknown, revoked or expired (code invalid_token). Send it as Authorization: Bearer <key>.

403wrong_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).

409review_not_latestapi_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.”

Update a round's due date

PermissionReviews · 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.

Path parameters

  • idstring (uuid)Required
  • nintegerRequired

Body parameters

  • duestring (date)RequiredNullable

Returns

The round.

An object with:

  • approvalstringRequired

    all: every assignee must approve a size; any: the first assignee to approve is enough.

    Possible valuesallany

  • duestring (date)RequiredNullable

    The round’s due date, or null.

  • overduebooleanRequired

    The due day has ended in Sydney and a size isn’t approved. Worked out on the server.

  • assigneesarray of objectsRequired

    The people the round is assigned to; empty when it is open to everyone.

    Show child attributesHide child attributes
    • namestringRequired

      The person’s name.

    • outsidebooleanRequired

      True for an outside reviewer, false for a member.

    • youbooleanRequired

      True when this is the caller.

    • waitingbooleanRequired

      A size of the round needs review and they have no standing decision on it.

    • userIdstring (uuid)Optional

      A member; never sent to an outside reviewer.

    • reviewerIdstring (uuid)Optional

      An outside reviewer; never sent to an outside reviewer.

  • numberintegerRequired

    The round’s number, from 1.

  • sourcestringRequired

    Where the round came from: plugin, run, applied, motion, rules, or edited (a hand edit saved in the editor).

    Possible valuespluginrunappliedmotionrulesedited

  • fromRunobjectOptionalNullable

    The run a round was sent from (id), for members; null for other rounds and for outside reviewers.

    Show child attributesHide child attributes
    • idstringOptional

      The run’s id.

  • fromMotionobjectOptionalNullable

    The motion version a round was sent from (jobId), for members; null for other rounds and for outside reviewers.

    Show child attributesHide child attributes
    • jobIdstringOptional

      The motion version’s id.

  • toolstringRequired

    The app the round was sent from: indesign, figma or canva (mestra for a motion round).

  • notestringRequired

    The note the sender left with the round.

  • authorobjectRequired

    Who sent the round.

    Show child attributesHide child attributes
    • namestringRequired

      The sender’s name.

    • youbooleanRequired

      True when the caller sent it.

  • appliedFromobjectRequiredNullable

    Set when the round came from applying an earlier review; otherwise null.

  • createdAtstring (date-time)Required

    When the round was sent.

  • latestbooleanRequired

    True for the newest round, the only one that can be decided, assigned or given a due date.

  • sizesarray of objectsRequired

    The round’s sizes.

    Show child attributesHide child attributes
    • videostringRequiredNullable

      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.

    • notesintegerRequiredNullable

      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.

    • yoursstringRequiredNullable

      The viewer’s own standing decision on the size, if any (one made for them counts).

      Possible valuesapproverequest_changesnull

    • sizestringRequired

      The size’s key.

    • namestringRequiredNullable

      The size’s display name, set when it was sent; null when none was. Outside reviewers see it too.

    • widthnumberRequired

      Width of the size.

    • heightnumberRequired

      Height of the size.

    • sceneHashstringRequired

      A fingerprint (SHA-256) of the size’s artwork; it changes when the artwork does.

    • snapshotstringRequired

      The id (SHA-256) of the picture sent with the size.

    • renderstringRequiredNullable

      The id of Mestra’s own picture of the size, or null when there is none.

    • statusstringRequired

      needs_review, approved or changes_requested.

      Possible valuesneeds_reviewapprovedchanges_requested

    • changedbooleanRequired

      True when the size differs from the round before.

    • carriedbooleanRequired

      True when the size is unchanged and its earlier decision carries over.

    • decisionobjectRequiredNullable

      Null until someone decides; a carried size shows the earlier round’s decision.

      Show child attributesHide child attributes
      • bystringRequired

        Who decided.

      • outsidebooleanRequired

        True when an outside reviewer decided.

      • onBehalfBystringRequiredNullable

        When an owner decided for someone, the owner’s name; otherwise null.

      • atstring (date-time)Required

        When the decision was made.

    • viewobjectOptionalNullable

      Which render to show by default and what can be exported. Null when renders aren’t set up on this server.

      Show child attributesHide child attributes
      • defaultstringRequired

        Which picture to show first: mestra or snapshot.

        Possible valuesmestrasnapshot

      • reasonstringRequiredNullable

        Why the snapshot shows by default; null when Mestra’s own render does.

        Possible valueslossyfontscheckinguncheckedfidelitynull

      • fidelitynumberRequiredNullable

        Share of pixels that differ from the snapshot, once scored.

      • missingFontsarray of stringsRequired

        Fonts the size needs that are not available.

      • exportobjectRequired

        Which file types this size can be exported as.

        Show child attributesHide child attributes
        • pngbooleanRequired

          Can be exported as PNG.

        • jpgbooleanRequired

          Can be exported as JPG.

        • pdfbooleanRequired

          Can be exported as PDF.

        • reasonstringRequiredNullable

          Why the size can’t be exported (or can’t be as PDF); null when every format can be.

Errors

StatusCodeMeaning
400review_due_pastreview_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>.

401invalid_token

The key is missing, unknown, revoked or expired (code invalid_token). Send it as Authorization: Bearer <key>.

403wrong_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).

409review_not_latestapi_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.”

List all people who can be assigned

PermissionReviews · 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.

Path parameters

  • idstring (uuid)Required

Returns

The people.

An object with:

  • peoplearray of objectsRequired
    Show child attributesHide child attributes
    • namestringRequired
    • outsidebooleanRequired
    • userIdstring (uuid)Optional

      A member.

    • reviewerIdstring (uuid)Optional

      An outside reviewer.

Errors

StatusCodeMeaning
401invalid_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).

409api_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.”

List all comments

PermissionReviews · 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.

Path parameters

  • idstring (uuid)Required

Returns

The comments.

An object with:

  • commentsarray of objectsRequired
    Show child attributesHide child attributes
    • atnumberRequiredNullable

      Seconds into a motion size’s video the comment is about; null for a stills size and for replies.

    • pinLabelstringRequiredNullable

      What the pinned element is called (for example Headline), for a pin on a motion size; null otherwise.

    • idstring (uuid)Required

      The comment’s id.

    • roundintegerRequired

      The round the comment is on.

    • sizestringRequiredNullable

      The size the comment is on, or null for a comment on the whole round.

    • parentIdstring (uuid)RequiredNullable

      The comment this replies to, or null for a first comment.

    • authorobjectRequired

      Who wrote it.

      Show child attributesHide child attributes
      • namestringRequired

        The author’s name.

      • outsidebooleanRequired

        True for an outside reviewer.

      • youbooleanRequired

        True when the caller wrote it.

    • bodystringRequired

      Untrusted text, stored as given. Escape it when showing it.

    • pinobjectRequiredNullable

      Where on the size the comment points, or null.

      Show child attributesHide child attributes
      • xnumberRequired

        Horizontal position, in the size’s own pixels.

      • ynumberRequired

        Vertical position, in the size’s own pixels.

    • suggestedbooleanRequired

      True when the comment suggests a change rather than only noting a point.

    • mentionsarray of objectsRequired

      The people the comment mentions.

      Show child attributesHide child attributes
      • userIdstring (uuid)Optional

        A member’s user id.

      • reviewerIdstring (uuid)Optional

        An outside reviewer’s id.

      • namestringOptional

        The person’s name.

    • resolvedobjectRequiredNullable

      Set when the comment was resolved; null while it is open.

      Show child attributesHide child attributes
      • bystringRequired

        Who resolved it.

      • atstring (date-time)Required

        When.

    • createdAtstring (date-time)Required

      When the comment was written.

Errors

StatusCodeMeaning
401invalid_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).

409api_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.”

Add a comment

PermissionReviews · 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.

Path parameters

  • idstring (uuid)Required

Body parameters

  • roundintegerRequired
  • sizestringOptionalNullable

    Absent for a comment on the whole round. A pin needs it.

  • parentIdstring (uuid)OptionalNullable

    A top-level comment of this review; a reply has no pin.

  • bodystringRequired
  • pinobjectOptionalNullable

    A point inside the size, in its own pixels.

    Show child attributesHide child attributes
    • xnumberRequired
    • ynumberRequired
  • atnumberOptionalNullable

    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.

  • elementIdstringOptional

    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.

  • suggestedbooleanOptional
  • mentionsobjectOptional

    At most 20 people in all.

    Show child attributesHide child attributes
    • userIdsarray of stringsOptional
    • reviewerIdsarray of stringsOptional

Returns

The comment.

An object with:

  • atnumberRequiredNullable

    Seconds into a motion size’s video the comment is about; null for a stills size and for replies.

  • pinLabelstringRequiredNullable

    What the pinned element is called (for example Headline), for a pin on a motion size; null otherwise.

  • idstring (uuid)Required

    The comment’s id.

  • roundintegerRequired

    The round the comment is on.

  • sizestringRequiredNullable

    The size the comment is on, or null for a comment on the whole round.

  • parentIdstring (uuid)RequiredNullable

    The comment this replies to, or null for a first comment.

  • authorobjectRequired

    Who wrote it.

    Show child attributesHide child attributes
    • namestringRequired

      The author’s name.

    • outsidebooleanRequired

      True for an outside reviewer.

    • youbooleanRequired

      True when the caller wrote it.

  • bodystringRequired

    Untrusted text, stored as given. Escape it when showing it.

  • pinobjectRequiredNullable

    Where on the size the comment points, or null.

    Show child attributesHide child attributes
    • xnumberRequired

      Horizontal position, in the size’s own pixels.

    • ynumberRequired

      Vertical position, in the size’s own pixels.

  • suggestedbooleanRequired

    True when the comment suggests a change rather than only noting a point.

  • mentionsarray of objectsRequired

    The people the comment mentions.

    Show child attributesHide child attributes
    • userIdstring (uuid)Optional

      A member’s user id.

    • reviewerIdstring (uuid)Optional

      An outside reviewer’s id.

    • namestringOptional

      The person’s name.

  • resolvedobjectRequiredNullable

    Set when the comment was resolved; null while it is open.

    Show child attributesHide child attributes
    • bystringRequired

      Who resolved it.

    • atstring (date-time)Required

      When.

  • createdAtstring (date-time)Required

    When the comment was written.

Errors

StatusCodeMeaning
400

A refusal naming its field: body, round, size, pin, parentId or mentions; or bad JSON: <error>.

401invalid_token

The key is missing, unknown, revoked or expired (code invalid_token). Send it as Authorization: Bearer <key>.

403wrong_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).

409api_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.”

Resolve a comment

PermissionReviews · 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.

Path parameters

  • idstring (uuid)Required
  • commentstring (uuid)Required

Body parameters

  • resolvedbooleanRequired

    true resolves; false reopens. Required: a request without it is a 400.

Returns

The comment.

An object with:

  • atnumberRequiredNullable

    Seconds into a motion size’s video the comment is about; null for a stills size and for replies.

  • pinLabelstringRequiredNullable

    What the pinned element is called (for example Headline), for a pin on a motion size; null otherwise.

  • idstring (uuid)Required

    The comment’s id.

  • roundintegerRequired

    The round the comment is on.

  • sizestringRequiredNullable

    The size the comment is on, or null for a comment on the whole round.

  • parentIdstring (uuid)RequiredNullable

    The comment this replies to, or null for a first comment.

  • authorobjectRequired

    Who wrote it.

    Show child attributesHide child attributes
    • namestringRequired

      The author’s name.

    • outsidebooleanRequired

      True for an outside reviewer.

    • youbooleanRequired

      True when the caller wrote it.

  • bodystringRequired

    Untrusted text, stored as given. Escape it when showing it.

  • pinobjectRequiredNullable

    Where on the size the comment points, or null.

    Show child attributesHide child attributes
    • xnumberRequired

      Horizontal position, in the size’s own pixels.

    • ynumberRequired

      Vertical position, in the size’s own pixels.

  • suggestedbooleanRequired

    True when the comment suggests a change rather than only noting a point.

  • mentionsarray of objectsRequired

    The people the comment mentions.

    Show child attributesHide child attributes
    • userIdstring (uuid)Optional

      A member’s user id.

    • reviewerIdstring (uuid)Optional

      An outside reviewer’s id.

    • namestringOptional

      The person’s name.

  • resolvedobjectRequiredNullable

    Set when the comment was resolved; null while it is open.

    Show child attributesHide child attributes
    • bystringRequired

      Who resolved it.

    • atstring (date-time)Required

      When.

  • createdAtstring (date-time)Required

    When the comment was written.

Errors

StatusCodeMeaning
400

resolved missing or not true or false (with field), or bad JSON: <error>.

401invalid_token

The key is missing, unknown, revoked or expired (code invalid_token). Send it as Authorization: Bearer <key>.

403wrong_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).

409api_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.”

Start an export

PermissionReviews · 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.

Path parameters

  • idstring (uuid)Required
  • nintegerRequired

Body parameters

  • formatstringRequired

    Possible valuespngjpgpdf

  • scalenumberOptional

    Default1

  • sizesone ofOptional

    all, or a non-empty list of the round’s sizes. Leave it out for all; null is refused.

    One of

    string

    Possible valuesall

    array

Returns

Queued.

An object with:

  • exportobjectRequired
    Show child attributesHide child attributes
    • idstring (uuid)Required

      The export’s id.

    • roundintegerRequired

      The round exported.

    • formatstringRequired

      The file type: png, jpg or pdf.

      Possible valuespngjpgpdf

    • scalenumberRequired

      The scale the files were made at.

    • statusstringRequired

      queued, running, done or failed.

      Possible valuesqueuedrunningdonefailed

    • byobjectRequired

      Who started the export.

      Show child attributesHide child attributes
      • namestringRequired

        The name of the person who started the export.

    • createdAtstring (date-time)Required

      When the export was requested.

    • finishedAtstring (date-time)RequiredNullable

      When it finished; null while it runs.

    • expiresAtstring (date-time)Required

      When its files are deleted (7 days after it was made).

    • skippedobjectRequired

      Sizes left out, each with its reason (checking, unchecked, fidelity, fonts, lossy, pdf-licence, too-large or an asset reason).

    • filesarray of objectsRequired

      One entry for each size in the export.

      Show child attributesHide child attributes
      • sizestringRequired

        The size’s key.

      • statusstringRequired

        queued, done or failed.

        Possible valuesqueueddonefailed

      • bytesintegerRequiredNullable

        The file’s size in bytes once done; otherwise null.

      • reasonstringRequiredNullable

        Why the file failed; otherwise null.

Errors

StatusCodeMeaning
400review_sizeexport_too_many_sizesexport_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.

401invalid_token

The key is missing, unknown, revoked or expired (code invalid_token). Send it as Authorization: Bearer <key>.

403wrong_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).

409export_busyapi_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).

List all exports

PermissionReviews · Read

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

Path parameters

  • idstring (uuid)Required

Returns

The exports.

An object with:

  • exportsarray of objectsRequired
    Show child attributesHide child attributes
    • idstring (uuid)Required

      The export’s id.

    • roundintegerRequired

      The round exported.

    • formatstringRequired

      The file type: png, jpg or pdf.

      Possible valuespngjpgpdf

    • scalenumberRequired

      The scale the files were made at.

    • statusstringRequired

      queued, running, done or failed.

      Possible valuesqueuedrunningdonefailed

    • byobjectRequired

      Who started the export.

      Show child attributesHide child attributes
      • namestringRequired

        The name of the person who started the export.

    • createdAtstring (date-time)Required

      When the export was requested.

    • finishedAtstring (date-time)RequiredNullable

      When it finished; null while it runs.

    • expiresAtstring (date-time)Required

      When its files are deleted (7 days after it was made).

    • skippedobjectRequired

      Sizes left out, each with its reason (checking, unchecked, fidelity, fonts, lossy, pdf-licence, too-large or an asset reason).

    • filesarray of objectsRequired

      One entry for each size in the export.

      Show child attributesHide child attributes
      • sizestringRequired

        The size’s key.

      • statusstringRequired

        queued, done or failed.

        Possible valuesqueueddonefailed

      • bytesintegerRequiredNullable

        The file’s size in bytes once done; otherwise null.

      • reasonstringRequiredNullable

        Why the file failed; otherwise null.

Errors

StatusCodeMeaning
401invalid_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).

409api_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).

Retrieve an export

PermissionReviews · 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.

Path parameters

  • idstring (uuid)Required
  • exportstring (uuid)Required

Returns

The export.

An object with:

  • idstring (uuid)Required

    The export’s id.

  • roundintegerRequired

    The round exported.

  • formatstringRequired

    The file type: png, jpg or pdf.

    Possible valuespngjpgpdf

  • scalenumberRequired

    The scale the files were made at.

  • statusstringRequired

    queued, running, done or failed.

    Possible valuesqueuedrunningdonefailed

  • byobjectRequired

    Who started the export.

    Show child attributesHide child attributes
    • namestringRequired

      The name of the person who started the export.

  • createdAtstring (date-time)Required

    When the export was requested.

  • finishedAtstring (date-time)RequiredNullable

    When it finished; null while it runs.

  • expiresAtstring (date-time)Required

    When its files are deleted (7 days after it was made).

  • skippedobjectRequired

    Sizes left out, each with its reason (checking, unchecked, fidelity, fonts, lossy, pdf-licence, too-large or an asset reason).

  • filesarray of objectsRequired

    One entry for each size in the export.

    Show child attributesHide child attributes
    • sizestringRequired

      The size’s key.

    • statusstringRequired

      queued, done or failed.

      Possible valuesqueueddonefailed

    • bytesintegerRequiredNullable

      The file’s size in bytes once done; otherwise null.

    • reasonstringRequiredNullable

      Why the file failed; otherwise null.

Errors

StatusCodeMeaning
401invalid_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).

409api_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).

Download an export

PermissionReviews · 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.

Path parameters

  • idstring (uuid)Required
  • exportstring (uuid)Required

Returns

The zip.

Errors

StatusCodeMeaning
401invalid_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).

409export_not_readyapi_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).

Download a file from an export

PermissionReviews · 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.

Path parameters

  • idstring (uuid)Required
  • exportstring (uuid)Required
  • sizestringRequired

Returns

The file.

Errors

StatusCodeMeaning
401invalid_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).

409api_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).