Figma sync

Static Ads Lab ships with a Figma plugin that lets you pull an editable image ad's JSON tree into Figma, edit it visually, and sync the result back to the API.

Prerequisites

An editable image ad — a flat ad won't work.
The Static Ads Lab Figma plugin installed.
Your API key in the plugin's settings.

Round-trip flow

sequenceDiagram
  participant App as Your app
  participant API as Static Ads Lab API
  participant Figma as Figma + plugin
  App->>API: POST /v1/image-ads (editable: true)
  API-->>App: completed { current_json_tree }
  Figma->>API: Plugin loads ad by ID
  API-->>Figma: current_json_tree + figma_render_url
  Note over Figma: User edits in Figma
  Figma->>API: POST /v1/image-ads/sync (items)
  API-->>Figma: 200 { results }
  App->>API: GET /v1/image-ads/:id
  API-->>App: completed (new version)

Sync endpoint

The Figma plugin uses POST /v1/image-ads/sync to push edits back. Up to 10 ads per request:

await fetch("https://api.staticadslab.com/v1/image-ads/sync", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.SAL_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    items: [
      {
        id: "ia_...",
        current_json_tree: { /* updated tree */ },
        figma_render_base64: "iVBORw0KGgo...", // raw base64, no data: prefix
      },
    ],
  }),
});

Each successful sync creates a new version (iav_…).

You usually don't call this endpoint yourself — the plugin does it. But it's documented in case you're integrating Figma another way (e.g., a custom Figma extension).

When this is useful

A designer needs to make pixel-perfect tweaks beyond what the JSON tree exposes.
You want a human-in-the-loop step before publishing an ad.
You're A/B-testing manual Figma variants against the AI baseline.

Pitfalls

Sync only accepts editable ads. Flat ads have no tree to update.
figma_render_base64 is the raw PNG bytes, base64-encoded, without the data:image/png;base64, prefix.
The full tree is required when you change it. If you only want to update the rendered PNG without overwriting the tree, omit current_json_tree.
Up to 10 ads per call. Larger batches must be split.