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
namestringRequiredThe format’s display name.
keystringRequiredThe format’s key: its identifier in format sets and runs. Unique in the organisation.
widthnumberRequiredWidth, in
unit.heightnumberRequiredHeight, in
unit.unitstringRequiredThe unit of
width,height,bleedandsafeMargin:px,mmorpt. Type sizes are always in points.Possible values
pxmmptdpinumberOptionalNullableResolution in dots per inch. Needed for
mmformats; usually null forpxandpt.exportScaleintegerOptionalpx 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.
bleednumberOptionalBleed beyond the trim, in
unit. A format with a bleed is a print size.safeMarginnumberOptionalThe margin kept clear of important content, in
unit.familystringOptionalThe kind of output (for example
print,social,weborscreen). It decides defaults such as the export scale.requirearray of stringsOptionalNullableElements every layout of this format must keep:
cta,qr. Null or empty for none.droparray of stringsOptionalNullableRoles left out of this format (for example
subhead). Null or empty for none.minTypeSizeobjectOptionalNullableSmallest type size per role, in points.
exportFormatsarray of stringsOptionalNullableThe file types a review of this format can export (for example
png,jpg,pdf). Null for the defaults.reviewPolicystringRequiredalwayschecks every layout of this format;skip-if-cleanskips the check when the layout is already clean.copyOverridesobjectOptionalNullableWording that replaces the campaign’s own for this format, by role. Each value is up to 2,000 characters.
Retrieve a format
Returns the format with this key, exactly as it was saved.
Path parameters
keystringRequiredThe document’s key (a brand’s code).
Returns
The document.
Returns the Format 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 format” | |
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 format
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
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 format’s display name.
keystringRequiredThe format’s key: its identifier in format sets and runs. Unique in the organisation.
widthnumberRequiredWidth, in
unit.heightnumberRequiredHeight, in
unit.unitstringRequiredThe unit of
width,height,bleedandsafeMargin:px,mmorpt. Type sizes are always in points.Possible values
pxmmptdpinumberOptionalNullableResolution in dots per inch. Needed for
mmformats; usually null forpxandpt.exportScaleintegerOptionalpx 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.
bleednumberOptionalBleed beyond the trim, in
unit. A format with a bleed is a print size.safeMarginnumberOptionalThe margin kept clear of important content, in
unit.familystringOptionalThe kind of output (for example
print,social,weborscreen). It decides defaults such as the export scale.requirearray of stringsOptionalNullableElements every layout of this format must keep:
cta,qr. Null or empty for none.droparray of stringsOptionalNullableRoles left out of this format (for example
subhead). Null or empty for none.minTypeSizeobjectOptionalNullableSmallest type size per role, in points.
exportFormatsarray of stringsOptionalNullableThe file types a review of this format can export (for example
png,jpg,pdf). Null for the defaults.reviewPolicystringRequiredalwayschecks every layout of this format;skip-if-cleanskips the check when the layout is already clean.copyOverridesobjectOptionalNullableWording 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
| 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 formats
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
| 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 format
Deletes the format. If a format set or campaign still uses it, the request is refused with 400 and field names 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 format” | |
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 or create a format for a size
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
wnumberRequiredhnumberRequiredunitstringOptionalPossible values
pxmm
Returns
The format.
An object with:
keystringRequirednamestringRequiredwidthnumberRequiredheightnumberRequiredunitstringRequiredPossible values
pxmm
Errors
| Status | Code | Meaning |
|---|---|---|
400 | bad_custom_size | The size is refused ( |
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
409 | api_off |
|
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. |