Skip to content

API reference

Campaigns

The Campaign object

The campaign object. A campaign is identified by its key.

Attributes

  • namestringRequired

    The campaign’s display name.

  • keystringRequired

    The campaign’s key: its identifier in URLs and in runs. Letters, digits and dashes, unique in the organisation.

  • externalRefobjectOptional

    A link to the same campaign in another system, for your own reference. Mestra does not read from it.

    Show child attributesHide child attributes
    • systemstringOptional

      The name of the other system (for example Asana). Empty when there is none.

    • idstringOptionalNullable

      The campaign’s id in that system, or null.

    • urlstringOptionalNullable

      A link to the campaign in that system, or null.

    • syncedAtstringOptionalNullable

      When the link was last refreshed from that system, or null.

  • formatSetstringOptional

    The key of the format set this campaign makes: the group of sizes each run builds. Optional: a campaign can list its sizes in formats alone.

  • formatsarray of stringsOptionalNullable

    The campaign’s own sizes, as format keys, added to the format set’s. Each key once. A campaign with neither a format set nor formats has no sizes until some are added.

  • centresarray of stringsRequiredNullable

    The codes of the brands this campaign runs in. At least one.

  • copyobjectOptionalNullable

    Fixed wording for the campaign, by role (for example headline or cta). A run uses it exactly as written. Each value is up to 2,000 characters.

  • qrUrlstringOptional

    The address a QR code in the campaign’s artwork points to. Empty for none.

  • startDatestringOptional

    Optional, YYYY-MM-DD: prefills a publish to screens.

  • endDatestringOptional

    Optional, YYYY-MM-DD, not before startDate.

  • notesstringOptional

    Free-text notes for this campaign that the layout planner follows, up to 4,000 characters.

  • brandRulesOverrideobjectOptionalNullable

    Brand rules that replace the brand’s own for this campaign; null to use the brand’s.

    Show child attributesHide child attributes
    • logoobjectOptionalNullable

      Rules for the logo; null for none.

      Show child attributesHide child attributes
      • minWidthPctnumberOptional

        The smallest logo width, as a share of the page width (0.12 is 12%).

      • clearSpacePctnumberOptional

        The clear space kept around the logo, as a share (for example 0.5).

    • typographyobjectOptionalNullable

      Rules for type; null for none.

      Show child attributesHide child attributes
      • allowedFamiliesarray of stringsOptionalNullable

        The font families layouts may use. Null for any.

      • headlineMaxLinesintegerOptional

        The most lines a headline may take.

    • alignmentobjectOptionalNullable

      Rules for alignment; null for none.

      Show child attributesHide child attributes
      • gridnumberOptional

        The grid that positions snap to.

    • spacingobjectOptionalNullable

      Rules for spacing; null for none.

      Show child attributesHide child attributes
      • minGapPctnumberOptional

        The smallest gap between elements, as a share of the page height (0.02 is 2%).

    • notesstringOptional

      Free-text brand notes the layout planner follows, up to 4,000 characters. Set on a brand; a campaign’s override must leave it empty (put campaign notes on the campaign).

  • centreFormatsmap of objectsOptional

    Per-centre changes to the format set, by brand code: sizes added and sizes skipped. These win over the brand’s own lists.

    Show child attributesHide child attributes
    • addarray of stringsOptional
    • skiparray of stringsOptional
  • copyRowsarray of objectsOptionalNullable

    The campaign’s copy sheet: copy for one brand and format, used word for word. For a brand and format, a run takes the campaign’s copy, then the national row for all formats, the national row for the format, the brand’s row for all formats and the brand’s row for the format, each later one winning per role. At most 5,000 rows, one per brand and format.

    Show child attributesHide child attributes
    • centrestringOptional

      A brand code. Empty for every brand.

    • formatstringOptional

      A format key. Empty for every format.

    • copyobjectRequired

      Text by role (headline, subhead, body, legal, cta), up to 2,000 characters each.

Retrieve a campaign

PermissionCampaigns · Read

Returns the campaign together with the formats and sites it uses. The key no-campaign is readable without Campaigns · Read by a key that has Runs · Write or Designs · Write and Brand · Read (it lists only brands and sizes; any other campaign key still needs Campaigns · Read). A site code that isn’t defined is listed under missingSites instead of being dropped. limits says how many reviews and review passes the organisation has.

The key no-campaign is not a stored campaign: it answers the same shape for a run that belongs to none. campaign is {"key": "no-campaign", "name": "No campaign", "centres": [...]} with every brand of the organisation, formats is every size the organisation has, and sites is every brand (with its uploadedLogos). There are no siteSizes or extraFormats: each brand gets each size. A run with no campaign names its brands in sites and its sizes in formats and customSizes (POST /masters/{id}/runs with campaignKey no-campaign; customSizes is a list of {"w", "h", "unit"} with unit px or mm, each made a format of the organisation if it has none like it, see POST /formats/custom).

Path parameters

  • keystringRequired

    The document’s key (a brand’s code).

Returns

The campaign.

An object with:

  • campaignobjectRequired

    The campaign object. A campaign is identified by its key.

    Show child attributesHide child attributes
    • namestringRequired

      The campaign’s display name.

    • keystringRequired

      The campaign’s key: its identifier in URLs and in runs. Letters, digits and dashes, unique in the organisation.

    • externalRefobjectOptional

      A link to the same campaign in another system, for your own reference. Mestra does not read from it.

      Show child attributesHide child attributes
      • systemstringOptional

        The name of the other system (for example Asana). Empty when there is none.

      • idstringOptionalNullable

        The campaign’s id in that system, or null.

      • urlstringOptionalNullable

        A link to the campaign in that system, or null.

      • syncedAtstringOptionalNullable

        When the link was last refreshed from that system, or null.

    • formatSetstringOptional

      The key of the format set this campaign makes: the group of sizes each run builds. Optional: a campaign can list its sizes in formats alone.

    • formatsarray of stringsOptionalNullable

      The campaign’s own sizes, as format keys, added to the format set’s. Each key once. A campaign with neither a format set nor formats has no sizes until some are added.

    • centresarray of stringsRequiredNullable

      The codes of the brands this campaign runs in. At least one.

    • copyobjectOptionalNullable

      Fixed wording for the campaign, by role (for example headline or cta). A run uses it exactly as written. Each value is up to 2,000 characters.

    • qrUrlstringOptional

      The address a QR code in the campaign’s artwork points to. Empty for none.

    • startDatestringOptional

      Optional, YYYY-MM-DD: prefills a publish to screens.

    • endDatestringOptional

      Optional, YYYY-MM-DD, not before startDate.

    • notesstringOptional

      Free-text notes for this campaign that the layout planner follows, up to 4,000 characters.

    • brandRulesOverrideobjectOptionalNullable

      Brand rules that replace the brand’s own for this campaign; null to use the brand’s.

      Show child attributesHide child attributes
      • logoobjectOptionalNullable

        Rules for the logo; null for none.

        Show child attributesHide child attributes
        • minWidthPctnumberOptional

          The smallest logo width, as a share of the page width (0.12 is 12%).

        • clearSpacePctnumberOptional

          The clear space kept around the logo, as a share (for example 0.5).

      • typographyobjectOptionalNullable

        Rules for type; null for none.

        Show child attributesHide child attributes
        • allowedFamiliesarray of stringsOptionalNullable

          The font families layouts may use. Null for any.

        • headlineMaxLinesintegerOptional

          The most lines a headline may take.

      • alignmentobjectOptionalNullable

        Rules for alignment; null for none.

        Show child attributesHide child attributes
        • gridnumberOptional

          The grid that positions snap to.

      • spacingobjectOptionalNullable

        Rules for spacing; null for none.

        Show child attributesHide child attributes
        • minGapPctnumberOptional

          The smallest gap between elements, as a share of the page height (0.02 is 2%).

      • notesstringOptional

        Free-text brand notes the layout planner follows, up to 4,000 characters. Set on a brand; a campaign’s override must leave it empty (put campaign notes on the campaign).

    • centreFormatsmap of objectsOptional

      Per-centre changes to the format set, by brand code: sizes added and sizes skipped. These win over the brand’s own lists.

      Show child attributesHide child attributes
      • addarray of stringsOptional
      • skiparray of stringsOptional
    • copyRowsarray of objectsOptionalNullable

      The campaign’s copy sheet: copy for one brand and format, used word for word. For a brand and format, a run takes the campaign’s copy, then the national row for all formats, the national row for the format, the brand’s row for all formats and the brand’s row for the format, each later one winning per role. At most 5,000 rows, one per brand and format.

      Show child attributesHide child attributes
      • centrestringOptional

        A brand code. Empty for every brand.

      • formatstringOptional

        A format key. Empty for every format.

      • copyobjectRequired

        Text by role (headline, subhead, body, legal, cta), up to 2,000 characters each.

  • limitsobjectRequired

    The organisation’s review slots (reviews) and how many review passes its apps may run (passes).

    Show child attributesHide child attributes
    • reviewsintegerRequired
    • passesintegerRequired
  • formatsarray of objectsRequired
    Show child attributesHide child attributes
    • namestringRequired

      The format’s display name.

    • keystringRequired

      The format’s key: its identifier in format sets and runs. Unique in the organisation.

    • widthnumberRequired

      Width, in unit.

    • heightnumberRequired

      Height, in unit.

    • unitstringRequired

      The unit of width, height, bleed and safeMargin: px, mm or pt. Type sizes are always in points.

      Possible valuespxmmpt

    • dpinumberOptionalNullable

      Resolution in dots per inch. Needed for mm formats; usually null for px and pt.

    • exportScaleintegerOptional

      px and pt formats: exported pixels per page unit: 0 (the default) or 1 to 3, at most 16 MP in all. 0 or absent is the family default (2 for social and web when that fits 16 MP, else 1). Campaign answers always carry it resolved.

    • bleednumberOptional

      Bleed beyond the trim, in unit. A format with a bleed is a print size.

    • safeMarginnumberOptional

      The margin kept clear of important content, in unit.

    • familystringOptional

      The kind of output (for example print, social, web or screen). It decides defaults such as the export scale.

    • requirearray of stringsOptionalNullable

      Elements every layout of this format must keep: cta, qr. Null or empty for none.

    • droparray of stringsOptionalNullable

      Roles left out of this format (for example subhead). Null or empty for none.

    • minTypeSizeobjectOptionalNullable

      Smallest type size per role, in points.

    • exportFormatsarray of stringsOptionalNullable

      The file types a review of this format can export (for example png, jpg, pdf). Null for the defaults.

    • reviewPolicystringRequired

      always checks every layout of this format; skip-if-clean skips the check when the layout is already clean.

    • copyOverridesobjectOptionalNullable

      Wording that replaces the campaign’s own for this format, by role. Each value is up to 2,000 characters.

  • extraFormatsarray of objectsOptional

    Full definitions of the formats that appear in a brand’s siteSizes list but not in formats. Present only when there are any.

    Show child attributesHide child attributes
    • namestringRequired

      The format’s display name.

    • keystringRequired

      The format’s key: its identifier in format sets and runs. Unique in the organisation.

    • widthnumberRequired

      Width, in unit.

    • heightnumberRequired

      Height, in unit.

    • unitstringRequired

      The unit of width, height, bleed and safeMargin: px, mm or pt. Type sizes are always in points.

      Possible valuespxmmpt

    • dpinumberOptionalNullable

      Resolution in dots per inch. Needed for mm formats; usually null for px and pt.

    • exportScaleintegerOptional

      px and pt formats: exported pixels per page unit: 0 (the default) or 1 to 3, at most 16 MP in all. 0 or absent is the family default (2 for social and web when that fits 16 MP, else 1). Campaign answers always carry it resolved.

    • bleednumberOptional

      Bleed beyond the trim, in unit. A format with a bleed is a print size.

    • safeMarginnumberOptional

      The margin kept clear of important content, in unit.

    • familystringOptional

      The kind of output (for example print, social, web or screen). It decides defaults such as the export scale.

    • requirearray of stringsOptionalNullable

      Elements every layout of this format must keep: cta, qr. Null or empty for none.

    • droparray of stringsOptionalNullable

      Roles left out of this format (for example subhead). Null or empty for none.

    • minTypeSizeobjectOptionalNullable

      Smallest type size per role, in points.

    • exportFormatsarray of stringsOptionalNullable

      The file types a review of this format can export (for example png, jpg, pdf). Null for the defaults.

    • reviewPolicystringRequired

      always checks every layout of this format; skip-if-clean skips the check when the layout is already clean.

    • copyOverridesobjectOptionalNullable

      Wording that replaces the campaign’s own for this format, by role. Each value is up to 2,000 characters.

  • siteSizesobjectOptional

    The sizes to build for each brand whose list differs from formats (the campaign’s format set), by brand code. Brands on the format set are not listed. Present only when at least one differs.

  • sitesarray of objectsRequired
    Show child attributesHide child attributes
    • namestringOptional

      The site’s display name.

    • codestringOptional

      The brand’s code.

    • logosobjectOptionalNullable

      The logo files named in the configuration, by variant. Uploaded logos are in uploadedLogos.

    • brandColoursarray of stringsOptionalNullable

      The brand’s brand colours as hex values. Null for none.

    • colourInksobjectOptional

      CMYK inks for brand colours, keyed by the lower-case hex value (for example #1b3a5c); four numbers from 0 to 1 (C, M, Y, K). Each key must be one of brandColours. Omitted when none are set.

    • colourNamesobjectOptional

      Optional names for brand colours, keyed by the lower-case hex value (for example #1b3a5c): {"#1b3a5c": "Navy"}. Each key must be one of brandColours; a colour with no entry is unnamed. A name is at most 40 characters with no quotes or angle brackets (refused with 400 and field colourNames). brandColours stays a list of hex strings, so clients that send only hex values keep working. Omitted when none are set.

    • qrBaseUrlstringOptional

      The address QR codes for this brand start from. Empty for none.

    • brandRulesobjectOptional
      Show child attributesHide child attributes
      • logoobjectOptionalNullable

        Rules for the logo; null for none.

        Show child attributesHide child attributes
        • minWidthPctnumberOptional

          The smallest logo width, as a share of the page width (0.12 is 12%).

        • clearSpacePctnumberOptional

          The clear space kept around the logo, as a share (for example 0.5).

      • typographyobjectOptionalNullable

        Rules for type; null for none.

        Show child attributesHide child attributes
        • allowedFamiliesarray of stringsOptionalNullable

          The font families layouts may use. Null for any.

        • headlineMaxLinesintegerOptional

          The most lines a headline may take.

      • alignmentobjectOptionalNullable

        Rules for alignment; null for none.

        Show child attributesHide child attributes
        • gridnumberOptional

          The grid that positions snap to.

      • spacingobjectOptionalNullable

        Rules for spacing; null for none.

        Show child attributesHide child attributes
        • minGapPctnumberOptional

          The smallest gap between elements, as a share of the page height (0.02 is 2%).

      • notesstringOptional

        Free-text brand notes the layout planner follows, up to 4,000 characters. Set on a brand; a campaign’s override must leave it empty (put campaign notes on the campaign).

    • formatsAddarray of stringsOptional

      Format keys added to every campaign’s format set for this brand.

    • formatsSkiparray of stringsOptional

      Format keys left out of every campaign’s format set for this brand.

    • uploadedLogosarray of objectsRequired

      The uploaded variants (primary, then reversed); [] when none or logos aren’t set up.

      Show child attributesHide child attributes
      • variantstringRequired

        primary or reversed: the slot the logo is uploaded to.

        Possible valuesprimaryreversed

      • contentTypestringRequired

        image/png or image/svg+xml.

        Possible valuesimage/pngimage/svg+xml

      • sha256stringRequired

        The file’s SHA-256, in lower-case hex.

      • luminancenumberOptionalNullable

        The logo’s mean relative luminance (WCAG; 0 black, 1 white), measured when it was uploaded; null when it can’t be measured. An app picks the upload that contrasts more with the artwork by this, not by the slot name (“reversed” is only a name).

      • trimobjectOptionalNullable

        The box of the logo’s visible artwork (alpha at least 8/255) as shares of its canvas, measured when it was uploaded; null for an SVG or when it can’t be measured. An app fits this box, not the canvas, into the logo frame, so a transparent margin doesn’t shrink the logo.

        Show child attributesHide child attributes
        • xnumberRequired

          Left edge of the visible artwork, as a share (0 to 1) of the logo’s width.

        • ynumberRequired

          Top edge of the visible artwork, as a share (0 to 1) of the logo’s height.

        • wnumberRequired

          Width of the visible artwork, as a share (0 to 1) of the logo’s width.

        • hnumberRequired

          Height of the visible artwork, as a share (0 to 1) of the logo’s height.

  • missingSitesarray of stringsOptional

    Present only when a brand code does not resolve.

Errors

StatusCodeMeaning
400

The campaign names a format set or format the organisation doesn’t have; the message says which.

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

“unknown campaign”

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 load configuration”, “could not resolve the campaign’s formats”, “could not read logos” or “could not check token”.

Create or update a campaign

PermissionCampaigns · Write

Creates the campaign with this key, or replaces it if it already exists. The body is strict JSON: unknown fields are refused, and its key must equal the one in the path. Copy values are up to 2,000 characters. Send X-Mestra-Create: 1 to insist on creating (a key that already exists is 409), or X-Mestra-Updated-At with the value from your last save to replace safely (412 when someone else changed it first). The answer carries the new X-Mestra-Updated-At.

Path parameters

  • keystringRequired

    The document’s key (a brand’s code).

Headers

  • X-Mestra-Updated-Atstring (date-time)Optional

    The X-Mestra-Updated-At your last save of this document answered with. The write goes ahead only if the document is unchanged since, otherwise 412 (a document deleted since counts as changed). Send either this or X-Mestra-Create, not both.

  • X-Mestra-CreatestringOptional

    1: the write creates the document; a taken key is 409. A DELETE ignores it.

    Possible values1

Body parameters

  • namestringRequired

    The campaign’s display name.

  • keystringRequired

    The campaign’s key: its identifier in URLs and in runs. Letters, digits and dashes, unique in the organisation.

  • externalRefobjectOptional

    A link to the same campaign in another system, for your own reference. Mestra does not read from it.

    Show child attributesHide child attributes
    • systemstringOptional

      The name of the other system (for example Asana). Empty when there is none.

    • idstringOptionalNullable

      The campaign’s id in that system, or null.

    • urlstringOptionalNullable

      A link to the campaign in that system, or null.

    • syncedAtstringOptionalNullable

      When the link was last refreshed from that system, or null.

  • formatSetstringOptional

    The key of the format set this campaign makes: the group of sizes each run builds. Optional: a campaign can list its sizes in formats alone.

  • formatsarray of stringsOptionalNullable

    The campaign’s own sizes, as format keys, added to the format set’s. Each key once. A campaign with neither a format set nor formats has no sizes until some are added.

  • centresarray of stringsRequiredNullable

    The codes of the brands this campaign runs in. At least one.

  • copyobjectOptionalNullable

    Fixed wording for the campaign, by role (for example headline or cta). A run uses it exactly as written. Each value is up to 2,000 characters.

  • qrUrlstringOptional

    The address a QR code in the campaign’s artwork points to. Empty for none.

  • startDatestringOptional

    Optional, YYYY-MM-DD: prefills a publish to screens.

  • endDatestringOptional

    Optional, YYYY-MM-DD, not before startDate.

  • notesstringOptional

    Free-text notes for this campaign that the layout planner follows, up to 4,000 characters.

  • brandRulesOverrideobjectOptionalNullable

    Brand rules that replace the brand’s own for this campaign; null to use the brand’s.

    Show child attributesHide child attributes
    • logoobjectOptionalNullable

      Rules for the logo; null for none.

      Show child attributesHide child attributes
      • minWidthPctnumberOptional

        The smallest logo width, as a share of the page width (0.12 is 12%).

      • clearSpacePctnumberOptional

        The clear space kept around the logo, as a share (for example 0.5).

    • typographyobjectOptionalNullable

      Rules for type; null for none.

      Show child attributesHide child attributes
      • allowedFamiliesarray of stringsOptionalNullable

        The font families layouts may use. Null for any.

      • headlineMaxLinesintegerOptional

        The most lines a headline may take.

    • alignmentobjectOptionalNullable

      Rules for alignment; null for none.

      Show child attributesHide child attributes
      • gridnumberOptional

        The grid that positions snap to.

    • spacingobjectOptionalNullable

      Rules for spacing; null for none.

      Show child attributesHide child attributes
      • minGapPctnumberOptional

        The smallest gap between elements, as a share of the page height (0.02 is 2%).

    • notesstringOptional

      Free-text brand notes the layout planner follows, up to 4,000 characters. Set on a brand; a campaign’s override must leave it empty (put campaign notes on the campaign).

  • centreFormatsmap of objectsOptional

    Per-centre changes to the format set, by brand code: sizes added and sizes skipped. These win over the brand’s own lists.

    Show child attributesHide child attributes
    • addarray of stringsOptional
    • skiparray of stringsOptional
  • copyRowsarray of objectsOptionalNullable

    The campaign’s copy sheet: copy for one brand and format, used word for word. For a brand and format, a run takes the campaign’s copy, then the national row for all formats, the national row for the format, the brand’s row for all formats and the brand’s row for the format, each later one winning per role. At most 5,000 rows, one per brand and format.

    Show child attributesHide child attributes
    • centrestringOptional

      A brand code. Empty for every brand.

    • formatstringOptional

      A format key. Empty for every format.

    • copyobjectRequired

      Text by role (headline, subhead, body, legal, cta), up to 2,000 characters each.

Returns

The stored (canonical) document.

Returns the Campaign object.

Errors

StatusCodeMeaning
400

A value is refused. The answer is {"error": "<sentence>", "field": "<name>"} for the first refused value, for example {"error":"Add a name.","field":"name"}, {"error":"Enter a full web address starting with https://.","field":"qrBaseUrl"} or {"error":"Width must be more than 0.","field":"width"}. Nothing is saved.

The rules: every kind needs a non-blank name; a brand’s qrBaseUrl and a campaign’s qrUrl and externalRef.url, when not empty, must be full http or https addresses; a campaign’s startDate and endDate, when set, must be real dates (“Enter a valid date.”), and endDate can’t be before startDate; a campaign’s formatSet is optional, its formats (format keys, added to the set’s) must each exist and be listed once (a campaign with neither has no sizes until some are added), and it needs at least one brand (“Choose at least one brand.”); a format’s width, height, unit, dpi (for mm), safe margin, review policy and lists must be valid; a campaign’s brandRulesOverride.typography may not set only one of headlineMaxLines and allowedFamilies.

Without a field, the answer is a plain sentence: the change would leave a reference to something that doesn’t exist, the key isn’t allowed (“Keys use letters, numbers, dots, dashes and underscores, up to 64 characters, starting with a letter or number.”), or the headers are wrong (“Send X-Mestra-Create or X-Mestra-Updated-At, not both.”, “X-Mestra-Updated-At must be an updatedAt value from this service.” or “X-Mestra-Create must be 1.”).

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.

409api_off

“That key is already taken.” (X-Mestra-Create: 1 and a document with that key exists). Nothing is saved. With an API key, also api_off (“Turn on the API in Developer → API and MCP first.”) when an owner has turned the API off.

412

“Someone else changed this. Reload to see their changes.” (X-Mestra-Updated-At is not the document’s current updatedAt, or the document is gone). Nothing is saved.

413

“body exceeds limit (1048576 bytes)”

500

“could not save configuration”, “could not read configuration” (re-reading after the change), “could not check token”, or “Couldn’t save that change. Try again.” (the change could not be recorded, so it was not made). Nothing is half-saved: try again.

501

“configuration is read-only here”: this server can’t change configuration.

List all campaigns

PermissionCampaigns · Read

Returns every campaign the organisation has, sorted by key. Send limit or offset to page through them: the answer is then that page, and the X-Total-Count header says how many there are in all.

Query parameters

  • limitintegerOptional

    1 to 200; every campaign when neither limit nor offset is sent.

    Default200

  • offsetintegerOptional

    Default0

Returns

Every campaign, or the page asked for.

Returns a list of Campaign objects.

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

Delete a campaign

PermissionCampaigns · Write

Deletes the campaign. Runs and reviews already made from it are not affected.

Path parameters

  • keystringRequired

    The document’s key (a brand’s code).

Headers

  • X-Mestra-Updated-Atstring (date-time)Optional

    The X-Mestra-Updated-At your last save of this document answered with. The write goes ahead only if the document is unchanged since, otherwise 412 (a document deleted since counts as changed). Send either this or X-Mestra-Create, not both.

  • X-Mestra-CreatestringOptional

    1: the write creates the document; a taken key is 409. A DELETE ignores it.

    Possible values1

Returns

Deleted.

Errors

StatusCodeMeaning
400

A value is refused. The answer is {"error": "<sentence>", "field": "<name>"} for the first refused value, for example {"error":"Add a name.","field":"name"}, {"error":"Enter a full web address starting with https://.","field":"qrBaseUrl"} or {"error":"Width must be more than 0.","field":"width"}. Nothing is saved.

The rules: every kind needs a non-blank name; a brand’s qrBaseUrl and a campaign’s qrUrl and externalRef.url, when not empty, must be full http or https addresses; a campaign’s startDate and endDate, when set, must be real dates (“Enter a valid date.”), and endDate can’t be before startDate; a campaign’s formatSet is optional, its formats (format keys, added to the set’s) must each exist and be listed once (a campaign with neither has no sizes until some are added), and it needs at least one brand (“Choose at least one brand.”); a format’s width, height, unit, dpi (for mm), safe margin, review policy and lists must be valid; a campaign’s brandRulesOverride.typography may not set only one of headlineMaxLines and allowedFamilies.

Without a field, the answer is a plain sentence: the change would leave a reference to something that doesn’t exist, the key isn’t allowed (“Keys use letters, numbers, dots, dashes and underscores, up to 64 characters, starting with a letter or number.”), or the headers are wrong (“Send X-Mestra-Create or X-Mestra-Updated-At, not both.”, “X-Mestra-Updated-At must be an updatedAt value from this service.” or “X-Mestra-Create must be 1.”).

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

“unknown campaign”

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.

412

“Someone else changed this. Reload to see their changes.” (X-Mestra-Updated-At is not the document’s current updatedAt, or the document is gone). Nothing is saved.

500

“could not save configuration”, “could not read configuration” (re-reading after the change), “could not check token”, or “Couldn’t save that change. Try again.” (the change could not be recorded, so it was not made). Nothing is half-saved: try again.

501

“configuration is read-only here”: this server can’t change configuration.

Retrieve the dynamic content table

PermissionCampaigns · Read

Returns the campaign’s dynamic content table (its columns and rows), the approved rules the rows draw on, and the signals a column can read. version is null until a table is saved. rules.approved is false until the campaign’s rules are approved. Each row’s needsApproval lists the fields (copy.<role>, colourway, master) that use a value the approved rules don’t list; such a row is saved but never rendered as ready, chosen or published. rules.mastersAvailable lists the organisation’s current ready master versions. rulesChanged is true when the saved table no longer passes the shape checks.

Path parameters

  • keystringRequired

    The document’s key (a brand’s code).

Returns

The table.

An object with:

  • versionobjectRequiredNullable

    The saved version, or null before the first save.

    Show child attributesHide child attributes
    • numberintegerOptional
    • hashstringOptional
    • sourcestringOptional
    • createdAtstring (date-time)Optional
  • columnsarray of objectsRequired
  • rowsarray of objectsRequired
  • rulesChangedbooleanRequired
  • signalsarray of stringsRequired

    The signals a column can read.

  • errorsarray of objectsRequired
    Show child attributesHide child attributes
    • rowstringOptional
    • fieldstringOptional
    • msgstringOptional
  • startedintegerOptional

    Renders started by a save.

  • renderErrorstringOptional

    A save’s renders could not be started; the table is saved.

  • switchingstringOptional

    Whether the published artwork switches between variants by itself: on, stopped once an editor stopped it, empty before the first publish.

    Possible valuesonstopped

Errors

StatusCodeMeaning
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

“unknown campaign”

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 the dynamic content.”

501

“Dynamic content isn’t set up on this server.”

Create or update the dynamic content table

PermissionCampaigns · Write

Saves the table as a new version and starts the renders it needs. The body is JSON with columns and rows; every row is checked against the campaign’s approved rules, and a table with problems is refused (422) with the list. The same table as the latest version saves nothing new. The rules must be approved first (409 rules_not_approved). The answer is the same as the read, plus started (renders started) or renderError when the table was saved but its renders could not start.

Path parameters

  • keystringRequired

    The document’s key (a brand’s code).

Body parameters

  • columnsarray of objectsRequired
    Show child attributesHide child attributes
    • namestringRequired

      Lower case letters, digits and underscores, up to 40.

    • typestringRequired
    • signalstringRequired

      The signal the column reads, such as time or city.

  • rowsarray of objectsRequired
    Show child attributesHide child attributes
    • idstringRequired
    • labelstringRequired
    • activebooleanRequired
    • defaultbooleanRequired

      The row used when no other applies.

    • copyobjectOptional

      Text for each role; blank keeps the rules’ default choice.

    • colourwaystringRequired
    • masterstringRequired

      A master version id from the approved rules.

    • whenobjectOptional

      The condition for each column.

Returns

The saved table.

An object with:

  • versionobjectRequiredNullable

    The saved version, or null before the first save.

    Show child attributesHide child attributes
    • numberintegerOptional
    • hashstringOptional
    • sourcestringOptional
    • createdAtstring (date-time)Optional
  • columnsarray of objectsRequired
  • rowsarray of objectsRequired
  • rulesChangedbooleanRequired
  • signalsarray of stringsRequired

    The signals a column can read.

  • errorsarray of objectsRequired
    Show child attributesHide child attributes
    • rowstringOptional
    • fieldstringOptional
    • msgstringOptional
  • startedintegerOptional

    Renders started by a save.

  • renderErrorstringOptional

    A save’s renders could not be started; the table is saved.

  • switchingstringOptional

    Whether the published artwork switches between variants by itself: on, stopped once an editor stopped it, empty before the first publish.

    Possible valuesonstopped

Errors

StatusCodeMeaning
400

The body could not be read.

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

“unknown campaign”

409api_off

Code api_off when an owner hasn’t turned the API on.

413

The body is over 2 MB.

422

“The table has problems.” with errors, up to 100 “{row, field, msg}”.

500

“Could not save the dynamic content.”

501

“Dynamic content isn’t set up on this server.”

Retrieve the row a screen would get

PermissionCampaigns · Write

Picks the row the saved table would show for a screen (screenId, from your last screen read) and any signal values you give (signals, which win over the screen’s own). Nothing is changed. The answer has the chosen rowId (empty when none), whether it is the default row, the reasons for the choice, the signals used and files, the ready file of the chosen row by format. 409 no_table until a table is saved.

Path parameters

  • keystringRequired

    The document’s key (a brand’s code).

Body parameters (optional)

  • screenIdstringOptional

    A screen from the last screen read.

  • timezonestringOptional

    An IANA zone such as Australia/Perth. With no screenId, the time, day and date signals follow this zone; blank means UTC. An unknown zone is refused with 400.

  • signalsobjectOptional

    Signal values to test with, such as time or city.

Returns

The choice.

An object with:

  • rowIdstringRequired
  • defaultbooleanRequired
  • reasonsarray of stringsRequired
  • signalsobjectRequired
  • filesobjectRequired

    The chosen row’s ready file for each format.

Errors

StatusCodeMeaning
400

The body could not be read.

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

“unknown campaign”, or “That screen isn’t in your last screen read.”

409rules_not_approvedno_tableapi_off

rules_not_approved (“Approve the rules first”), no_table (“Save the table first”), or code api_off.

500

“Could not read the dynamic content.”

501

“Dynamic content isn’t set up on this server.”