API reference
App runs
An app run is one go at building a campaign’s formats for one brand, started from inside InDesign, Figma or Canva, with the design app doing the building. Each format has its own outcome and, if the organisation keeps its work, kept files. A server run’s builds are listed here too, with source headless. To start a run from the API, see Server runs.
The App run object
The run object: a run for one brand, with the outcome of each format.
Attributes
idstringRequiredThe run’s id (16 hex characters).
campaignKeystringRequiredThe campaign the run was for.
siteCodestringRequiredThe brand the run was for.
statusstringRequiredPossible values
planningplannedfailedcancelledsourcestringRequiredThe app the run came from;
headlessfor a run made on the server from a saved master.Possible values
indesignfigmacanvaheadlesscreatedBystringOptionalThe creating user’s id; omitted when unknown.
createdByNamestringRequiredThe member’s name; “Member” when they have none, or “Canva user” on a Canva run; “Removed member” when they have left (or no creator was recorded). Never an email.
createdAtstring (date-time)RequiredWhen the run started.
runIdstringOptionalThe run this belongs to; brands started together share it. Omitted when there is none.
appVersionstringOptionalThe app build the run came from; omitted when unknown.
formatsarray of objectsRequiredThe outcome of each format of the run.
Show child attributesHide child attributes
formatKeystringRequiredThe format this outcome is for.
statusstringRequiredplanned: laid out;reviewed: laid out and checked;failed.Possible values
plannedreviewedfailedplanSourcestringRequiredplannerwhen Mestra made the layout,nonefor a failed format.Possible values
plannerfallbacknoneflagsarray of stringsRequiredThings the check found worth a look in the layout.
attemptsintegerRequiredHow many tries the layout took.
reviewAppliedbooleanRequiredWhether the review’s changes were applied to the layout.
updatedAtstring (date-time)RequiredWhen this outcome last changed.
layoutstringOptionalHow the layout was made; absent for a format stored before it was recorded, and for a failed format.
Possible values
plannedsharedownlayoutReasonstringOptionalWhy the layout is
own; only withown.Possible values
ruleslogofailReasonstringOptionalWhy a failed format failed, as a code; present only when
statusisfailed(and absent for formats stored before it was recorded).layout: the planner gave up or its answer was unusable.timeout: planning ran out of time.service: the AI service errored, could not be reached, or anything else.build: it was planned, but the app could not build it (reasonsays why). Never text.Possible values
layouttimeoutservicebuildreasonone ofOptionalWhy the format was left out or failed, when it was; see
reasonTextfor a sentence.One of
PlanReasonstringPossible values
wont_fitlegal_keptprice_keptcopy_lockedcopy_too_longrules_copylayout_checkinvalidBuildReasonstringPossible values
build_pasteboardbuild_fontbuild_busybuild_errorreasonTextstringOptionalOne short sentence for
reason, built from the format’s settings (or, for a build reason, the server’s own words naming the run’s app); never client copy. Absent forinvalid.filesarray of objectsOptionalPresent when the library holds files for the format (the thumbnail is the one named _thumb.png).
Show child attributesHide child attributes
idstring (uuid)RequiredThe file’s id: fetch it with
GET /library/files/{id}.namestringRequiredThe file’s name.
contentTypestringRequiredThe file’s media type.
sizeintegerRequiredThe file’s size in bytes.
reviewNotesobjectOptionalWhat one layout check of one format or size found. Kept only for organisations that keep their work, and kept encrypted.
Show child attributesHide child attributes
outcomestringRequiredamended: changes were applied;nothing: nothing needed changing;minor: only small points;notes: points were noted;not_applied: the review could not be applied (seereason);none: no review was made.Possible values
amendednothingminornotesnot_appliednonereasonstringOptionalWith not_applied only.
Possible values
no_visible_changetext_orderlayout_problemslayout_ruleissuesarray of objectsRequiredThe problems the review found.
Show child attributesHide child attributes
elementRefstringRequiredThe element’s scene id, or empty. A malformed ref, or one longer than 128 characters, is stored empty.
kindstringRequiredWhat kind of problem it is.
Possible values
overlapcrampedhierarchymisalignedcropBadunreadableoversetdeadSpaceorphanbrandNoteseveritystringRequiredlow,mediumorhigh.Possible values
lowmediumhighnotestringRequiredA short sentence describing the problem.
changesarray of objectsRequiredWith amended only: each applied change, its element named by role.
Show child attributesHide child attributes
namestringRequiredThe element changed, named by its role.
requestedobjectRequiredEach axis is within +-100000; the whole notes payload is at most 32 KiB as stored.
Show child attributesHide child attributes
dxnumberRequiredChange in left position.
dynumberRequiredChange in top position.
dwnumberRequiredChange in width.
dhnumberRequiredChange in height.
dTextSizenumberRequiredChange in text size.
actualobjectRequiredEach axis is within +-100000; the whole notes payload is at most 32 KiB as stored.
Show child attributesHide child attributes
dxnumberRequiredChange in left position.
dynumberRequiredChange in top position.
dwnumberRequiredChange in width.
dhnumberRequiredChange in height.
dTextSizenumberRequiredChange in text size.
limitstringRequiredWhat held the change back, if anything:
safe-margin,constraintorelement; empty when nothing did.Possible values
safe-marginconstraintelementbystringRequiredWhat made the change.
unitstringRequiredThe unit of the changes:
pxormm.Possible values
pxmmflagsarray of stringsRequiredFlag codes, in the shared vocabulary (
overset:<id>,offpage:<id>,rotated-fit:<id>,export-unavailable:<fmt>,focal-unapplied:<id>,z-order-failed:<id>, …). At most 40, and the whole payload at most 32 KiB as stored (canonical JSON).
sourceLinkobjectOptionalWhere a Canva or Figma run’s work lives, until it expires with the run’s files.
Show child attributesHide child attributes
appstringRequiredcanvaorfigma: the app the run was made in.Possible values
canvafigmaurlstring (uri)RequiredA link to the work in that app.
expiresAtstring (date-time)RequiredNullableWhen the link stops being kept; null under Keep everything.
masterNamestringOptionalThe name of the saved master the run was built from, when it is pinned to one.
Retrieve a run
Returns the run and what happened to each format: its status, flags and, when the organisation keeps its work, the files kept for it and the run’s sourceLink. A run of another organisation is a 404.
Path parameters
idstringRequiredThe run’s id. A run of another organisation is a
404.
Returns
The run.
Returns the App run object.
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 | “job not found”: no such run in this organisation (a run of another organisation is as unknown as a missing one). | |
409 | api_off |
|
500 | “could not read job”, “could not read the library” or “could not check token”. |
List all runs
Returns the organisation’s runs, newest first, as summaries: each run’s status and counts, without the outcome of each format (Retrieve a run has those). Filter by campaign, site, status, the app it came from, outcome and the day it started; page with limit and offset. total is how many runs match in all.
Query parameters
campaignstringOptionalFilter by campaign key.
sitestringOptionalFilter by brand code.
statusstringOptionalPossible values
planningplannedfailedcancelledsourcestringOptionalFilter by the app the run came from (
headlessfor a run made on the server).Possible values
indesignfigmacanvaheadlessoutcomestringOptionalbuilt: every format built with no flags, and the run neither failed nor cancelled;flagged: some format (not failed) has flags;failed: the run failed, or some format did.Possible values
builtflaggedfailedfromstring (date)OptionalFirst UTC day the run was started, inclusive.
tostring (date)OptionalLast UTC day the run was started, inclusive.
limitintegerOptional1 to 200.
Default
50offsetintegerOptionalDefault
0statestringOptionalWith
grouped=1: only runs in this state, each run counted once asbuilding, elsefailed, elselook(needs a look), elseready. Withoutgrouped=1it is not read.Possible values
readybuildinglookfailedgroupedstringOptional1gives one row per run instead of one per brand: the row adds up the run’s brands (matching the filters), withbrands(their brand codes) andjobIdsadded, andtotalcounts runs. A run with no run id is a row on its own.Possible values
1
Returns
Run summaries (no per-format outcomes, but their counts), and how many runs match in all.
An object with:
jobsarray of objectsRequiredShow child attributesHide child attributes
idstringRequiredThe run’s id (16 hex characters).
campaignKeystringRequiredThe campaign the run was for.
siteCodestringRequiredThe brand the run was for.
statusstringRequiredPossible values
planningplannedfailedcancelledsourcestringRequiredThe app the run came from;
headlessfor a run made on the server from a saved master.Possible values
indesignfigmacanvaheadlesscreatedBystringOptionalThe creating user’s id; omitted when unknown.
createdByNamestringRequiredThe member’s name; “Member” when they have none, or “Canva user” on a Canva run; “Removed member” when they have left (or no creator was recorded). Never an email.
createdAtstring (date-time)RequiredWhen the run started.
runIdstringOptionalThe run this belongs to; brands started together share it. Omitted when there is none.
appVersionstringOptionalThe app build the run came from; omitted when unknown.
formatCountsobjectRequiredThe run’s formats, each counted once - failed, else flagged (any flag), else built.
Show child attributesHide child attributes
builtintegerRequiredFormats made with no flags.
flaggedintegerRequiredFormats made, but with at least one flag worth a look.
failedintegerRequiredFormats that could not be made.
hasFilesbooleanRequiredThe library keeps files (not just a thumbnail) for the run.
notesintegerRequiredHow many issues and distinct flags (element flags once per code) the run’s kept review notes hold, across its formats.
brandsarray of stringsOptionalWith
grouped=1: the brand codes of the run’s brands.jobIdsarray of stringsOptionalWith
grouped=1: the ids of the run’s brands, by brand code.
totalintegerRequiredEvery run the filters match, limit and offset aside.
Errors
| Status | Code | Meaning |
|---|---|---|
400 | “limit must be 1 to 200”, “offset must be 0 or more”, “source must be indesign, figma, canva or headless”, “outcome must be built, flagged or failed”, “state must be ready, building, look or failed”, “from must be a date (YYYY-MM-DD)”, “to must be a date (YYYY-MM-DD)” or “to must not be before from”. | |
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 list jobs” or “could not check token”. |