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 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”
409
api_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.
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.
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.”).
401
invalid_token
The key is missing, unknown, revoked or expired (code invalid_token). Send it as Authorization: Bearer <key>.
403
wrong_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.
409
api_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.
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).
409
api_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”.
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
Status
Code
Meaning
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.”).
401
invalid_token
The key is missing, unknown, revoked or expired (code invalid_token). Send it as Authorization: Bearer <key>.
403
wrong_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”
409
api_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.