Skip to content

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

  • idstringRequired

    The run’s id (16 hex characters).

  • campaignKeystringRequired

    The campaign the run was for.

  • siteCodestringRequired

    The brand the run was for.

  • statusstringRequired

    Possible valuesplanningplannedfailedcancelled

  • sourcestringRequired

    The app the run came from; headless for a run made on the server from a saved master.

    Possible valuesindesignfigmacanvaheadless

  • createdBystringOptional

    The creating user’s id; omitted when unknown.

  • createdByNamestringRequired

    The 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)Required

    When the run started.

  • runIdstringOptional

    The run this belongs to; brands started together share it. Omitted when there is none.

  • appVersionstringOptional

    The app build the run came from; omitted when unknown.

  • formatsarray of objectsRequired

    The outcome of each format of the run.

    Show child attributesHide child attributes
    • formatKeystringRequired

      The format this outcome is for.

    • statusstringRequired

      planned: laid out; reviewed: laid out and checked; failed.

      Possible valuesplannedreviewedfailed

    • planSourcestringRequired

      planner when Mestra made the layout, none for a failed format.

      Possible valuesplannerfallbacknone

    • flagsarray of stringsRequired

      Things the check found worth a look in the layout.

    • attemptsintegerRequired

      How many tries the layout took.

    • reviewAppliedbooleanRequired

      Whether the review’s changes were applied to the layout.

    • updatedAtstring (date-time)Required

      When this outcome last changed.

    • layoutstringOptional

      How the layout was made; absent for a format stored before it was recorded, and for a failed format.

      Possible valuesplannedsharedown

    • layoutReasonstringOptional

      Why the layout is own; only with own.

      Possible valuesruleslogo

    • failReasonstringOptional

      Why a failed format failed, as a code; present only when status is failed (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 (reason says why). Never text.

      Possible valueslayouttimeoutservicebuild

    • reasonone ofOptional

      Why the format was left out or failed, when it was; see reasonText for a sentence.

      One of

      PlanReason string

      Possible valueswont_fitlegal_keptprice_keptcopy_lockedcopy_too_longrules_copylayout_checkinvalid

      BuildReason string

      Possible valuesbuild_pasteboardbuild_fontbuild_busybuild_error

    • reasonTextstringOptional

      One 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 for invalid.

    • filesarray of objectsOptional

      Present when the library holds files for the format (the thumbnail is the one named _thumb.png).

      Show child attributesHide child attributes
      • idstring (uuid)Required

        The file’s id: fetch it with GET /library/files/{id}.

      • namestringRequired

        The file’s name.

      • contentTypestringRequired

        The file’s media type.

      • sizeintegerRequired

        The file’s size in bytes.

    • reviewNotesobjectOptional

      What 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
      • outcomestringRequired

        amended: changes were applied; nothing: nothing needed changing; minor: only small points; notes: points were noted; not_applied: the review could not be applied (see reason); none: no review was made.

        Possible valuesamendednothingminornotesnot_appliednone

      • reasonstringOptional

        With not_applied only.

        Possible valuesno_visible_changetext_orderlayout_problemslayout_rule

      • issuesarray of objectsRequired

        The problems the review found.

        Show child attributesHide child attributes
        • elementRefstringRequired

          The element’s scene id, or empty. A malformed ref, or one longer than 128 characters, is stored empty.

        • kindstringRequired

          What kind of problem it is.

          Possible valuesoverlapcrampedhierarchymisalignedcropBadunreadableoversetdeadSpaceorphanbrandNote

        • severitystringRequired

          low, medium or high.

          Possible valueslowmediumhigh

        • notestringRequired

          A short sentence describing the problem.

      • changesarray of objectsRequired

        With amended only: each applied change, its element named by role.

        Show child attributesHide child attributes
        • namestringRequired

          The element changed, named by its role.

        • requestedobjectRequired

          Each axis is within +-100000; the whole notes payload is at most 32 KiB as stored.

          Show child attributesHide child attributes
          • dxnumberRequired

            Change in left position.

          • dynumberRequired

            Change in top position.

          • dwnumberRequired

            Change in width.

          • dhnumberRequired

            Change in height.

          • dTextSizenumberRequired

            Change in text size.

        • actualobjectRequired

          Each axis is within +-100000; the whole notes payload is at most 32 KiB as stored.

          Show child attributesHide child attributes
          • dxnumberRequired

            Change in left position.

          • dynumberRequired

            Change in top position.

          • dwnumberRequired

            Change in width.

          • dhnumberRequired

            Change in height.

          • dTextSizenumberRequired

            Change in text size.

        • limitstringRequired

          What held the change back, if anything: safe-margin, constraint or element; empty when nothing did.

          Possible valuessafe-marginconstraintelement

        • bystringRequired

          What made the change.

      • unitstringRequired

        The unit of the changes: px or mm.

        Possible valuespxmm

      • flagsarray of stringsRequired

        Flag 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).

  • sourceLinkobjectOptional

    Where a Canva or Figma run’s work lives, until it expires with the run’s files.

    Show child attributesHide child attributes
    • appstringRequired

      canva or figma: the app the run was made in.

      Possible valuescanvafigma

    • urlstring (uri)Required

      A link to the work in that app.

    • expiresAtstring (date-time)RequiredNullable

      When the link stops being kept; null under Keep everything.

  • masterNamestringOptional

    The name of the saved master the run was built from, when it is pinned to one.

Retrieve a run

PermissionRuns · Read

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

  • idstringRequired

    The run’s id. A run of another organisation is a 404.

Returns

The run.

Returns the App run object.

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

“job not found”: no such run in this organisation (a run of another organisation is as unknown as a missing one).

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 read job”, “could not read the library” or “could not check token”.

List all runs

PermissionRuns · Read

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

  • campaignstringOptional

    Filter by campaign key.

  • sitestringOptional

    Filter by brand code.

  • statusstringOptional

    Possible valuesplanningplannedfailedcancelled

  • sourcestringOptional

    Filter by the app the run came from (headless for a run made on the server).

    Possible valuesindesignfigmacanvaheadless

  • outcomestringOptional

    built: 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 valuesbuiltflaggedfailed

  • fromstring (date)Optional

    First UTC day the run was started, inclusive.

  • tostring (date)Optional

    Last UTC day the run was started, inclusive.

  • limitintegerOptional

    1 to 200.

    Default50

  • offsetintegerOptional

    Default0

  • statestringOptional

    With grouped=1: only runs in this state, each run counted once as building, else failed, else look (needs a look), else ready. Without grouped=1 it is not read.

    Possible valuesreadybuildinglookfailed

  • groupedstringOptional

    1 gives one row per run instead of one per brand: the row adds up the run’s brands (matching the filters), with brands (their brand codes) and jobIds added, and total counts runs. A run with no run id is a row on its own.

    Possible values1

Returns

Run summaries (no per-format outcomes, but their counts), and how many runs match in all.

An object with:

  • jobsarray of objectsRequired
    Show child attributesHide child attributes
    • idstringRequired

      The run’s id (16 hex characters).

    • campaignKeystringRequired

      The campaign the run was for.

    • siteCodestringRequired

      The brand the run was for.

    • statusstringRequired

      Possible valuesplanningplannedfailedcancelled

    • sourcestringRequired

      The app the run came from; headless for a run made on the server from a saved master.

      Possible valuesindesignfigmacanvaheadless

    • createdBystringOptional

      The creating user’s id; omitted when unknown.

    • createdByNamestringRequired

      The 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)Required

      When the run started.

    • runIdstringOptional

      The run this belongs to; brands started together share it. Omitted when there is none.

    • appVersionstringOptional

      The app build the run came from; omitted when unknown.

    • formatCountsobjectRequired

      The run’s formats, each counted once - failed, else flagged (any flag), else built.

      Show child attributesHide child attributes
      • builtintegerRequired

        Formats made with no flags.

      • flaggedintegerRequired

        Formats made, but with at least one flag worth a look.

      • failedintegerRequired

        Formats that could not be made.

    • hasFilesbooleanRequired

      The library keeps files (not just a thumbnail) for the run.

    • notesintegerRequired

      How many issues and distinct flags (element flags once per code) the run’s kept review notes hold, across its formats.

    • brandsarray of stringsOptional

      With grouped=1: the brand codes of the run’s brands.

    • jobIdsarray of stringsOptional

      With grouped=1: the ids of the run’s brands, by brand code.

  • totalintegerRequired

    Every run the filters match, limit and offset aside.

Errors

StatusCodeMeaning
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”.

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 list jobs” or “could not check token”.