Skip to content

API reference

Format sets

A format set is a named group of formats, such as “Social launch”. A campaign names one format set, and each of its formats is built once for each brand.

The Format set object

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

Attributes

  • namestringRequired

    The format set’s display name.

  • keystringRequired

    The format set’s key. Unique in the organisation.

  • formatsarray of stringsOptionalNullable

    The keys of the formats in this set, in the order they are made.

Retrieve a format set

PermissionBrand · Read

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

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 set

PermissionBrand · Write

Creates the format set with this key, or replaces it if it already exists. The body is strict JSON, and its key must equal the one in the path. Every format it lists must exist, or the request is refused with 400 and field. 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 set’s display name.

  • keystringRequired

    The format set’s key. Unique in the organisation.

  • formatsarray of stringsOptionalNullable

    The keys of the formats in this set, in the order they are made.

Returns

The stored (canonical) document.

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

PermissionBrand · Read

Returns every format set (a named group of formats) the organisation has, sorted by key.

Returns

Every format set.

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

PermissionBrand · Write

Deletes the format set. If a campaign still uses it, the request is refused with 400.

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

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.