API reference
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.
The Review object
The review object. A review is for one campaign and one brand.
Attributes
kindstringRequiredstills(a review of images) ormotion(a review of animated versions). A motion review holds MP4s and posters of a stills review’s sizes.Possible values
stillsmotionsourceIdstring (uuid)RequiredNullableA motion review’s stills review, for members; null for a stills review and once the stills review is deleted.
approvalstringRequiredThe latest round’s rule.
Possible values
allanyduestring (date)RequiredNullableThe latest round’s due date, or null.
overduebooleanRequiredThe due day has ended in Sydney and a size isn’t approved. Worked out on the server.
assigneesarray of objectsRequiredThe latest round’s current assignees.
Show child attributesHide child attributes
namestringRequiredThe person’s name.
outsidebooleanRequiredTrue for an outside reviewer, false for a member.
youbooleanRequiredTrue when this is the caller.
waitingbooleanRequiredA size of the round needs review and they have no standing decision on it.
userIdstring (uuid)OptionalA member; never sent to an outside reviewer.
reviewerIdstring (uuid)OptionalAn outside reviewer; never sent to an outside reviewer.
assignedToYoubooleanRequiredTrue 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 approvedand the approvals still stand.Show child attributesHide child attributes
bystringRequiredWho approved on behalf of others.
forarray of stringsRequiredWhose approvals were made on their behalf.
atstring (date-time)RequiredWhen.
canMovebooleanRequiredAn owner or editor who didn’t send the latest round.
archivedAtstring (date-time)RequiredNullableWhen the review was archived; null for a current review. An archived review is left out of the default list.
idstring (uuid)RequiredThe review’s id.
campaignKeystringRequiredThe campaign under review.
sitestringRequiredThe brand code under review.
namestringRequiredThe campaign’s name now; its key when the setup no longer has it.
brandNamestringRequiredThe brand’s name now; its code when the setup no longer has it.
statusstringRequiredempty: nothing sent yet;needs_review;changes_requested;approved.Possible values
emptyneeds_reviewchanges_requestedapprovedlatestRoundintegerRequiredThe number of the latest round; 0 before the first.
progressobjectRequiredHow the latest round’s sizes stand.
Show child attributesHide child attributes
sizesintegerRequiredSizes in the latest round.
approvedintegerRequiredSizes approved.
changesRequestedintegerRequiredSizes with changes requested.
needsReviewintegerRequiredSizes still waiting for a decision.
createdAtstring (date-time)RequiredWhen the review was started.
lastActivityAtstring (date-time)RequiredWhen something last happened in the review.
expiresAtstring (date-time)RequiredNullableThe last activity plus the library’s retention; null under Keep everything.
Start a review
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
campaignKeystringRequiredsitestringRequiredA brand’s code; it must be one of the campaign’s.
Returns
The existing review.
An object with:
kindstringRequiredstills(a review of images) ormotion(a review of animated versions). A motion review holds MP4s and posters of a stills review’s sizes.Possible values
stillsmotionsourceIdstring (uuid)RequiredNullableA motion review’s stills review, for members; null for a stills review and once the stills review is deleted.
approvalstringRequiredThe latest round’s rule.
Possible values
allanyduestring (date)RequiredNullableThe latest round’s due date, or null.
overduebooleanRequiredThe due day has ended in Sydney and a size isn’t approved. Worked out on the server.
assigneesarray of objectsRequiredThe latest round’s current assignees.
Show child attributesHide child attributes
namestringRequiredThe person’s name.
outsidebooleanRequiredTrue for an outside reviewer, false for a member.
youbooleanRequiredTrue when this is the caller.
waitingbooleanRequiredA size of the round needs review and they have no standing decision on it.
userIdstring (uuid)OptionalA member; never sent to an outside reviewer.
reviewerIdstring (uuid)OptionalAn outside reviewer; never sent to an outside reviewer.
assignedToYoubooleanRequiredTrue 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 approvedand the approvals still stand.Show child attributesHide child attributes
bystringRequiredWho approved on behalf of others.
forarray of stringsRequiredWhose approvals were made on their behalf.
atstring (date-time)RequiredWhen.
canMovebooleanRequiredAn owner or editor who didn’t send the latest round.
archivedAtstring (date-time)RequiredNullableWhen the review was archived; null for a current review. An archived review is left out of the default list.
idstring (uuid)RequiredThe review’s id.
campaignKeystringRequiredThe campaign under review.
sitestringRequiredThe brand code under review.
namestringRequiredThe campaign’s name now; its key when the setup no longer has it.
brandNamestringRequiredThe brand’s name now; its code when the setup no longer has it.
statusstringRequiredempty: nothing sent yet;needs_review;changes_requested;approved.Possible values
emptyneeds_reviewchanges_requestedapprovedlatestRoundintegerRequiredThe number of the latest round; 0 before the first.
progressobjectRequiredHow the latest round’s sizes stand.
Show child attributesHide child attributes
sizesintegerRequiredSizes in the latest round.
approvedintegerRequiredSizes approved.
changesRequestedintegerRequiredSizes with changes requested.
needsReviewintegerRequiredSizes still waiting for a decision.
createdAtstring (date-time)RequiredWhen the review was started.
lastActivityAtstring (date-time)RequiredWhen something last happened in the review.
expiresAtstring (date-time)RequiredNullableThe last activity plus the library’s retention; null under Keep everything.
roundsarray of objectsRequiredEvery round of the review, oldest first.
Show child attributesHide child attributes
numberintegerRequiredThe round’s number, from 1.
sourcestringRequiredWhere the round came from:
plugin,applied,run,motion,rules, oredited(a hand edit saved in the editor).Possible values
pluginappliedrunmotionruleseditedfromRunobjectOptionalNullableThe run a round was sent from (
id), for members; null for other rounds and for outside reviewers.Show child attributesHide child attributes
idstringOptionalThe run’s id.
fromMotionobjectOptionalNullableThe motion version a round was sent from (
jobId), for members; null for other rounds and for outside reviewers.Show child attributesHide child attributes
jobIdstringOptionalThe motion version’s id.
toolstringRequiredThe app the round was sent from:
indesign,figmaorcanva(mestrafor a motion round).notestringRequiredThe note the sender left with the round.
authorobjectRequiredWho sent the round.
Show child attributesHide child attributes
namestringRequiredThe sender’s name.
youbooleanRequiredTrue when the caller sent it.
createdAtstring (date-time)RequiredWhen the round was sent.
sizesintegerRequiredHow many sizes the round holds.
changedintegerRequiredHow many of its sizes changed since the round before.
youobjectRequiredWhat the caller may do in this review.
Show child attributesHide child attributes
canCommentbooleanRequiredMay comment.
canDecidebooleanRequiredFalse when the latest round has assignees and you aren’t one.
canSendbooleanRequiredMay send a new round.
canResolvebooleanRequiredMay resolve comments.
canManageLinksbooleanRequiredMay manage links for outside reviewers.
canDownloadbooleanRequiredMay download exports.
canArchivebooleanRequiredMay archive and unarchive the review (editors and owners, members only).
canDeletebooleanRequiredMay delete the review (owners, members only).
Errors
| Status | Code | Meaning |
|---|---|---|
400 |
| |
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
404 | “That campaign or brand isn’t in your setup.” | |
409 | review_dont_keepapi_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
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:
kindstringRequiredstills(a review of images) ormotion(a review of animated versions). A motion review holds MP4s and posters of a stills review’s sizes.Possible values
stillsmotionsourceIdstring (uuid)RequiredNullableA motion review’s stills review, for members; null for a stills review and once the stills review is deleted.
approvalstringRequiredThe latest round’s rule.
Possible values
allanyduestring (date)RequiredNullableThe latest round’s due date, or null.
overduebooleanRequiredThe due day has ended in Sydney and a size isn’t approved. Worked out on the server.
assigneesarray of objectsRequiredThe latest round’s current assignees.
Show child attributesHide child attributes
namestringRequiredThe person’s name.
outsidebooleanRequiredTrue for an outside reviewer, false for a member.
youbooleanRequiredTrue when this is the caller.
waitingbooleanRequiredA size of the round needs review and they have no standing decision on it.
userIdstring (uuid)OptionalA member; never sent to an outside reviewer.
reviewerIdstring (uuid)OptionalAn outside reviewer; never sent to an outside reviewer.
assignedToYoubooleanRequiredTrue 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 approvedand the approvals still stand.Show child attributesHide child attributes
bystringRequiredWho approved on behalf of others.
forarray of stringsRequiredWhose approvals were made on their behalf.
atstring (date-time)RequiredWhen.
canMovebooleanRequiredAn owner or editor who didn’t send the latest round.
archivedAtstring (date-time)RequiredNullableWhen the review was archived; null for a current review. An archived review is left out of the default list.
idstring (uuid)RequiredThe review’s id.
campaignKeystringRequiredThe campaign under review.
sitestringRequiredThe brand code under review.
namestringRequiredThe campaign’s name now; its key when the setup no longer has it.
brandNamestringRequiredThe brand’s name now; its code when the setup no longer has it.
statusstringRequiredempty: nothing sent yet;needs_review;changes_requested;approved.Possible values
emptyneeds_reviewchanges_requestedapprovedlatestRoundintegerRequiredThe number of the latest round; 0 before the first.
progressobjectRequiredHow the latest round’s sizes stand.
Show child attributesHide child attributes
sizesintegerRequiredSizes in the latest round.
approvedintegerRequiredSizes approved.
changesRequestedintegerRequiredSizes with changes requested.
needsReviewintegerRequiredSizes still waiting for a decision.
createdAtstring (date-time)RequiredWhen the review was started.
lastActivityAtstring (date-time)RequiredWhen something last happened in the review.
expiresAtstring (date-time)RequiredNullableThe last activity plus the library’s retention; null under Keep everything.
roundsarray of objectsRequiredEvery round of the review, oldest first.
Show child attributesHide child attributes
numberintegerRequiredThe round’s number, from 1.
sourcestringRequiredWhere the round came from:
plugin,applied,run,motion,rules, oredited(a hand edit saved in the editor).Possible values
pluginappliedrunmotionruleseditedfromRunobjectOptionalNullableThe run a round was sent from (
id), for members; null for other rounds and for outside reviewers.Show child attributesHide child attributes
idstringOptionalThe run’s id.
fromMotionobjectOptionalNullableThe motion version a round was sent from (
jobId), for members; null for other rounds and for outside reviewers.Show child attributesHide child attributes
jobIdstringOptionalThe motion version’s id.
toolstringRequiredThe app the round was sent from:
indesign,figmaorcanva(mestrafor a motion round).notestringRequiredThe note the sender left with the round.
authorobjectRequiredWho sent the round.
Show child attributesHide child attributes
namestringRequiredThe sender’s name.
youbooleanRequiredTrue when the caller sent it.
createdAtstring (date-time)RequiredWhen the round was sent.
sizesintegerRequiredHow many sizes the round holds.
changedintegerRequiredHow many of its sizes changed since the round before.
youobjectRequiredWhat the caller may do in this review.
Show child attributesHide child attributes
canCommentbooleanRequiredMay comment.
canDecidebooleanRequiredFalse when the latest round has assignees and you aren’t one.
canSendbooleanRequiredMay send a new round.
canResolvebooleanRequiredMay resolve comments.
canManageLinksbooleanRequiredMay manage links for outside reviewers.
canDownloadbooleanRequiredMay download exports.
canArchivebooleanRequiredMay archive and unarchive the review (editors and owners, members only).
canDeletebooleanRequiredMay delete the review (owners, members only).
Errors
| Status | Code | Meaning |
|---|---|---|
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
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 |
|
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
Returns the organisation’s reviews, newest first, each with its campaign, brand and where its latest round stands.
Query parameters
archivedstringOptional1lists the archived reviews instead of the current ones. Any other value is ignored.Possible values
1
Returns
The reviews, without their rounds.
An object with:
campaignsarray of objectsRequiredShow child attributesHide child attributes
kindstringRequiredstills(a review of images) ormotion(a review of animated versions). A motion review holds MP4s and posters of a stills review’s sizes.Possible values
stillsmotionsourceIdstring (uuid)RequiredNullableA motion review’s stills review, for members; null for a stills review and once the stills review is deleted.
approvalstringRequiredThe latest round’s rule.
Possible values
allanyduestring (date)RequiredNullableThe latest round’s due date, or null.
overduebooleanRequiredThe due day has ended in Sydney and a size isn’t approved. Worked out on the server.
assigneesarray of objectsRequiredThe latest round’s current assignees.
Show child attributesHide child attributes
namestringRequiredThe person’s name.
outsidebooleanRequiredTrue for an outside reviewer, false for a member.
youbooleanRequiredTrue when this is the caller.
waitingbooleanRequiredA size of the round needs review and they have no standing decision on it.
userIdstring (uuid)OptionalA member; never sent to an outside reviewer.
reviewerIdstring (uuid)OptionalAn outside reviewer; never sent to an outside reviewer.
assignedToYoubooleanRequiredTrue 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 approvedand the approvals still stand.Show child attributesHide child attributes
bystringRequiredWho approved on behalf of others.
forarray of stringsRequiredWhose approvals were made on their behalf.
atstring (date-time)RequiredWhen.
canMovebooleanRequiredAn owner or editor who didn’t send the latest round.
archivedAtstring (date-time)RequiredNullableWhen the review was archived; null for a current review. An archived review is left out of the default list.
idstring (uuid)RequiredThe review’s id.
campaignKeystringRequiredThe campaign under review.
sitestringRequiredThe brand code under review.
namestringRequiredThe campaign’s name now; its key when the setup no longer has it.
brandNamestringRequiredThe brand’s name now; its code when the setup no longer has it.
statusstringRequiredempty: nothing sent yet;needs_review;changes_requested;approved.Possible values
emptyneeds_reviewchanges_requestedapprovedlatestRoundintegerRequiredThe number of the latest round; 0 before the first.
progressobjectRequiredHow the latest round’s sizes stand.
Show child attributesHide child attributes
sizesintegerRequiredSizes in the latest round.
approvedintegerRequiredSizes approved.
changesRequestedintegerRequiredSizes with changes requested.
needsReviewintegerRequiredSizes still waiting for a decision.
createdAtstring (date-time)RequiredWhen the review was started.
lastActivityAtstring (date-time)RequiredWhen something last happened in the review.
expiresAtstring (date-time)RequiredNullableThe last activity plus the library’s retention; null under Keep everything.
archivedCountintegerRequiredHow many of the organisation’s reviews are archived, whichever list this is.
Errors
| Status | Code | Meaning |
|---|---|---|
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
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 |
|
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
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)RequirednintegerRequired
Returns
The round.
An object with:
approvalstringRequiredall: every assignee must approve a size;any: the first assignee to approve is enough.Possible values
allanyduestring (date)RequiredNullableThe round’s due date, or null.
overduebooleanRequiredThe due day has ended in Sydney and a size isn’t approved. Worked out on the server.
assigneesarray of objectsRequiredThe people the round is assigned to; empty when it is open to everyone.
Show child attributesHide child attributes
namestringRequiredThe person’s name.
outsidebooleanRequiredTrue for an outside reviewer, false for a member.
youbooleanRequiredTrue when this is the caller.
waitingbooleanRequiredA size of the round needs review and they have no standing decision on it.
userIdstring (uuid)OptionalA member; never sent to an outside reviewer.
reviewerIdstring (uuid)OptionalAn outside reviewer; never sent to an outside reviewer.
numberintegerRequiredThe round’s number, from 1.
sourcestringRequiredWhere the round came from:
plugin,run,applied,motion,rules, oredited(a hand edit saved in the editor).Possible values
pluginrunappliedmotionruleseditedfromRunobjectOptionalNullableThe run a round was sent from (
id), for members; null for other rounds and for outside reviewers.Show child attributesHide child attributes
idstringOptionalThe run’s id.
fromMotionobjectOptionalNullableThe motion version a round was sent from (
jobId), for members; null for other rounds and for outside reviewers.Show child attributesHide child attributes
jobIdstringOptionalThe motion version’s id.
toolstringRequiredThe app the round was sent from:
indesign,figmaorcanva(mestrafor a motion round).notestringRequiredThe note the sender left with the round.
authorobjectRequiredWho sent the round.
Show child attributesHide child attributes
namestringRequiredThe sender’s name.
youbooleanRequiredTrue when the caller sent it.
appliedFromobjectRequiredNullableSet when the round came from applying an earlier review; otherwise null.
createdAtstring (date-time)RequiredWhen the round was sent.
latestbooleanRequiredTrue for the newest round, the only one that can be decided, assigned or given a due date.
sizesarray of objectsRequiredThe round’s sizes.
Show child attributesHide child attributes
videostringRequiredNullableA motion size’s MP4, an asset id (its SHA-256) served at
/reviews/campaigns/{id}/assets/{asset}; null for a stills size.snapshotis its poster.notesintegerRequiredNullableHow 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.
yoursstringRequiredNullableThe viewer’s own standing decision on the size, if any (one made for them counts).
Possible values
approverequest_changesnullsizestringRequiredThe size’s key.
namestringRequiredNullableThe size’s display name, set when it was sent; null when none was. Outside reviewers see it too.
widthnumberRequiredWidth of the size.
heightnumberRequiredHeight of the size.
sceneHashstringRequiredA fingerprint (SHA-256) of the size’s artwork; it changes when the artwork does.
snapshotstringRequiredThe id (SHA-256) of the picture sent with the size.
renderstringRequiredNullableThe id of Mestra’s own picture of the size, or null when there is none.
statusstringRequiredneeds_review,approvedorchanges_requested.Possible values
needs_reviewapprovedchanges_requestedchangedbooleanRequiredTrue when the size differs from the round before.
carriedbooleanRequiredTrue when the size is unchanged and its earlier decision carries over.
decisionobjectRequiredNullableNull until someone decides; a carried size shows the earlier round’s decision.
Show child attributesHide child attributes
bystringRequiredWho decided.
outsidebooleanRequiredTrue when an outside reviewer decided.
onBehalfBystringRequiredNullableWhen an owner decided for someone, the owner’s name; otherwise null.
atstring (date-time)RequiredWhen the decision was made.
viewobjectOptionalNullableWhich 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
defaultstringRequiredWhich picture to show first:
mestraorsnapshot.Possible values
mestrasnapshotreasonstringRequiredNullableWhy the snapshot shows by default; null when Mestra’s own render does.
Possible values
lossyfontscheckinguncheckedfidelitynullfidelitynumberRequiredNullableShare of pixels that differ from the snapshot, once scored.
missingFontsarray of stringsRequiredFonts the size needs that are not available.
exportobjectRequiredWhich file types this size can be exported as.
Show child attributesHide child attributes
pngbooleanRequiredCan be exported as PNG.
jpgbooleanRequiredCan be exported as JPG.
pdfbooleanRequiredCan be exported as PDF.
reasonstringRequiredNullableWhy the size can’t be exported (or can’t be as PDF); null when every format can be.
Errors
| Status | Code | Meaning |
|---|---|---|
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
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 |
|
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
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)RequirednintegerRequired
Body parameters
sizesone ofRequiredOne of
stringPossible values
allarraydecisionstringRequiredPossible values
approverequest_changesonBehalfOfobjectOptionalNullableOwners only. A member’s
userIdor a verified outside reviewer’sreviewerId.Show child attributesHide child attributes
userIdstring (uuid)OptionalreviewerIdstring (uuid)Optional
Returns
The round.
An object with:
approvalstringRequiredall: every assignee must approve a size;any: the first assignee to approve is enough.Possible values
allanyduestring (date)RequiredNullableThe round’s due date, or null.
overduebooleanRequiredThe due day has ended in Sydney and a size isn’t approved. Worked out on the server.
assigneesarray of objectsRequiredThe people the round is assigned to; empty when it is open to everyone.
Show child attributesHide child attributes
namestringRequiredThe person’s name.
outsidebooleanRequiredTrue for an outside reviewer, false for a member.
youbooleanRequiredTrue when this is the caller.
waitingbooleanRequiredA size of the round needs review and they have no standing decision on it.
userIdstring (uuid)OptionalA member; never sent to an outside reviewer.
reviewerIdstring (uuid)OptionalAn outside reviewer; never sent to an outside reviewer.
numberintegerRequiredThe round’s number, from 1.
sourcestringRequiredWhere the round came from:
plugin,run,applied,motion,rules, oredited(a hand edit saved in the editor).Possible values
pluginrunappliedmotionruleseditedfromRunobjectOptionalNullableThe run a round was sent from (
id), for members; null for other rounds and for outside reviewers.Show child attributesHide child attributes
idstringOptionalThe run’s id.
fromMotionobjectOptionalNullableThe motion version a round was sent from (
jobId), for members; null for other rounds and for outside reviewers.Show child attributesHide child attributes
jobIdstringOptionalThe motion version’s id.
toolstringRequiredThe app the round was sent from:
indesign,figmaorcanva(mestrafor a motion round).notestringRequiredThe note the sender left with the round.
authorobjectRequiredWho sent the round.
Show child attributesHide child attributes
namestringRequiredThe sender’s name.
youbooleanRequiredTrue when the caller sent it.
appliedFromobjectRequiredNullableSet when the round came from applying an earlier review; otherwise null.
createdAtstring (date-time)RequiredWhen the round was sent.
latestbooleanRequiredTrue for the newest round, the only one that can be decided, assigned or given a due date.
sizesarray of objectsRequiredThe round’s sizes.
Show child attributesHide child attributes
videostringRequiredNullableA motion size’s MP4, an asset id (its SHA-256) served at
/reviews/campaigns/{id}/assets/{asset}; null for a stills size.snapshotis its poster.notesintegerRequiredNullableHow 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.
yoursstringRequiredNullableThe viewer’s own standing decision on the size, if any (one made for them counts).
Possible values
approverequest_changesnullsizestringRequiredThe size’s key.
namestringRequiredNullableThe size’s display name, set when it was sent; null when none was. Outside reviewers see it too.
widthnumberRequiredWidth of the size.
heightnumberRequiredHeight of the size.
sceneHashstringRequiredA fingerprint (SHA-256) of the size’s artwork; it changes when the artwork does.
snapshotstringRequiredThe id (SHA-256) of the picture sent with the size.
renderstringRequiredNullableThe id of Mestra’s own picture of the size, or null when there is none.
statusstringRequiredneeds_review,approvedorchanges_requested.Possible values
needs_reviewapprovedchanges_requestedchangedbooleanRequiredTrue when the size differs from the round before.
carriedbooleanRequiredTrue when the size is unchanged and its earlier decision carries over.
decisionobjectRequiredNullableNull until someone decides; a carried size shows the earlier round’s decision.
Show child attributesHide child attributes
bystringRequiredWho decided.
outsidebooleanRequiredTrue when an outside reviewer decided.
onBehalfBystringRequiredNullableWhen an owner decided for someone, the owner’s name; otherwise null.
atstring (date-time)RequiredWhen the decision was made.
viewobjectOptionalNullableWhich 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
defaultstringRequiredWhich picture to show first:
mestraorsnapshot.Possible values
mestrasnapshotreasonstringRequiredNullableWhy the snapshot shows by default; null when Mestra’s own render does.
Possible values
lossyfontscheckinguncheckedfidelitynullfidelitynumberRequiredNullableShare of pixels that differ from the snapshot, once scored.
missingFontsarray of stringsRequiredFonts the size needs that are not available.
exportobjectRequiredWhich file types this size can be exported as.
Show child attributesHide child attributes
pngbooleanRequiredCan be exported as PNG.
jpgbooleanRequiredCan be exported as JPG.
pdfbooleanRequiredCan be exported as PDF.
reasonstringRequiredNullableWhy the size can’t be exported (or can’t be as PDF); null when every format can be.
Errors
| Status | Code | Meaning |
|---|---|---|
400 | review_size |
|
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | review_own_roundreview_not_assignedreview_on_behalfwrong_key |
|
404 | “That review no longer exists.” (including another organisation’s review and a malformed id). | |
409 | review_not_latestapi_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
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)RequirednintegerRequired
Body parameters
peoplearray of objectsRequiredShow child attributesHide child attributes
userIdstring (uuid)OptionalA member’s user id (from
GET .../people).reviewerIdstring (uuid)OptionalAn outside reviewer’s id (from
GET .../people).
approvalstringRequiredPossible values
allany
Returns
The round.
An object with:
approvalstringRequiredall: every assignee must approve a size;any: the first assignee to approve is enough.Possible values
allanyduestring (date)RequiredNullableThe round’s due date, or null.
overduebooleanRequiredThe due day has ended in Sydney and a size isn’t approved. Worked out on the server.
assigneesarray of objectsRequiredThe people the round is assigned to; empty when it is open to everyone.
Show child attributesHide child attributes
namestringRequiredThe person’s name.
outsidebooleanRequiredTrue for an outside reviewer, false for a member.
youbooleanRequiredTrue when this is the caller.
waitingbooleanRequiredA size of the round needs review and they have no standing decision on it.
userIdstring (uuid)OptionalA member; never sent to an outside reviewer.
reviewerIdstring (uuid)OptionalAn outside reviewer; never sent to an outside reviewer.
numberintegerRequiredThe round’s number, from 1.
sourcestringRequiredWhere the round came from:
plugin,run,applied,motion,rules, oredited(a hand edit saved in the editor).Possible values
pluginrunappliedmotionruleseditedfromRunobjectOptionalNullableThe run a round was sent from (
id), for members; null for other rounds and for outside reviewers.Show child attributesHide child attributes
idstringOptionalThe run’s id.
fromMotionobjectOptionalNullableThe motion version a round was sent from (
jobId), for members; null for other rounds and for outside reviewers.Show child attributesHide child attributes
jobIdstringOptionalThe motion version’s id.
toolstringRequiredThe app the round was sent from:
indesign,figmaorcanva(mestrafor a motion round).notestringRequiredThe note the sender left with the round.
authorobjectRequiredWho sent the round.
Show child attributesHide child attributes
namestringRequiredThe sender’s name.
youbooleanRequiredTrue when the caller sent it.
appliedFromobjectRequiredNullableSet when the round came from applying an earlier review; otherwise null.
createdAtstring (date-time)RequiredWhen the round was sent.
latestbooleanRequiredTrue for the newest round, the only one that can be decided, assigned or given a due date.
sizesarray of objectsRequiredThe round’s sizes.
Show child attributesHide child attributes
videostringRequiredNullableA motion size’s MP4, an asset id (its SHA-256) served at
/reviews/campaigns/{id}/assets/{asset}; null for a stills size.snapshotis its poster.notesintegerRequiredNullableHow 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.
yoursstringRequiredNullableThe viewer’s own standing decision on the size, if any (one made for them counts).
Possible values
approverequest_changesnullsizestringRequiredThe size’s key.
namestringRequiredNullableThe size’s display name, set when it was sent; null when none was. Outside reviewers see it too.
widthnumberRequiredWidth of the size.
heightnumberRequiredHeight of the size.
sceneHashstringRequiredA fingerprint (SHA-256) of the size’s artwork; it changes when the artwork does.
snapshotstringRequiredThe id (SHA-256) of the picture sent with the size.
renderstringRequiredNullableThe id of Mestra’s own picture of the size, or null when there is none.
statusstringRequiredneeds_review,approvedorchanges_requested.Possible values
needs_reviewapprovedchanges_requestedchangedbooleanRequiredTrue when the size differs from the round before.
carriedbooleanRequiredTrue when the size is unchanged and its earlier decision carries over.
decisionobjectRequiredNullableNull until someone decides; a carried size shows the earlier round’s decision.
Show child attributesHide child attributes
bystringRequiredWho decided.
outsidebooleanRequiredTrue when an outside reviewer decided.
onBehalfBystringRequiredNullableWhen an owner decided for someone, the owner’s name; otherwise null.
atstring (date-time)RequiredWhen the decision was made.
viewobjectOptionalNullableWhich 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
defaultstringRequiredWhich picture to show first:
mestraorsnapshot.Possible values
mestrasnapshotreasonstringRequiredNullableWhy the snapshot shows by default; null when Mestra’s own render does.
Possible values
lossyfontscheckinguncheckedfidelitynullfidelitynumberRequiredNullableShare of pixels that differ from the snapshot, once scored.
missingFontsarray of stringsRequiredFonts the size needs that are not available.
exportobjectRequiredWhich file types this size can be exported as.
Show child attributesHide child attributes
pngbooleanRequiredCan be exported as PNG.
jpgbooleanRequiredCan be exported as JPG.
pdfbooleanRequiredCan be exported as PDF.
reasonstringRequiredNullableWhy the size can’t be exported (or can’t be as PDF); null when every format can be.
Errors
| Status | Code | Meaning |
|---|---|---|
400 | review_assign_authorreview_assignee |
|
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
404 | “That review no longer exists.” (including another organisation’s review and a malformed id). | |
409 | review_not_latestapi_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
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)RequirednintegerRequired
Body parameters
duestring (date)RequiredNullable
Returns
The round.
An object with:
approvalstringRequiredall: every assignee must approve a size;any: the first assignee to approve is enough.Possible values
allanyduestring (date)RequiredNullableThe round’s due date, or null.
overduebooleanRequiredThe due day has ended in Sydney and a size isn’t approved. Worked out on the server.
assigneesarray of objectsRequiredThe people the round is assigned to; empty when it is open to everyone.
Show child attributesHide child attributes
namestringRequiredThe person’s name.
outsidebooleanRequiredTrue for an outside reviewer, false for a member.
youbooleanRequiredTrue when this is the caller.
waitingbooleanRequiredA size of the round needs review and they have no standing decision on it.
userIdstring (uuid)OptionalA member; never sent to an outside reviewer.
reviewerIdstring (uuid)OptionalAn outside reviewer; never sent to an outside reviewer.
numberintegerRequiredThe round’s number, from 1.
sourcestringRequiredWhere the round came from:
plugin,run,applied,motion,rules, oredited(a hand edit saved in the editor).Possible values
pluginrunappliedmotionruleseditedfromRunobjectOptionalNullableThe run a round was sent from (
id), for members; null for other rounds and for outside reviewers.Show child attributesHide child attributes
idstringOptionalThe run’s id.
fromMotionobjectOptionalNullableThe motion version a round was sent from (
jobId), for members; null for other rounds and for outside reviewers.Show child attributesHide child attributes
jobIdstringOptionalThe motion version’s id.
toolstringRequiredThe app the round was sent from:
indesign,figmaorcanva(mestrafor a motion round).notestringRequiredThe note the sender left with the round.
authorobjectRequiredWho sent the round.
Show child attributesHide child attributes
namestringRequiredThe sender’s name.
youbooleanRequiredTrue when the caller sent it.
appliedFromobjectRequiredNullableSet when the round came from applying an earlier review; otherwise null.
createdAtstring (date-time)RequiredWhen the round was sent.
latestbooleanRequiredTrue for the newest round, the only one that can be decided, assigned or given a due date.
sizesarray of objectsRequiredThe round’s sizes.
Show child attributesHide child attributes
videostringRequiredNullableA motion size’s MP4, an asset id (its SHA-256) served at
/reviews/campaigns/{id}/assets/{asset}; null for a stills size.snapshotis its poster.notesintegerRequiredNullableHow 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.
yoursstringRequiredNullableThe viewer’s own standing decision on the size, if any (one made for them counts).
Possible values
approverequest_changesnullsizestringRequiredThe size’s key.
namestringRequiredNullableThe size’s display name, set when it was sent; null when none was. Outside reviewers see it too.
widthnumberRequiredWidth of the size.
heightnumberRequiredHeight of the size.
sceneHashstringRequiredA fingerprint (SHA-256) of the size’s artwork; it changes when the artwork does.
snapshotstringRequiredThe id (SHA-256) of the picture sent with the size.
renderstringRequiredNullableThe id of Mestra’s own picture of the size, or null when there is none.
statusstringRequiredneeds_review,approvedorchanges_requested.Possible values
needs_reviewapprovedchanges_requestedchangedbooleanRequiredTrue when the size differs from the round before.
carriedbooleanRequiredTrue when the size is unchanged and its earlier decision carries over.
decisionobjectRequiredNullableNull until someone decides; a carried size shows the earlier round’s decision.
Show child attributesHide child attributes
bystringRequiredWho decided.
outsidebooleanRequiredTrue when an outside reviewer decided.
onBehalfBystringRequiredNullableWhen an owner decided for someone, the owner’s name; otherwise null.
atstring (date-time)RequiredWhen the decision was made.
viewobjectOptionalNullableWhich 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
defaultstringRequiredWhich picture to show first:
mestraorsnapshot.Possible values
mestrasnapshotreasonstringRequiredNullableWhy the snapshot shows by default; null when Mestra’s own render does.
Possible values
lossyfontscheckinguncheckedfidelitynullfidelitynumberRequiredNullableShare of pixels that differ from the snapshot, once scored.
missingFontsarray of stringsRequiredFonts the size needs that are not available.
exportobjectRequiredWhich file types this size can be exported as.
Show child attributesHide child attributes
pngbooleanRequiredCan be exported as PNG.
jpgbooleanRequiredCan be exported as JPG.
pdfbooleanRequiredCan be exported as PDF.
reasonstringRequiredNullableWhy the size can’t be exported (or can’t be as PDF); null when every format can be.
Errors
| Status | Code | Meaning |
|---|---|---|
400 | review_due_pastreview_due_far | A |
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
404 | “That review no longer exists.” (including another organisation’s review and a malformed id). | |
409 | review_not_latestapi_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
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 objectsRequiredShow child attributesHide child attributes
namestringRequiredoutsidebooleanRequireduserIdstring (uuid)OptionalA member.
reviewerIdstring (uuid)OptionalAn outside reviewer.
Errors
| Status | Code | Meaning |
|---|---|---|
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
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 |
|
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
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 objectsRequiredShow child attributesHide child attributes
atnumberRequiredNullableSeconds into a motion size’s video the comment is about; null for a stills size and for replies.
pinLabelstringRequiredNullableWhat the pinned element is called (for example
Headline), for a pin on a motion size; null otherwise.idstring (uuid)RequiredThe comment’s id.
roundintegerRequiredThe round the comment is on.
sizestringRequiredNullableThe size the comment is on, or null for a comment on the whole round.
parentIdstring (uuid)RequiredNullableThe comment this replies to, or null for a first comment.
authorobjectRequiredWho wrote it.
Show child attributesHide child attributes
namestringRequiredThe author’s name.
outsidebooleanRequiredTrue for an outside reviewer.
youbooleanRequiredTrue when the caller wrote it.
bodystringRequiredUntrusted text, stored as given. Escape it when showing it.
pinobjectRequiredNullableWhere on the size the comment points, or null.
Show child attributesHide child attributes
xnumberRequiredHorizontal position, in the size’s own pixels.
ynumberRequiredVertical position, in the size’s own pixels.
suggestedbooleanRequiredTrue when the comment suggests a change rather than only noting a point.
mentionsarray of objectsRequiredThe people the comment mentions.
Show child attributesHide child attributes
userIdstring (uuid)OptionalA member’s user id.
reviewerIdstring (uuid)OptionalAn outside reviewer’s id.
namestringOptionalThe person’s name.
resolvedobjectRequiredNullableSet when the comment was resolved; null while it is open.
Show child attributesHide child attributes
bystringRequiredWho resolved it.
atstring (date-time)RequiredWhen.
createdAtstring (date-time)RequiredWhen the comment was written.
Errors
| Status | Code | Meaning |
|---|---|---|
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
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 |
|
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
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
roundintegerRequiredsizestringOptionalNullableAbsent for a comment on the whole round. A pin needs it.
parentIdstring (uuid)OptionalNullableA top-level comment of this review; a reply has no pin.
bodystringRequiredpinobjectOptionalNullableA point inside the size, in its own pixels.
Show child attributesHide child attributes
xnumberRequiredynumberRequired
atnumberOptionalNullableSeconds 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.
elementIdstringOptionalThe 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
pinLabelis derived from it.suggestedbooleanOptionalmentionsobjectOptionalAt most 20 people in all.
Show child attributesHide child attributes
userIdsarray of stringsOptionalreviewerIdsarray of stringsOptional
Returns
The comment.
An object with:
atnumberRequiredNullableSeconds into a motion size’s video the comment is about; null for a stills size and for replies.
pinLabelstringRequiredNullableWhat the pinned element is called (for example
Headline), for a pin on a motion size; null otherwise.idstring (uuid)RequiredThe comment’s id.
roundintegerRequiredThe round the comment is on.
sizestringRequiredNullableThe size the comment is on, or null for a comment on the whole round.
parentIdstring (uuid)RequiredNullableThe comment this replies to, or null for a first comment.
authorobjectRequiredWho wrote it.
Show child attributesHide child attributes
namestringRequiredThe author’s name.
outsidebooleanRequiredTrue for an outside reviewer.
youbooleanRequiredTrue when the caller wrote it.
bodystringRequiredUntrusted text, stored as given. Escape it when showing it.
pinobjectRequiredNullableWhere on the size the comment points, or null.
Show child attributesHide child attributes
xnumberRequiredHorizontal position, in the size’s own pixels.
ynumberRequiredVertical position, in the size’s own pixels.
suggestedbooleanRequiredTrue when the comment suggests a change rather than only noting a point.
mentionsarray of objectsRequiredThe people the comment mentions.
Show child attributesHide child attributes
userIdstring (uuid)OptionalA member’s user id.
reviewerIdstring (uuid)OptionalAn outside reviewer’s id.
namestringOptionalThe person’s name.
resolvedobjectRequiredNullableSet when the comment was resolved; null while it is open.
Show child attributesHide child attributes
bystringRequiredWho resolved it.
atstring (date-time)RequiredWhen.
createdAtstring (date-time)RequiredWhen the comment was written.
Errors
| Status | Code | Meaning |
|---|---|---|
400 | A refusal naming its | |
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
404 | “That review no longer exists.” (including another organisation’s review and a malformed id). | |
409 | 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.” |
Resolve a comment
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)Requiredcommentstring (uuid)Required
Body parameters
resolvedbooleanRequiredtrue resolves; false reopens. Required: a request without it is a 400.
Returns
The comment.
An object with:
atnumberRequiredNullableSeconds into a motion size’s video the comment is about; null for a stills size and for replies.
pinLabelstringRequiredNullableWhat the pinned element is called (for example
Headline), for a pin on a motion size; null otherwise.idstring (uuid)RequiredThe comment’s id.
roundintegerRequiredThe round the comment is on.
sizestringRequiredNullableThe size the comment is on, or null for a comment on the whole round.
parentIdstring (uuid)RequiredNullableThe comment this replies to, or null for a first comment.
authorobjectRequiredWho wrote it.
Show child attributesHide child attributes
namestringRequiredThe author’s name.
outsidebooleanRequiredTrue for an outside reviewer.
youbooleanRequiredTrue when the caller wrote it.
bodystringRequiredUntrusted text, stored as given. Escape it when showing it.
pinobjectRequiredNullableWhere on the size the comment points, or null.
Show child attributesHide child attributes
xnumberRequiredHorizontal position, in the size’s own pixels.
ynumberRequiredVertical position, in the size’s own pixels.
suggestedbooleanRequiredTrue when the comment suggests a change rather than only noting a point.
mentionsarray of objectsRequiredThe people the comment mentions.
Show child attributesHide child attributes
userIdstring (uuid)OptionalA member’s user id.
reviewerIdstring (uuid)OptionalAn outside reviewer’s id.
namestringOptionalThe person’s name.
resolvedobjectRequiredNullableSet when the comment was resolved; null while it is open.
Show child attributesHide child attributes
bystringRequiredWho resolved it.
atstring (date-time)RequiredWhen.
createdAtstring (date-time)RequiredWhen the comment was written.
Errors
| Status | Code | Meaning |
|---|---|---|
400 |
| |
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
404 | “That review no longer exists.” (including another organisation’s review and a malformed id). | |
409 | 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.” |
Start an export
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)RequirednintegerRequired
Body parameters
formatstringRequiredPossible values
pngjpgpdfscalenumberOptionalDefault
1sizesone ofOptionalall, or a non-empty list of the round’s sizes. Leave it out for all;nullis refused.One of
stringPossible values
allarray
Returns
Queued.
An object with:
exportobjectRequiredShow child attributesHide child attributes
idstring (uuid)RequiredThe export’s id.
roundintegerRequiredThe round exported.
formatstringRequiredThe file type:
png,jpgorpdf.Possible values
pngjpgpdfscalenumberRequiredThe scale the files were made at.
statusstringRequiredqueued,running,doneorfailed.Possible values
queuedrunningdonefailedbyobjectRequiredWho started the export.
Show child attributesHide child attributes
namestringRequiredThe name of the person who started the export.
createdAtstring (date-time)RequiredWhen the export was requested.
finishedAtstring (date-time)RequiredNullableWhen it finished; null while it runs.
expiresAtstring (date-time)RequiredWhen its files are deleted (7 days after it was made).
skippedobjectRequiredSizes left out, each with its reason (
checking,unchecked,fidelity,fonts,lossy,pdf-licence,too-largeor an asset reason).filesarray of objectsRequiredOne entry for each size in the export.
Show child attributesHide child attributes
sizestringRequiredThe size’s key.
statusstringRequiredqueued,doneorfailed.Possible values
queueddonefailedbytesintegerRequiredNullableThe file’s size in bytes once done; otherwise null.
reasonstringRequiredNullableWhy the file failed; otherwise null.
Errors
| Status | Code | Meaning |
|---|---|---|
400 | review_sizeexport_too_many_sizesexport_none | A bad |
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
404 | “That review no longer exists.” (including another organisation’s review and a malformed id). | |
409 | export_busyapi_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
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 objectsRequiredShow child attributesHide child attributes
idstring (uuid)RequiredThe export’s id.
roundintegerRequiredThe round exported.
formatstringRequiredThe file type:
png,jpgorpdf.Possible values
pngjpgpdfscalenumberRequiredThe scale the files were made at.
statusstringRequiredqueued,running,doneorfailed.Possible values
queuedrunningdonefailedbyobjectRequiredWho started the export.
Show child attributesHide child attributes
namestringRequiredThe name of the person who started the export.
createdAtstring (date-time)RequiredWhen the export was requested.
finishedAtstring (date-time)RequiredNullableWhen it finished; null while it runs.
expiresAtstring (date-time)RequiredWhen its files are deleted (7 days after it was made).
skippedobjectRequiredSizes left out, each with its reason (
checking,unchecked,fidelity,fonts,lossy,pdf-licence,too-largeor an asset reason).filesarray of objectsRequiredOne entry for each size in the export.
Show child attributesHide child attributes
sizestringRequiredThe size’s key.
statusstringRequiredqueued,doneorfailed.Possible values
queueddonefailedbytesintegerRequiredNullableThe file’s size in bytes once done; otherwise null.
reasonstringRequiredNullableWhy the file failed; otherwise null.
Errors
| Status | Code | Meaning |
|---|---|---|
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
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 |
|
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
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)Requiredexportstring (uuid)Required
Returns
The export.
An object with:
idstring (uuid)RequiredThe export’s id.
roundintegerRequiredThe round exported.
formatstringRequiredThe file type:
png,jpgorpdf.Possible values
pngjpgpdfscalenumberRequiredThe scale the files were made at.
statusstringRequiredqueued,running,doneorfailed.Possible values
queuedrunningdonefailedbyobjectRequiredWho started the export.
Show child attributesHide child attributes
namestringRequiredThe name of the person who started the export.
createdAtstring (date-time)RequiredWhen the export was requested.
finishedAtstring (date-time)RequiredNullableWhen it finished; null while it runs.
expiresAtstring (date-time)RequiredWhen its files are deleted (7 days after it was made).
skippedobjectRequiredSizes left out, each with its reason (
checking,unchecked,fidelity,fonts,lossy,pdf-licence,too-largeor an asset reason).filesarray of objectsRequiredOne entry for each size in the export.
Show child attributesHide child attributes
sizestringRequiredThe size’s key.
statusstringRequiredqueued,doneorfailed.Possible values
queueddonefailedbytesintegerRequiredNullableThe file’s size in bytes once done; otherwise null.
reasonstringRequiredNullableWhy the file failed; otherwise null.
Errors
| Status | Code | Meaning |
|---|---|---|
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
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 |
|
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
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)Requiredexportstring (uuid)Required
Returns
The zip.
Errors
| Status | Code | Meaning |
|---|---|---|
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
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_readyapi_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
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)Requiredexportstring (uuid)RequiredsizestringRequired
Returns
The file.
Errors
| Status | Code | Meaning |
|---|---|---|
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
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 |
|
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). |