JavaScript SDK
JavaScript SDK
@withmestra/sdk is a typed JavaScript client for the Mestra API, with helpers for editing designs. You open a size or a master, change it by role (the headline, the button), look at the result and save. Mestra’s servers do all the drawing. The package never draws anything: it sends your edits and brings back the picture.
Install
npm install @withmestra/sdkIt runs in Node 20 or later and in browsers. This page covers version 0.2.0.
Make a client
You need an API key, which starts ptk_. An owner or team member makes it in Settings, then API. To edit designs, the key needs the Designs permission: read opens, checks and previews, and write makes edits and saves. The presets don’t include Designs, so choose Custom permissions. See Authentication.
import { createMestra,} from "@withmestra/sdk";
const mestra = createMestra({ token: process.env.MESTRA_KEY! });createMestra takes these options:
token: your API key. Required.baseUrl: the origin to call. The default ishttps://app.withmestra.com. A trailing/api/v1is accepted and dropped.fetch: your ownfetchfunction, if you don’t want the global one.
Keep the key on a server. Don’t put it in a web page.
A first edit
// The run's id and the size's key.const size = await mestra.openSize("run-4f2a", "300x250");
const answer = await size.edit("set_text", { role: "headline", text: "Summer sale, this week" });if (answer.refused) { console.log(answer.refused, answer.detail); // nothing was changed}
const picture = await size.preview(); // picture.png holds a PNGconst saved = await size.save(); // free; joins the run's reviewconsole.log(saved.sceneHash, saved.round);To find the sizes of a run that can be opened, call mestra.editable(runId). It answers with the API’s own list.
Where to next
- Editing sizes: edit, check, preview and save one size.
- Editing masters: the same for a master, with its own edits.
- Editing many sizes: one edit across a campaign, and saving the results.
- Errors: what the SDK throws and what it returns as data.
Each page matches an API guide: Editing a size and Editing a master. The API reference lists every endpoint.
Any other API call
mestra.api is a typed client for every other call in the API. It is made from the same OpenAPI file as the reference, and it sends your key for you.
const { data, error } = await mestra.api.GET("/api/v1/campaigns");if (error) throw new Error("The campaigns call failed.");console.log(data);The package also exports the types paths, components and operations.
Versions
The package follows version 1 of the API. New fields can appear, so read answers defensively and ignore fields you don’t know.