Skip to content

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

  • namestringRequired

    The site’s display name.

  • codestringRequired

    The brand’s code: its identifier in campaigns and runs. Unique in the organisation.

  • stylesobjectOptional

    A 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 objectsOptional
      Show child attributesHide child attributes
      • namestringRequired

        1 to 60 characters; unique among the text styles, ignoring case.

      • rolestringOptional

        The role it is meant for (headline, subhead, body, cta, legal…); empty for none.

      • fontobjectRequired
        Show child attributesHide child attributes
        • familystringRequired
        • stylestringRequired
        • axesobjectOptional
        • opticalSizestringOptional

          Possible valuesauto

      • sizenumberRequired

        Points, above 0.

      • leadingnumberRequired

        Points; 0 is automatic.

      • trackingnumberRequired

        Thousandths of an em.

      • alignstringRequired

        Possible valuesleftcenterrightjustify

      • capsstringRequired

        Possible valuesnormalallCapssmallCapscapToSmallCaps

      • colorstringOptional

        A #RRGGBB colour; empty to leave the colour as it is.

    • looksarray of objectsOptional
      Show child attributesHide child attributes
      • namestringRequired

        1 to 60 characters; unique among the looks, ignoring case.

      • lookobjectRequired

        The composition’s own look (blend, effects, fills, stroke, levels and the rest): at least one setting, every effect editable, no picture, notes or reach.

    • coloursarray of objectsOptional
      Show child attributesHide child attributes
      • namestringRequired

        1 to 60 characters; unique among the colours, ignoring case.

      • hexstringRequired

        A #RRGGBB colour of the brand’s palette (its brand colours, white or black); stored upper case.

  • logosobjectOptionalNullable

    InDesign 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 with 400, as InDesign would otherwise connect to that host.

  • brandColoursarray of stringsOptionalNullable

    The brand’s brand colours as hex values (for example #1B3A5C). 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.

Retrieve a brand

PermissionBrand · Read

Returns the site with this code, exactly as it was saved. Uploaded logos are listed under Logos.

Path parameters

  • keystringRequired

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

Returns

The document.

Returns the Brand object.

Errors

StatusCodeMeaning
401invalid_token

The key is missing, unknown, revoked or expired (code invalid_token). Send it as Authorization: Bearer <key>.

403

“Your role (<role>) can’t <action>.” (the role is below the route’s minimum) or “Choose an organisation first.” (the session has no organisation).

404

“unknown brand”

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

501

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

Create or update a brand

PermissionBrand · Write

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

  • 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 site’s display name.

  • codestringRequired

    The brand’s code: its identifier in campaigns and runs. Unique in the organisation.

  • stylesobjectOptional

    A 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 objectsOptional
      Show child attributesHide child attributes
      • namestringRequired

        1 to 60 characters; unique among the text styles, ignoring case.

      • rolestringOptional

        The role it is meant for (headline, subhead, body, cta, legal…); empty for none.

      • fontobjectRequired
        Show child attributesHide child attributes
        • familystringRequired
        • stylestringRequired
        • axesobjectOptional
        • opticalSizestringOptional

          Possible valuesauto

      • sizenumberRequired

        Points, above 0.

      • leadingnumberRequired

        Points; 0 is automatic.

      • trackingnumberRequired

        Thousandths of an em.

      • alignstringRequired

        Possible valuesleftcenterrightjustify

      • capsstringRequired

        Possible valuesnormalallCapssmallCapscapToSmallCaps

      • colorstringOptional

        A #RRGGBB colour; empty to leave the colour as it is.

    • looksarray of objectsOptional
      Show child attributesHide child attributes
      • namestringRequired

        1 to 60 characters; unique among the looks, ignoring case.

      • lookobjectRequired

        The composition’s own look (blend, effects, fills, stroke, levels and the rest): at least one setting, every effect editable, no picture, notes or reach.

    • coloursarray of objectsOptional
      Show child attributesHide child attributes
      • namestringRequired

        1 to 60 characters; unique among the colours, ignoring case.

      • hexstringRequired

        A #RRGGBB colour of the brand’s palette (its brand colours, white or black); stored upper case.

  • logosobjectOptionalNullable

    InDesign 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 with 400, as InDesign would otherwise connect to that host.

  • brandColoursarray of stringsOptionalNullable

    The brand’s brand colours as hex values (for example #1B3A5C). 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.

Returns

The stored (canonical) document.

Returns the Brand 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 brands

PermissionBrand · Read

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

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 brand

PermissionBrand · Write

Deletes the brand. Its uploaded logos are deleted with it.

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 brand”

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 a brand's styles

PermissionDesigns · Read

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

  • keystringRequired

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

Returns

The styles.

An object with:

  • savedobjectRequired
    Show child attributesHide child attributes
    • textarray of objectsRequired
      Show child attributesHide child attributes
      • namestringRequired

        1 to 60 characters; unique among the text styles, ignoring case.

      • rolestringOptional

        The role it is meant for (headline, subhead, body, cta, legal…); empty for none.

      • fontobjectRequired
        Show child attributesHide child attributes
        • familystringRequired
        • stylestringRequired
        • axesobjectOptional
        • opticalSizestringOptional

          Possible valuesauto

      • sizenumberRequired

        Points, above 0.

      • leadingnumberRequired

        Points; 0 is automatic.

      • trackingnumberRequired

        Thousandths of an em.

      • alignstringRequired

        Possible valuesleftcenterrightjustify

      • capsstringRequired

        Possible valuesnormalallCapssmallCapscapToSmallCaps

      • colorstringOptional

        A #RRGGBB colour; empty to leave the colour as it is.

    • looksarray of objectsRequired
      Show child attributesHide child attributes
      • namestringRequired

        1 to 60 characters; unique among the looks, ignoring case.

      • lookobjectRequired

        The composition’s own look (blend, effects, fills, stroke, levels and the rest): at least one setting, every effect editable, no picture, notes or reach.

    • coloursarray of objectsRequired
      Show child attributesHide child attributes
      • namestringRequired

        1 to 60 characters; unique among the colours, ignoring case.

      • hexstringRequired

        A #RRGGBB colour of the brand’s palette (its brand colours, white or black); stored upper case.

  • palettearray of stringsRequired

    The brand’s palette, read-only: its brand colours, then white and black. Not part of what a save sends.

  • fromMastersobjectRequired
    Show child attributesHide child attributes
    • textarray of objectsRequired

      A text style found in a master: a TextStyle (its name made from its role, face and size) and the master it was first seen in.

      Show child attributesHide child attributes
      • namestringRequired

        1 to 60 characters; unique among the text styles, ignoring case.

      • rolestringOptional

        The role it is meant for (headline, subhead, body, cta, legal…); empty for none.

      • fontobjectRequired
        Show child attributesHide child attributes
        • familystringRequired
        • stylestringRequired
        • axesobjectOptional
        • opticalSizestringOptional

          Possible valuesauto

      • sizenumberRequired

        Points, above 0.

      • leadingnumberRequired

        Points; 0 is automatic.

      • trackingnumberRequired

        Thousandths of an em.

      • alignstringRequired

        Possible valuesleftcenterrightjustify

      • capsstringRequired

        Possible valuesnormalallCapssmallCapscapToSmallCaps

      • colorstringOptional

        A #RRGGBB colour; empty to leave the colour as it is.

      • masterstringRequired
    • looksarray of objectsRequired
      Show child attributesHide child attributes
      • namestringRequired

        The layer’s name, or the kind of element and its master when it has none.

      • masterstringRequired

        The master it was first seen in.

      • layerstringRequired

        The layer’s name; empty when it has none.

      • lookobjectRequired

        The composition’s own look.

Errors

StatusCodeMeaning
401invalid_token

The key is missing, unknown, revoked or expired (code invalid_token). Send it as Authorization: Bearer <key>.

403

“Your role (<role>) can’t <action>.” (the role is below the route’s minimum) or “Choose an organisation first.” (the session has no organisation).

404

“unknown brand”: no such site in the organisation (or a Network customer asked).

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

501

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

Update a brand's styles

PermissionDesigns · Write

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

  • keystringRequired

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

Headers

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

    The brand’s updatedAt the person read; 412 when it has changed. Without it the save is checked against the document just read.

Body parameters

  • textarray of objectsOptional
    Show child attributesHide child attributes
    • namestringRequired

      1 to 60 characters; unique among the text styles, ignoring case.

    • rolestringOptional

      The role it is meant for (headline, subhead, body, cta, legal…); empty for none.

    • fontobjectRequired
      Show child attributesHide child attributes
      • familystringRequired
      • stylestringRequired
      • axesobjectOptional
      • opticalSizestringOptional

        Possible valuesauto

    • sizenumberRequired

      Points, above 0.

    • leadingnumberRequired

      Points; 0 is automatic.

    • trackingnumberRequired

      Thousandths of an em.

    • alignstringRequired

      Possible valuesleftcenterrightjustify

    • capsstringRequired

      Possible valuesnormalallCapssmallCapscapToSmallCaps

    • colorstringOptional

      A #RRGGBB colour; empty to leave the colour as it is.

  • looksarray of objectsOptional
    Show child attributesHide child attributes
    • namestringRequired

      1 to 60 characters; unique among the looks, ignoring case.

    • lookobjectRequired

      The composition’s own look (blend, effects, fills, stroke, levels and the rest): at least one setting, every effect editable, no picture, notes or reach.

  • coloursarray of objectsOptional
    Show child attributesHide child attributes
    • namestringRequired

      1 to 60 characters; unique among the colours, ignoring case.

    • hexstringRequired

      A #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 objectsRequired
    Show child attributesHide child attributes
    • namestringRequired

      1 to 60 characters; unique among the text styles, ignoring case.

    • rolestringOptional

      The role it is meant for (headline, subhead, body, cta, legal…); empty for none.

    • fontobjectRequired
      Show child attributesHide child attributes
      • familystringRequired
      • stylestringRequired
      • axesobjectOptional
      • opticalSizestringOptional

        Possible valuesauto

    • sizenumberRequired

      Points, above 0.

    • leadingnumberRequired

      Points; 0 is automatic.

    • trackingnumberRequired

      Thousandths of an em.

    • alignstringRequired

      Possible valuesleftcenterrightjustify

    • capsstringRequired

      Possible valuesnormalallCapssmallCapscapToSmallCaps

    • colorstringOptional

      A #RRGGBB colour; empty to leave the colour as it is.

  • looksarray of objectsRequired
    Show child attributesHide child attributes
    • namestringRequired

      1 to 60 characters; unique among the looks, ignoring case.

    • lookobjectRequired

      The composition’s own look (blend, effects, fills, stroke, levels and the rest): at least one setting, every effect editable, no picture, notes or reach.

  • coloursarray of objectsRequired
    Show child attributesHide child attributes
    • namestringRequired

      1 to 60 characters; unique among the colours, ignoring case.

    • hexstringRequired

      A #RRGGBB colour of the brand’s palette (its brand colours, white or black); stored upper case.

Errors

StatusCodeMeaning
400

A refusal with field (text[1].name, looks[2].look.effects[0], text[0].font.family, colours[0].hex) and the reason, or bad JSON: <error>.

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

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.

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.