Skip to content

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

Shell
npm install @withmestra/sdk

It 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.

TypeScript
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 is https://app.withmestra.com. A trailing /api/v1 is accepted and dropped.
  • fetch: your own fetch function, 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

TypeScript
// 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 PNG
const saved = await size.save(); // free; joins the run's review
console.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

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.

TypeScript
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.