API reference
Brands
A site is a brand or site that campaigns run in: its colours, QR address and layout rules. Its logos are uploaded separately (see Logos). Every run is for one brand.
The Brand object
The brand object. A brand is identified by its code.
Attributes
namestringRequiredThe site’s display name.
codestringRequiredThe brand’s code: its identifier in campaigns and runs. Unique in the organisation.
stylesobjectOptionalA brand’s saved styles: its text styles, its looks and its named colours. Every list may be empty. A save replaces the whole document, so a save that leaves a list out clears it.
Show child attributesHide child attributes
textarray of objectsOptionalShow child attributesHide child attributes
namestringRequired1 to 60 characters; unique among the text styles, ignoring case.
rolestringOptionalThe role it is meant for (headline, subhead, body, cta, legal…); empty for none.
fontobjectRequiredShow child attributesHide child attributes
familystringRequiredstylestringRequiredaxesobjectOptionalopticalSizestringOptionalPossible values
auto
sizenumberRequiredPoints, above 0.
leadingnumberRequiredPoints; 0 is automatic.
trackingnumberRequiredThousandths of an em.
alignstringRequiredPossible values
leftcenterrightjustifycapsstringRequiredPossible values
normalallCapssmallCapscapToSmallCapscolorstringOptionalA #RRGGBB colour; empty to leave the colour as it is.
looksarray of objectsOptionalShow child attributesHide child attributes
namestringRequired1 to 60 characters; unique among the looks, ignoring case.
lookobjectRequiredThe composition’s own look (
blend,effects,fills,stroke,levelsand the rest): at least one setting, every effect editable, nopicture,notesorreach.
coloursarray of objectsOptionalShow child attributesHide child attributes
namestringRequired1 to 60 characters; unique among the colours, ignoring case.
hexstringRequiredA #RRGGBB colour of the brand’s palette (its brand colours, white or black); stored upper case.
logosobjectOptionalNullableInDesign file paths by variant. Each must be a file on the user’s computer (
C:\...,/...or a relative path); a network or web address (//host,\\host,file:,smb:,http:or any other scheme) is refused with400, as InDesign would otherwise connect to that host.brandColoursarray of stringsOptionalNullableThe brand’s brand colours as hex values (for example
#1B3A5C). 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.
Retrieve a brand
Returns the site with this code, exactly as it was saved. Uploaded logos are listed under Logos.
Path parameters
keystringRequiredThe document’s key (a brand’s code).
Returns
The document.
Returns the Brand 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 | “unknown brand” | |
409 | api_off |
|
500 | “could not read configuration” or “could not check token”. | |
501 | “configuration is read-only here”: this server can’t change configuration. |
Create or update a brand
Creates the brand with this code, or replaces it if it already exists. The body is strict JSON, and its code must equal the one in the path. Creating a brand beyond the plan’s brand allowance is refused. 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 site’s display name.
codestringRequiredThe brand’s code: its identifier in campaigns and runs. Unique in the organisation.
stylesobjectOptionalA brand’s saved styles: its text styles, its looks and its named colours. Every list may be empty. A save replaces the whole document, so a save that leaves a list out clears it.
Show child attributesHide child attributes
textarray of objectsOptionalShow child attributesHide child attributes
namestringRequired1 to 60 characters; unique among the text styles, ignoring case.
rolestringOptionalThe role it is meant for (headline, subhead, body, cta, legal…); empty for none.
fontobjectRequiredShow child attributesHide child attributes
familystringRequiredstylestringRequiredaxesobjectOptionalopticalSizestringOptionalPossible values
auto
sizenumberRequiredPoints, above 0.
leadingnumberRequiredPoints; 0 is automatic.
trackingnumberRequiredThousandths of an em.
alignstringRequiredPossible values
leftcenterrightjustifycapsstringRequiredPossible values
normalallCapssmallCapscapToSmallCapscolorstringOptionalA #RRGGBB colour; empty to leave the colour as it is.
looksarray of objectsOptionalShow child attributesHide child attributes
namestringRequired1 to 60 characters; unique among the looks, ignoring case.
lookobjectRequiredThe composition’s own look (
blend,effects,fills,stroke,levelsand the rest): at least one setting, every effect editable, nopicture,notesorreach.
coloursarray of objectsOptionalShow child attributesHide child attributes
namestringRequired1 to 60 characters; unique among the colours, ignoring case.
hexstringRequiredA #RRGGBB colour of the brand’s palette (its brand colours, white or black); stored upper case.
logosobjectOptionalNullableInDesign file paths by variant. Each must be a file on the user’s computer (
C:\...,/...or a relative path); a network or web address (//host,\\host,file:,smb:,http:or any other scheme) is refused with400, as InDesign would otherwise connect to that host.brandColoursarray of stringsOptionalNullableThe brand’s brand colours as hex values (for example
#1B3A5C). 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.
Returns
The stored (canonical) document.
Returns the Brand 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 brands
Returns every site (a brand or site that campaigns run in) the organisation has, sorted by code.
Returns
Every brand.
Returns a list of Brand 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 brand
Deletes the brand. Its uploaded logos are deleted with it.
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 brand” | |
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 a brand's styles
Returns the site’s saved text styles, looks and colours (saved), the site’s palette (palette, read-only: its brand colours, then white and black, each #RRGGBB upper case, which is what the editor’s paint operations accept), and the ones its masters already use (fromMasters), found when you ask and kept nowhere: each distinct look of an element in the latest version of the site’s masters, named by its layer and master (looks drawn from a saved picture or holding an effect the editor cannot edit are left out), and each distinct paragraph style by role. Needs the Designs read permission. The answer carries X-Mestra-Updated-At, the site’s own, to send back with a save.
Path parameters
keystringRequiredThe document’s key (a brand’s code).
Returns
The styles.
An object with:
savedobjectRequiredShow child attributesHide child attributes
textarray of objectsRequiredShow child attributesHide child attributes
namestringRequired1 to 60 characters; unique among the text styles, ignoring case.
rolestringOptionalThe role it is meant for (headline, subhead, body, cta, legal…); empty for none.
fontobjectRequiredShow child attributesHide child attributes
familystringRequiredstylestringRequiredaxesobjectOptionalopticalSizestringOptionalPossible values
auto
sizenumberRequiredPoints, above 0.
leadingnumberRequiredPoints; 0 is automatic.
trackingnumberRequiredThousandths of an em.
alignstringRequiredPossible values
leftcenterrightjustifycapsstringRequiredPossible values
normalallCapssmallCapscapToSmallCapscolorstringOptionalA #RRGGBB colour; empty to leave the colour as it is.
looksarray of objectsRequiredShow child attributesHide child attributes
namestringRequired1 to 60 characters; unique among the looks, ignoring case.
lookobjectRequiredThe composition’s own look (
blend,effects,fills,stroke,levelsand the rest): at least one setting, every effect editable, nopicture,notesorreach.
coloursarray of objectsRequiredShow child attributesHide child attributes
namestringRequired1 to 60 characters; unique among the colours, ignoring case.
hexstringRequiredA #RRGGBB colour of the brand’s palette (its brand colours, white or black); stored upper case.
palettearray of stringsRequiredThe brand’s palette, read-only: its brand colours, then white and black. Not part of what a save sends.
fromMastersobjectRequiredShow child attributesHide child attributes
textarray of objectsRequiredA text style found in a master: a
TextStyle(itsnamemade from its role, face and size) and the master it was first seen in.Show child attributesHide child attributes
namestringRequired1 to 60 characters; unique among the text styles, ignoring case.
rolestringOptionalThe role it is meant for (headline, subhead, body, cta, legal…); empty for none.
fontobjectRequiredShow child attributesHide child attributes
familystringRequiredstylestringRequiredaxesobjectOptionalopticalSizestringOptionalPossible values
auto
sizenumberRequiredPoints, above 0.
leadingnumberRequiredPoints; 0 is automatic.
trackingnumberRequiredThousandths of an em.
alignstringRequiredPossible values
leftcenterrightjustifycapsstringRequiredPossible values
normalallCapssmallCapscapToSmallCapscolorstringOptionalA #RRGGBB colour; empty to leave the colour as it is.
masterstringRequired
looksarray of objectsRequiredShow child attributesHide child attributes
namestringRequiredThe layer’s name, or the kind of element and its master when it has none.
masterstringRequiredThe master it was first seen in.
layerstringRequiredThe layer’s name; empty when it has none.
lookobjectRequiredThe composition’s own look.
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 | “unknown brand”: no such site in the organisation (or a Network customer asked). | |
409 | api_off |
|
500 | “could not read configuration” or “could not check token”. | |
501 | “configuration is read-only here”: this server can’t change configuration. |
Update a brand's styles
Replaces the brand’s saved styles whole with the body and answers the saved styles. Any editor may save a style: this needs the Designs write permission, not the brand settings’. Names are 1 to 60 characters and unique in their list, ignoring case; a saved colour (colours: {name, hex}) is a #RRGGBB (kept upper case) that the brand’s palette holds, 400 with field colours[i].hex otherwise; a look holds only effects the editor can edit and none of the server’s own picture, notes and reach; a text style’s family must be one the brand allows when it restricts families. A refusal is 400 with field naming the place (looks[2].look.effects[0], text[1].name). Send the X-Mestra-Updated-At of the read to get 412 when the brand changed since.
Path parameters
keystringRequiredThe document’s key (a brand’s code).
Headers
X-Mestra-Updated-Atstring (date-time)OptionalThe brand’s
updatedAtthe person read;412when it has changed. Without it the save is checked against the document just read.
Body parameters
textarray of objectsOptionalShow child attributesHide child attributes
namestringRequired1 to 60 characters; unique among the text styles, ignoring case.
rolestringOptionalThe role it is meant for (headline, subhead, body, cta, legal…); empty for none.
fontobjectRequiredShow child attributesHide child attributes
familystringRequiredstylestringRequiredaxesobjectOptionalopticalSizestringOptionalPossible values
auto
sizenumberRequiredPoints, above 0.
leadingnumberRequiredPoints; 0 is automatic.
trackingnumberRequiredThousandths of an em.
alignstringRequiredPossible values
leftcenterrightjustifycapsstringRequiredPossible values
normalallCapssmallCapscapToSmallCapscolorstringOptionalA #RRGGBB colour; empty to leave the colour as it is.
looksarray of objectsOptionalShow child attributesHide child attributes
namestringRequired1 to 60 characters; unique among the looks, ignoring case.
lookobjectRequiredThe composition’s own look (
blend,effects,fills,stroke,levelsand the rest): at least one setting, every effect editable, nopicture,notesorreach.
coloursarray of objectsOptionalShow child attributesHide child attributes
namestringRequired1 to 60 characters; unique among the colours, ignoring case.
hexstringRequiredA #RRGGBB colour of the brand’s palette (its brand colours, white or black); stored upper case.
Returns
The saved styles.
An object with:
textarray of objectsRequiredShow child attributesHide child attributes
namestringRequired1 to 60 characters; unique among the text styles, ignoring case.
rolestringOptionalThe role it is meant for (headline, subhead, body, cta, legal…); empty for none.
fontobjectRequiredShow child attributesHide child attributes
familystringRequiredstylestringRequiredaxesobjectOptionalopticalSizestringOptionalPossible values
auto
sizenumberRequiredPoints, above 0.
leadingnumberRequiredPoints; 0 is automatic.
trackingnumberRequiredThousandths of an em.
alignstringRequiredPossible values
leftcenterrightjustifycapsstringRequiredPossible values
normalallCapssmallCapscapToSmallCapscolorstringOptionalA #RRGGBB colour; empty to leave the colour as it is.
looksarray of objectsRequiredShow child attributesHide child attributes
namestringRequired1 to 60 characters; unique among the looks, ignoring case.
lookobjectRequiredThe composition’s own look (
blend,effects,fills,stroke,levelsand the rest): at least one setting, every effect editable, nopicture,notesorreach.
coloursarray of objectsRequiredShow child attributesHide child attributes
namestringRequired1 to 60 characters; unique among the colours, ignoring case.
hexstringRequiredA #RRGGBB colour of the brand’s palette (its brand colours, white or black); stored upper case.
Errors
| Status | Code | Meaning |
|---|---|---|
400 | A refusal with | |
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
404 | “unknown brand”. | |
409 | api_off |
|
412 | “Someone else changed this. Reload to see their changes.” ( | |
413 | “body exceeds limit (65536 bytes)” | |
500 | “could not read configuration” or “could not check token”. | |
501 | “configuration is read-only here”: this server can’t change configuration. |