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
403andwrong_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-campaignand the brand’s code ascentre.
Open a session
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 ispxormm, 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:
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.masterandifMatch:null, because nothing is stored yet.elements: empty.sizes: each ticked size, with itskey,name,width,height,unitandscreenSpec, ornull.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:
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}}}'idis made by you. It readsmand ten of0-9a-z. Otherwise it is refused asbad-id, andid-takenwhen the design already holds it.kindistext,shape,image,line,polygonorstar.frameisx,y,wandhin the page’s units. Atextmay leavehout, and the box is then one line high. Alinetakesfromandtoinstead of a frame.- A
texttakestextwith itsparagraphs. Ashapetakesshape(rect,ellipseorpath) andfill. Apolygontakessides, and astartakespointsandinnerRatio. - An
imagenamesimagewith theasset(the SHA-256 of a picture you uploaded into the session), orlogowith thevariantof the brand’s own logo. The open answer lists the brand’s logos. A logo that isn’t there is404unknown_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
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,centreandsizes: 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
404withsession_gone. The session ended. Open the design again and redo the edits. A save you sent with anidempotencyKeycan still be sent again.422withempty_design. Add an element, then save again.409withdont_keep. Your organisation keeps no files, so nothing can be saved.404withheadless_off, ornot_editablefor a Network customer. Saved masters or the editor aren’t available to that organisation.503witheditor_unavailable. Try again shortly.