Skip to content

API reference

Formats

A format is one output size and its rules: width, height, bleed, safe margin, the smallest type allowed, and what must be kept or left out. Formats are grouped into format sets, and a campaign builds every format in its set.

The Format object

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

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.

Retrieve a format

PermissionBrand · Read

Returns the format with this key, exactly as it was saved.

Path parameters

  • keystringRequired

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

Returns

The document.

Returns the Format 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 format”

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 format

PermissionBrand · Write

Creates the format 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. A value that isn’t allowed is refused with 400, and field names it. 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 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.

Returns

The stored (canonical) document.

Returns the Format 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 formats

PermissionBrand · Read

Returns every format (a named output size and its rules) the organisation has, sorted by key.

Returns

Every format.

Returns a list of Format 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 format

PermissionBrand · Write

Deletes the format. If a format set or campaign still uses it, the request is refused with 400 and field names 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 format”

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 or create a format for a size

PermissionCampaigns · Write

Answers the organisation’s format for a width, height and unit (px or mm; a blank unit is px), making one when it has none. A size the organisation already has, with the same width, height and unit, answers that format’s key (the lowest key if several match; a print format, which the server does not make, is never reused). Otherwise a format is made with the key custom-<w>x<h>-<unit> (a decimal keeps its dot, for example custom-99.5x210-mm), the name <w> × <h> <unit> and the usual defaults (review always, export indd, png and jpg, no bleed or safe margin; 150 dpi for a size in mm). Each side must be at least 1 and at most 20000, else 400 with code bad_custom_size, field (w, h or unit) and, for a side, min and max. Needs the same permission as saving a campaign.

Body parameters

  • wnumberRequired
  • hnumberRequired
  • unitstringOptional

    Possible valuespxmm

Returns

The format.

An object with:

  • keystringRequired
  • namestringRequired
  • widthnumberRequired
  • heightnumberRequired
  • unitstringRequired

    Possible valuespxmm

Errors

StatusCodeMeaning
400bad_custom_size

The size is refused (bad_custom_size).

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

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