API reference
Campaigns
A campaign is a brief: the copy, the dates, and the brands and formats to make. It points at a format set and one or more brands. Runs make a campaign’s artwork from a master, and reviews follow a campaign’s results.
The Campaign object
The campaign object. A campaign is identified by its key.
Attributes
namestringRequiredThe campaign’s display name.
keystringRequiredThe campaign’s key: its identifier in URLs and in runs. Letters, digits and dashes, unique in the organisation.
externalRefobjectOptionalA link to the same campaign in another system, for your own reference. Mestra does not read from it.
Show child attributesHide child attributes
systemstringOptionalThe name of the other system (for example
Asana). Empty when there is none.idstringOptionalNullableThe campaign’s id in that system, or null.
urlstringOptionalNullableA link to the campaign in that system, or null.
syncedAtstringOptionalNullableWhen the link was last refreshed from that system, or null.
formatSetstringOptionalThe key of the format set this campaign makes: the group of sizes each run builds. Optional: a campaign can list its sizes in
formatsalone.formatsarray of stringsOptionalNullableThe 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 stringsRequiredNullableThe codes of the brands this campaign runs in. At least one.
copyobjectOptionalNullableFixed wording for the campaign, by role (for example
headlineorcta). A run uses it exactly as written. Each value is up to 2,000 characters.qrUrlstringOptionalThe address a QR code in the campaign’s artwork points to. Empty for none.
startDatestringOptionalOptional, YYYY-MM-DD: prefills a publish to screens.
endDatestringOptionalOptional, YYYY-MM-DD, not before startDate.
notesstringOptionalFree-text notes for this campaign that the layout planner follows, up to 4,000 characters.
brandRulesOverrideobjectOptionalNullableBrand rules that replace the brand’s own for this campaign; null to use the brand’s.
Show child attributesHide child attributes
logoobjectOptionalNullableRules for the logo; null for none.
Show child attributesHide child attributes
minWidthPctnumberOptionalThe smallest logo width, as a share of the page width (0.12 is 12%).
clearSpacePctnumberOptionalThe clear space kept around the logo, as a share (for example 0.5).
typographyobjectOptionalNullableRules for type; null for none.
Show child attributesHide child attributes
allowedFamiliesarray of stringsOptionalNullableThe font families layouts may use. Null for any.
headlineMaxLinesintegerOptionalThe most lines a headline may take.
alignmentobjectOptionalNullableRules for alignment; null for none.
Show child attributesHide child attributes
gridnumberOptionalThe grid that positions snap to.
spacingobjectOptionalNullableRules for spacing; null for none.
Show child attributesHide child attributes
minGapPctnumberOptionalThe smallest gap between elements, as a share of the page height (0.02 is 2%).
notesstringOptionalFree-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 objectsOptionalPer-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 stringsOptionalskiparray of stringsOptional
copyRowsarray of objectsOptionalNullableThe 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
centrestringOptionalA brand code. Empty for every brand.
formatstringOptionalA format key. Empty for every format.
copyobjectRequiredText by role (
headline,subhead,body,legal,cta), up to 2,000 characters each.
Retrieve a campaign
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
keystringRequiredThe document’s key (a brand’s code).
Returns
The campaign.
An object with:
campaignobjectRequiredThe campaign object. A campaign is identified by its
key.Show child attributesHide child attributes
namestringRequiredThe campaign’s display name.
keystringRequiredThe campaign’s key: its identifier in URLs and in runs. Letters, digits and dashes, unique in the organisation.
externalRefobjectOptionalA link to the same campaign in another system, for your own reference. Mestra does not read from it.
Show child attributesHide child attributes
systemstringOptionalThe name of the other system (for example
Asana). Empty when there is none.idstringOptionalNullableThe campaign’s id in that system, or null.
urlstringOptionalNullableA link to the campaign in that system, or null.
syncedAtstringOptionalNullableWhen the link was last refreshed from that system, or null.
formatSetstringOptionalThe key of the format set this campaign makes: the group of sizes each run builds. Optional: a campaign can list its sizes in
formatsalone.formatsarray of stringsOptionalNullableThe 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 stringsRequiredNullableThe codes of the brands this campaign runs in. At least one.
copyobjectOptionalNullableFixed wording for the campaign, by role (for example
headlineorcta). A run uses it exactly as written. Each value is up to 2,000 characters.qrUrlstringOptionalThe address a QR code in the campaign’s artwork points to. Empty for none.
startDatestringOptionalOptional, YYYY-MM-DD: prefills a publish to screens.
endDatestringOptionalOptional, YYYY-MM-DD, not before startDate.
notesstringOptionalFree-text notes for this campaign that the layout planner follows, up to 4,000 characters.
brandRulesOverrideobjectOptionalNullableBrand rules that replace the brand’s own for this campaign; null to use the brand’s.
Show child attributesHide child attributes
logoobjectOptionalNullableRules for the logo; null for none.
Show child attributesHide child attributes
minWidthPctnumberOptionalThe smallest logo width, as a share of the page width (0.12 is 12%).
clearSpacePctnumberOptionalThe clear space kept around the logo, as a share (for example 0.5).
typographyobjectOptionalNullableRules for type; null for none.
Show child attributesHide child attributes
allowedFamiliesarray of stringsOptionalNullableThe font families layouts may use. Null for any.
headlineMaxLinesintegerOptionalThe most lines a headline may take.
alignmentobjectOptionalNullableRules for alignment; null for none.
Show child attributesHide child attributes
gridnumberOptionalThe grid that positions snap to.
spacingobjectOptionalNullableRules for spacing; null for none.
Show child attributesHide child attributes
minGapPctnumberOptionalThe smallest gap between elements, as a share of the page height (0.02 is 2%).
notesstringOptionalFree-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 objectsOptionalPer-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 stringsOptionalskiparray of stringsOptional
copyRowsarray of objectsOptionalNullableThe 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
centrestringOptionalA brand code. Empty for every brand.
formatstringOptionalA format key. Empty for every format.
copyobjectRequiredText by role (
headline,subhead,body,legal,cta), up to 2,000 characters each.
limitsobjectRequiredThe organisation’s review slots (
reviews) and how many review passes its apps may run (passes).Show child attributesHide child attributes
reviewsintegerRequiredpassesintegerRequired
formatsarray of objectsRequiredShow child attributesHide child attributes
namestringRequiredThe format’s display name.
keystringRequiredThe format’s key: its identifier in format sets and runs. Unique in the organisation.
widthnumberRequiredWidth, in
unit.heightnumberRequiredHeight, in
unit.unitstringRequiredThe unit of
width,height,bleedandsafeMargin:px,mmorpt. Type sizes are always in points.Possible values
pxmmptdpinumberOptionalNullableResolution in dots per inch. Needed for
mmformats; usually null forpxandpt.exportScaleintegerOptionalpx 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.
bleednumberOptionalBleed beyond the trim, in
unit. A format with a bleed is a print size.safeMarginnumberOptionalThe margin kept clear of important content, in
unit.familystringOptionalThe kind of output (for example
print,social,weborscreen). It decides defaults such as the export scale.requirearray of stringsOptionalNullableElements every layout of this format must keep:
cta,qr. Null or empty for none.droparray of stringsOptionalNullableRoles left out of this format (for example
subhead). Null or empty for none.minTypeSizeobjectOptionalNullableSmallest type size per role, in points.
exportFormatsarray of stringsOptionalNullableThe file types a review of this format can export (for example
png,jpg,pdf). Null for the defaults.reviewPolicystringRequiredalwayschecks every layout of this format;skip-if-cleanskips the check when the layout is already clean.copyOverridesobjectOptionalNullableWording that replaces the campaign’s own for this format, by role. Each value is up to 2,000 characters.
extraFormatsarray of objectsOptionalFull definitions of the formats that appear in a brand’s
siteSizeslist but not informats. Present only when there are any.Show child attributesHide child attributes
namestringRequiredThe format’s display name.
keystringRequiredThe format’s key: its identifier in format sets and runs. Unique in the organisation.
widthnumberRequiredWidth, in
unit.heightnumberRequiredHeight, in
unit.unitstringRequiredThe unit of
width,height,bleedandsafeMargin:px,mmorpt. Type sizes are always in points.Possible values
pxmmptdpinumberOptionalNullableResolution in dots per inch. Needed for
mmformats; usually null forpxandpt.exportScaleintegerOptionalpx 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.
bleednumberOptionalBleed beyond the trim, in
unit. A format with a bleed is a print size.safeMarginnumberOptionalThe margin kept clear of important content, in
unit.familystringOptionalThe kind of output (for example
print,social,weborscreen). It decides defaults such as the export scale.requirearray of stringsOptionalNullableElements every layout of this format must keep:
cta,qr. Null or empty for none.droparray of stringsOptionalNullableRoles left out of this format (for example
subhead). Null or empty for none.minTypeSizeobjectOptionalNullableSmallest type size per role, in points.
exportFormatsarray of stringsOptionalNullableThe file types a review of this format can export (for example
png,jpg,pdf). Null for the defaults.reviewPolicystringRequiredalwayschecks every layout of this format;skip-if-cleanskips the check when the layout is already clean.copyOverridesobjectOptionalNullableWording that replaces the campaign’s own for this format, by role. Each value is up to 2,000 characters.
siteSizesobjectOptionalThe 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 objectsRequiredShow child attributesHide child attributes
namestringOptionalThe site’s display name.
codestringOptionalThe brand’s code.
logosobjectOptionalNullableThe logo files named in the configuration, by variant. Uploaded logos are in
uploadedLogos.brandColoursarray of stringsOptionalNullableThe brand’s brand colours as hex values. Null for none.
colourInksobjectOptionalCMYK 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 ofbrandColours. Omitted when none are set.colourNamesobjectOptionalOptional names for brand colours, keyed by the lower-case hex value (for example
#1b3a5c):{"#1b3a5c": "Navy"}. Each key must be one ofbrandColours; a colour with no entry is unnamed. A name is at most 40 characters with no quotes or angle brackets (refused with400and fieldcolourNames).brandColoursstays a list of hex strings, so clients that send only hex values keep working. Omitted when none are set.qrBaseUrlstringOptionalThe address QR codes for this brand start from. Empty for none.
brandRulesobjectOptionalShow child attributesHide child attributes
logoobjectOptionalNullableRules for the logo; null for none.
Show child attributesHide child attributes
minWidthPctnumberOptionalThe smallest logo width, as a share of the page width (0.12 is 12%).
clearSpacePctnumberOptionalThe clear space kept around the logo, as a share (for example 0.5).
typographyobjectOptionalNullableRules for type; null for none.
Show child attributesHide child attributes
allowedFamiliesarray of stringsOptionalNullableThe font families layouts may use. Null for any.
headlineMaxLinesintegerOptionalThe most lines a headline may take.
alignmentobjectOptionalNullableRules for alignment; null for none.
Show child attributesHide child attributes
gridnumberOptionalThe grid that positions snap to.
spacingobjectOptionalNullableRules for spacing; null for none.
Show child attributesHide child attributes
minGapPctnumberOptionalThe smallest gap between elements, as a share of the page height (0.02 is 2%).
notesstringOptionalFree-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 stringsOptionalFormat keys added to every campaign’s format set for this brand.
formatsSkiparray of stringsOptionalFormat keys left out of every campaign’s format set for this brand.
uploadedLogosarray of objectsRequiredThe uploaded variants (primary, then reversed);
[]when none or logos aren’t set up.Show child attributesHide child attributes
variantstringRequiredprimaryorreversed: the slot the logo is uploaded to.Possible values
primaryreversedcontentTypestringRequiredimage/pngorimage/svg+xml.Possible values
image/pngimage/svg+xmlsha256stringRequiredThe file’s SHA-256, in lower-case hex.
luminancenumberOptionalNullableThe 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).
trimobjectOptionalNullableThe 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
xnumberRequiredLeft edge of the visible artwork, as a share (0 to 1) of the logo’s width.
ynumberRequiredTop edge of the visible artwork, as a share (0 to 1) of the logo’s height.
wnumberRequiredWidth of the visible artwork, as a share (0 to 1) of the logo’s width.
hnumberRequiredHeight of the visible artwork, as a share (0 to 1) of the logo’s height.
missingSitesarray of stringsOptionalPresent only when a brand code does not resolve.
Errors
| Status | Code | Meaning |
|---|---|---|
400 | The campaign names a format set or format the organisation doesn’t have; the message says which. | |
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 | “unknown campaign” | |
409 | api_off |
|
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
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
keystringRequiredThe document’s key (a brand’s code).
Headers
X-Mestra-Updated-Atstring (date-time)OptionalThe
X-Mestra-Updated-Atyour last save of this document answered with. The write goes ahead only if the document is unchanged since, otherwise412(a document deleted since counts as changed). Send either this orX-Mestra-Create, not both.X-Mestra-CreatestringOptional1: the write creates the document; a taken key is409. A DELETE ignores it.Possible values
1
Body parameters
namestringRequiredThe campaign’s display name.
keystringRequiredThe campaign’s key: its identifier in URLs and in runs. Letters, digits and dashes, unique in the organisation.
externalRefobjectOptionalA link to the same campaign in another system, for your own reference. Mestra does not read from it.
Show child attributesHide child attributes
systemstringOptionalThe name of the other system (for example
Asana). Empty when there is none.idstringOptionalNullableThe campaign’s id in that system, or null.
urlstringOptionalNullableA link to the campaign in that system, or null.
syncedAtstringOptionalNullableWhen the link was last refreshed from that system, or null.
formatSetstringOptionalThe key of the format set this campaign makes: the group of sizes each run builds. Optional: a campaign can list its sizes in
formatsalone.formatsarray of stringsOptionalNullableThe 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 stringsRequiredNullableThe codes of the brands this campaign runs in. At least one.
copyobjectOptionalNullableFixed wording for the campaign, by role (for example
headlineorcta). A run uses it exactly as written. Each value is up to 2,000 characters.qrUrlstringOptionalThe address a QR code in the campaign’s artwork points to. Empty for none.
startDatestringOptionalOptional, YYYY-MM-DD: prefills a publish to screens.
endDatestringOptionalOptional, YYYY-MM-DD, not before startDate.
notesstringOptionalFree-text notes for this campaign that the layout planner follows, up to 4,000 characters.
brandRulesOverrideobjectOptionalNullableBrand rules that replace the brand’s own for this campaign; null to use the brand’s.
Show child attributesHide child attributes
logoobjectOptionalNullableRules for the logo; null for none.
Show child attributesHide child attributes
minWidthPctnumberOptionalThe smallest logo width, as a share of the page width (0.12 is 12%).
clearSpacePctnumberOptionalThe clear space kept around the logo, as a share (for example 0.5).
typographyobjectOptionalNullableRules for type; null for none.
Show child attributesHide child attributes
allowedFamiliesarray of stringsOptionalNullableThe font families layouts may use. Null for any.
headlineMaxLinesintegerOptionalThe most lines a headline may take.
alignmentobjectOptionalNullableRules for alignment; null for none.
Show child attributesHide child attributes
gridnumberOptionalThe grid that positions snap to.
spacingobjectOptionalNullableRules for spacing; null for none.
Show child attributesHide child attributes
minGapPctnumberOptionalThe smallest gap between elements, as a share of the page height (0.02 is 2%).
notesstringOptionalFree-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 objectsOptionalPer-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 stringsOptionalskiparray of stringsOptional
copyRowsarray of objectsOptionalNullableThe 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
centrestringOptionalA brand code. Empty for every brand.
formatstringOptionalA format key. Empty for every format.
copyobjectRequiredText by role (
headline,subhead,body,legal,cta), up to 2,000 characters each.
Returns
The stored (canonical) document.
Returns the Campaign object.
Errors
| Status | Code | Meaning |
|---|---|---|
400 | A value is refused. The answer is The rules: every kind needs a non-blank Without a | |
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
409 | api_off | “That key is already taken.” ( |
412 | “Someone else changed this. Reload to see their changes.” ( | |
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
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
limitintegerOptional1 to 200; every campaign when neither limit nor offset is sent.
Default
200offsetintegerOptionalDefault
0
Returns
Every campaign, or the page asked for.
Returns a list of Campaign objects.
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 load configuration” or “could not check token”. |
Delete a campaign
Deletes the campaign. Runs and reviews already made from it are not affected.
Path parameters
keystringRequiredThe document’s key (a brand’s code).
Headers
X-Mestra-Updated-Atstring (date-time)OptionalThe
X-Mestra-Updated-Atyour last save of this document answered with. The write goes ahead only if the document is unchanged since, otherwise412(a document deleted since counts as changed). Send either this orX-Mestra-Create, not both.X-Mestra-CreatestringOptional1: the write creates the document; a taken key is409. A DELETE ignores it.Possible values
1
Returns
Deleted.
Errors
| Status | Code | Meaning |
|---|---|---|
400 | A value is refused. The answer is The rules: every kind needs a non-blank Without a | |
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
404 | “unknown campaign” | |
409 | api_off |
|
412 | “Someone else changed this. Reload to see their changes.” ( | |
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
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
keystringRequiredThe document’s key (a brand’s code).
Returns
The table.
An object with:
versionobjectRequiredNullableThe saved version, or null before the first save.
Show child attributesHide child attributes
numberintegerOptionalhashstringOptionalsourcestringOptionalcreatedAtstring (date-time)Optional
columnsarray of objectsRequiredrowsarray of objectsRequiredrulesChangedbooleanRequiredsignalsarray of stringsRequiredThe signals a column can read.
errorsarray of objectsRequiredShow child attributesHide child attributes
rowstringOptionalfieldstringOptionalmsgstringOptional
startedintegerOptionalRenders started by a save.
renderErrorstringOptionalA save’s renders could not be started; the table is saved.
switchingstringOptionalWhether the published artwork switches between variants by itself:
on,stoppedonce an editor stopped it, empty before the first publish.Possible values
onstopped
Errors
| Status | Code | Meaning |
|---|---|---|
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
404 | “unknown campaign” | |
409 | api_off |
|
500 | “Could not read the dynamic content.” | |
501 | “Dynamic content isn’t set up on this server.” |
Create or update the dynamic content table
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
keystringRequiredThe document’s key (a brand’s code).
Body parameters
columnsarray of objectsRequiredShow child attributesHide child attributes
namestringRequiredLower case letters, digits and underscores, up to 40.
typestringRequiredsignalstringRequiredThe signal the column reads, such as
timeorcity.
rowsarray of objectsRequiredShow child attributesHide child attributes
idstringRequiredlabelstringRequiredactivebooleanRequireddefaultbooleanRequiredThe row used when no other applies.
copyobjectOptionalText for each role; blank keeps the rules’ default choice.
colourwaystringRequiredmasterstringRequiredA master version id from the approved rules.
whenobjectOptionalThe condition for each column.
Returns
The saved table.
An object with:
versionobjectRequiredNullableThe saved version, or null before the first save.
Show child attributesHide child attributes
numberintegerOptionalhashstringOptionalsourcestringOptionalcreatedAtstring (date-time)Optional
columnsarray of objectsRequiredrowsarray of objectsRequiredrulesChangedbooleanRequiredsignalsarray of stringsRequiredThe signals a column can read.
errorsarray of objectsRequiredShow child attributesHide child attributes
rowstringOptionalfieldstringOptionalmsgstringOptional
startedintegerOptionalRenders started by a save.
renderErrorstringOptionalA save’s renders could not be started; the table is saved.
switchingstringOptionalWhether the published artwork switches between variants by itself:
on,stoppedonce an editor stopped it, empty before the first publish.Possible values
onstopped
Errors
| Status | Code | Meaning |
|---|---|---|
400 | The body could not be read. | |
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
404 | “unknown campaign” | |
409 | api_off | Code |
413 | The body is over 2 MB. | |
422 | “The table has problems.” with | |
500 | “Could not save the dynamic content.” | |
501 | “Dynamic content isn’t set up on this server.” |
Retrieve the row a screen would get
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
keystringRequiredThe document’s key (a brand’s code).
Body parameters (optional)
screenIdstringOptionalA screen from the last screen read.
timezonestringOptionalAn IANA zone such as
Australia/Perth. With noscreenId, thetime,dayanddatesignals follow this zone; blank means UTC. An unknown zone is refused with 400.signalsobjectOptionalSignal values to test with, such as
timeorcity.
Returns
The choice.
An object with:
rowIdstringRequireddefaultbooleanRequiredreasonsarray of stringsRequiredsignalsobjectRequiredfilesobjectRequiredThe chosen row’s ready file for each format.
Errors
| Status | Code | Meaning |
|---|---|---|
400 | The body could not be read. | |
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
404 | “unknown campaign”, or “That screen isn’t in your last screen read.” | |
409 | rules_not_approvedno_tableapi_off |
|
500 | “Could not read the dynamic content.” | |
501 | “Dynamic content isn’t set up on this server.” |