Skip to content

API reference

Starting a design

You can start a design from nothing from your own code. Open a new design for a campaign, or for none, add elements, look at the result, then save. The first save makes a master, and you start a run from it.

This guide builds on Editing a size and Editing a master: sessions, checks, previews and saves work the same way. Read them first. Here is what differs for a new design. Agents can use the MCP op sizes.new_design.

What you need

  • A key with the Designs · Write permission, and Campaigns · Read. A key without Campaigns · Read is refused with 403 and wrong_key, because the design is made of the campaign’s name and sizes. See Authentication.
  • A campaign key, and for a campaign of several brands, the brand’s code as centre. Or, for a design with no campaign, no-campaign and the brand’s code as centre.

Open a session

Shell
curl -X POST https://app.withmestra.com/api/v1/designs/new/edit \
-H "Authorization: Bearer $MESTRA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"campaign": "spring", "sizes": ["mrec", "tall"], "designAt": {"format": "mrec"}}'
  • campaign: the campaign’s key.
  • sizes: the campaign’s size keys ticked for the design’s first run. Left out, it is every size of the campaign for the brand. [] ticks none.
  • designAt: the page the design is drawn at. Send {"format": "<one of the ticked sizes>"} or {"custom": {"w": 1080, "h": 1920, "unit": "px"}}. The unit is px or mm, and each side is from 1 to 20000. Left out, the page is the ticked size whose shape is the middle one of the set. Of equal ones, the larger.
  • centre: the brand of a campaign that has several. The first is used without it.

A design with no campaign

Send "campaign": "no-campaign". The design belongs to no campaign, so centre is required and sizes are keys of your own formats (left out, none). Add typed sizes in customSizes:

Shell
curl -X POST https://app.withmestra.com/api/v1/designs/new/edit \
-H "Authorization: Bearer $MESTRA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"campaign": "no-campaign", "centre": "ESP", "sizes": ["mrec"], "customSizes": [{"w": 300, "h": 250, "unit": "px"}], "designAt": {"custom": {"w": 300, "h": 250, "unit": "px"}}}'

customSizes is a list of {"w", "h", "unit"} (px or mm, each side 1 to 20,000). Each is made a format of your organisation, or an existing one of that size is reused, and joins the ticked sizes. Use POST /api/v1/formats/custom to get a size’s format key first. The Campaigns · Read permission isn’t needed for no-campaign if the key has Designs · Write and Brand · Read. A campaign design needs it as before. See Starting a run.

The master from the first save is named No campaign - <size name>.

The page takes that size’s safe area as its margins. The answer is the same as for a master, with:

  • draft: true.
  • master and ifMatch: null, because nothing is stored yet.
  • elements: empty.
  • sizes: each ticked size, with its key, name, width, height, unit and screenSpec, or null.
  • designAt: the page that was used, in the form you send it.

Send the session id in the X-Mestra-Edit-Session header on every later call.

A refusal names the field. 404 unknown_campaign. 400 size_not_in_campaign (the field is sizes[i]), bad_custom_size (with min and max), design_at_not_ticked, sizes_required and unknown_centre, and with no-campaign, centre_required (choose a brand) and bad_custom_size for a size in customSizes.

Add elements

Use POST /api/v1/edit/apply, as for a master. On an empty page, an edit that names an element is refused as unknown-ref.

add_element puts an element on top of the stacking:

Shell
curl -X POST https://app.withmestra.com/api/v1/edit/apply \
-H "Authorization: Bearer $MESTRA_TOKEN" \
-H "X-Mestra-Edit-Session: $SESSION" \
-H "Content-Type: application/json" \
-d '{"name": "add_element", "input": {"id": "m1a2b3c4d5e", "kind": "text", "frame": {"x": 40, "y": 30, "w": 600, "h": 120}}}'
  • id is made by you. It reads m and ten of 0-9a-z. Otherwise it is refused as bad-id, and id-taken when the design already holds it.
  • kind is text, shape, image, line, polygon or star.
  • frame is x, y, w and h in the page’s units. A text may leave h out, and the box is then one line high. A line takes from and to instead of a frame.
  • A text takes text with its paragraphs. A shape takes shape (rect, ellipse or path) and fill. A polygon takes sides, and a star takes points and innerRatio.
  • An image names image with the asset (the SHA-256 of a picture you uploaded into the session), or logo with the variant of the brand’s own logo. The open answer lists the brand’s logos. A logo that isn’t there is 404 unknown_logo.

Colours must be of the brand’s palette, or the edit is refused as style-refused. A number out of range is refused as bad-number, with the field in limit.

A new design also takes these edits: place_picture, set_picture, set_order, make_group, ungroup, release_clip, set_look, set_paras_paint, set_rotation, set_shape, and the master’s own set_opacity, set_role, set_text and set_style. An element you added comes out with drop. The API reference gives every field.

Upload a picture as for a master, with PUT /api/v1/edit/assets/{sha}.

Check and preview

POST /api/v1/edit/check and POST /api/v1/edit/preview work as for a size. Look at the preview before you save.

Save

Shell
curl -X PUT https://app.withmestra.com/api/v1/edit/save \
-H "Authorization: Bearer $MESTRA_TOKEN" \
-H "X-Mestra-Edit-Session: $SESSION" \
-H "Content-Type: application/json" \
-d '{"idempotencyKey": "6f0c2a4e-8d7b-4c59-9a43-1d2b7e5f9a10"}'

Leave out If-Match for the first save, or send 0 or draft. Any other value is 400 with the code if_match.

The first save makes the master. Its name is the campaign’s and the size it was designed at, such as Spring - Medium rectangle. If the brand already has a master with that name, it ends in (2). Its source app is mestra, and it is version 1. The answer is a master save’s, with version 1, ifMatch 1, status and pull set to none, plus:

  • master: the master, as opening a master gives it.
  • campaign, centre and sizes: what the design was opened for.

A design with nothing in it is refused with 422 and empty_design. An organisation that keeps no files gets 409 and dont_keep. Saving is free.

The session is now a session on that master at version 1. Its next save sends If-Match: 1 and makes version 2. A retry with the same idempotencyKey answers the first save, with the master, and makes no second one.

Start a run

Make the sizes with POST /api/v1/masters/{id}/runs using the master’s id. It needs the Runs · Write permission, and the master must be ready. A master that is still checking or not_ready answers 409 with not_ready. Send dryRun: true first to see which sizes it would make, without a charge. A design with no campaign is run with campaignKey no-campaign, its brand in centres and its sizes in formats and customSizes. See Starting a run.

When it goes wrong

  • 404 with session_gone. The session ended. Open the design again and redo the edits. A save you sent with an idempotencyKey can still be sent again.
  • 422 with empty_design. Add an element, then save again.
  • 409 with dont_keep. Your organisation keeps no files, so nothing can be saved.
  • 404 with headless_off, or not_editable for a Network customer. Saved masters or the editor aren’t available to that organisation.
  • 503 with editor_unavailable. Try again shortly.