Common Workflows

The embed is the editing surface. Your backend should still use the Moda Public API for account-level and workflow-level operations.

Let users choose a canvas

Use the Public API to list or search canvases, then create an embed session for the selected canvas. A canvas in either response is a CanvasItem. The title field is name (not title), and neither endpoint returns a thumbnail — render the picker from name/category/updated_at, or open the canvas to get a preview.

CanvasItem

type CanvasItem = {
  id: string; // prefixed `cvs_...`
  name: string; // display name — the title field
  url: string; // opens the canvas in the Moda editor
  category: string | null; // 'slides' | 'social' | 'pdf' | 'diagram' | ... | null
  visibility: string | null; // 'team' | 'private'
  created_at: string | null; // ISO 8601
  updated_at: string | null;
  created_by: { id: string; name: string; email: string } | null;
};

The two endpoints use different envelope keys — list is cursor-paginated under data, search is a flat list under canvases:

List canvases — { data, next_cursor }

async function listCanvases(cursor?: string) {
  const url = new URL("https://api.moda.app/v1/canvases");
  if (cursor) url.searchParams.set("cursor", cursor);
  url.searchParams.set("limit", "50"); // 1–100, defaults to 20

  const response = await fetch(url, {
    headers: {
      Authorization: `Bearer ${process.env.MODA_API_KEY}`,
      "Moda-Version": "2026-05-01",
    },
  });

  if (!response.ok) throw new Error("Failed to list canvases");
  return response.json() as Promise<{
    data: CanvasItem[];
    next_cursor: string | null;
  }>;
}

Search canvases — { canvases }

async function searchCanvases(query: string) {
  const url = new URL("https://api.moda.app/v1/canvases/search");
  url.searchParams.set("q", query);
  url.searchParams.set("limit", "20");

  const response = await fetch(url, {
    headers: {
      Authorization: `Bearer ${process.env.MODA_API_KEY}`,
      "Moda-Version": "2026-05-01",
    },
  });

  if (!response.ok) throw new Error("Failed to search canvases");
  return response.json() as Promise<{ canvases: CanvasItem[] }>; // note: `canvases`, not `data`; no cursor
}

Page through the full list with next_cursor until it comes back null:

let cursor: string | undefined;
const all: CanvasItem[] = [];
do {
  const { data, next_cursor } = await listCanvases(cursor);
  all.push(...data);
  cursor = next_cursor ?? undefined;
} while (cursor);

Build a canvas picker

Recommended flow:

User opens your “Choose design” screen.
Your backend calls GET /v1/canvases or GET /v1/canvases/search.
Your frontend shows the result list.
User selects a canvas.
Your backend creates an embed session for that canvas.
Your frontend loads the returned embed_url.

Do not create embed sessions for every canvas in the list. Create one only when the user opens a canvas.

Restrict canvases in an internal tool

Your app should remain the policy decision point. Moda can pin an embed session to one canvas, one mode, and one set of allowed browser origins, but your backend should decide which internal users may see or edit each canvas before creating the session. Recommended pattern:

Store the mapping between your internal users, teams, projects, or roles and the Moda canvas IDs they may access.
When a user opens your picker, call the Moda Public API from your backend and filter the results against that mapping before returning them to the browser.
When the browser asks to open a canvas, do not trust the submitted canvas_id. Re-check the current internal user against your access mapping on the backend.
Create the embed session only after that check passes.
Set mode from your app’s authorization result. For example, reviewers get view-no-export or view; editors get edit.
Set external_user.id to your stable internal user ID for attribution and audit trails.
Revoke active sessions when the user signs out, changes role, or loses access to the underlying project.

Backend authorization sketch

async function openCanvasForUser(userId: string, requestedCanvasId: string) {
  const grant = await db.canvasAccess.findFirst({
    where: { userId, modaCanvasId: requestedCanvasId },
  });

  if (!grant) {
    throw new Response("Not found", { status: 404 });
  }

  const mode = grant.canEdit
    ? "edit"
    : grant.canExport
      ? "view"
      : "view-no-export";

  return createModaEmbedSession({
    canvas_id: requestedCanvasId,
    mode,
    external_user: {
      id: userId,
      email: grant.email,
      name: grant.displayName,
    },
    allowed_origins: ["https://internal.example.com"],
    ui: {
      toolbar: grant.canEdit ? "secondary" : "hidden",
      chat: grant.canUseAgent ? "external" : "hidden",
    },
    expires_in_seconds: 1800,
  });
}

For larger workspaces, avoid relying only on client-side filtering. Keep a server-side allowlist, project membership table, or policy check that runs both when listing canvases and when minting the embed session.

Save and autosave

Edit-mode embeds autosave after user edits. You can still call manual save before an important transition:

client.post("save");

Listen for canvas:saved before closing a modal or advancing your workflow:

client.on("canvas:saved", (payload: any) => {
  markStepComplete(payload.version);
});

Use your own chat UI

Create sessions with:

{
  "ui": {
    "chat": "external",
    "toolbar": "secondary"
  }
}

Then send messages from your UI:

client.post("chat.send", { message: userMessage });

Render agent output from events:

client.on("chat:message", (payload: any) => {
  appendChatBubble(payload.sender, payload.text);
});

client.on("chat:progress", (payload: any) => {
  appendStreamingProgress(payload);
});

client.on("chat:canvas_update", () => {
  showToast("Canvas updated");
});

Use chat.stop to cancel the active agent turn.

Insert user-uploaded images

If the user picks an image in your app, send the File to the iframe. The iframe uploads it through the embed image endpoint and inserts a real Moda image node. Embed uploads currently accept PNG, JPEG, GIF, and WebP files up to 25 MB. If you need SVG or larger asset handling, upload through your own workflow and pass a browser-renderable HTTPS URL to insertImage.

const file = input.files?.[0];
if (file) {
  client.post("insertImage", {
    file,
    filename: file.name,
    mimeType: file.type,
    width: 500,
  });
}

The user can also paste images directly into the iframe. The embed handles screenshots and image files from the clipboard.

Insert server-generated images

If your backend generates an image, prefer one of these:

Option	When to use
Pass a temporary HTTPS URL to `insertImage`	The URL is reachable by the browser and stable long enough for rendering
Download the image in your frontend and pass a `Blob`	You want the embed upload endpoint to persist the asset with the canvas
Use the Public API upload flow first	You need a broader server-side asset workflow outside the embed

Example with a URL:

client.post("insertImage", {
  url: generatedImageUrl,
  x: 100,
  y: 100,
  width: 600,
});

Export from the iframe

Use iframe export when the user needs the file immediately in the browser.

client.post("export", { format: "png", page: 1 });

export:completed includes a job envelope — jobId, downloadUrl and warnings — for every format; the artifact is built on Moda’s servers and your page fetches it from the URL. The SDK still waits for the job with a ~120s completion timeout. Use Public API export when your backend needs a durable export URL, background polling, caching, a server-side workflow, or whenever the document is large or multi-page:

POST /v1/canvases/{canvas_id}/export?format=pdf&wait=true
Authorization: Bearer moda_live_...
Moda-Version: 2026-05-01

Refresh long-running sessions

Sessions can last up to 3600 seconds. For long editing sessions:

Track expires_at from session creation.
Set a timer to refresh from your backend before expiry (for example, 60s ahead).
Send the new token to the iframe with session.refresh; the iframe replies session:refreshed { expiresAt }.

function scheduleRefresh(expiresAt: string) {
  const refreshAheadMs = 60_000;
  const delay = Math.max(
    0,
    new Date(expiresAt).getTime() - Date.now() - refreshAheadMs,
  );

  return setTimeout(async () => {
    const refreshed = await fetch("/api/moda-embed/refresh", {
      method: "POST",
      body: JSON.stringify({ sessionId }),
    }).then((response) => response.json());

    client.post("session.refresh", {
      token: new URL(refreshed.embed_url).searchParams.get("token"),
      expiresAt: refreshed.expires_at,
      browserToken: refreshed.browser_token,
      browserTokenExpiresAt: refreshed.browser_token_expires_at,
    });

    scheduleRefresh(refreshed.expires_at); // chain the next refresh off the new expiry
  }, delay);
}

client.on("session:refreshed", ({ expiresAt }: { expiresAt: string }) => {
  console.log("Session refreshed until", expiresAt);
});

Instead of computing your own timer, you can drive the refresh off the iframe’s proactive session:refresh_requested event, which fires ahead of expiry (by default 60 seconds before the browser token lapses):

client.on("session:refresh_requested", async () => {
  const refreshed = await fetch("/api/moda-embed/refresh", {
    method: "POST",
    body: JSON.stringify({ sessionId }),
  }).then((response) => response.json());

  client.post("session.refresh", {
    token: new URL(refreshed.embed_url).searchParams.get("token"),
    expiresAt: refreshed.expires_at,
    browserToken: refreshed.browser_token,
    browserTokenExpiresAt: refreshed.browser_token_expires_at,
  });
});

// If a refresh never lands, react to expiry:
client.on("session:expired", () => promptReauthentication());

Recover from full expiry — create, don’t refresh

A refresh loop only works while the session is alive. If your refresh cadence ever stops — your job runner pauses, the user’s laptop sleeps, a background tab gets suspended — the session expires for good (sessions cap at 3600 seconds), and the embedded tab that later wakes up cannot be recovered by refreshing:

POST /v1/embed/sessions/{session_id}/refresh returns 404 once the session record is gone (or 409 while an expired/revoked record lingers). Calling it on a timer forever is the classic broken integration: the iframe stays dead while your backend 404s. Keep it up on one session_id and the API answers 410 Gone (embed_session_gone) — a stop, with no Retry-After, because the id is gone for good and waiting changes nothing.
The iframe emits session:expired (once) and stops: live sync is closed with a terminal code and not retried, so edits made in that tab are not being saved until you act.

The recovery is the same call you made to mount the embed in the first place — create a new session and swap it in:

let recovering = false; // expired + revoked can both fire — mint ONE session

const recover = async (payload: { scope?: string }) => {
  if (recovering) return;
  recovering = true;
  try {
    // scope 'browser_token': the outer session may still be alive — a refresh
    // preserves the running iframe (and unflushed edits) where a reload would
    // not. Fall through to create ONLY on 404/409/410, which prove it is dead
    // (410 = too many failed refreshes of this id, and it is terminal);
    // treat 5xx/network as transient and keep the iframe for a later retry.
    if (payload?.scope === "browser_token") {
      const refreshed = await fetch("/api/moda-embed/refresh", {
        method: "POST",
        body: JSON.stringify({ sessionId: client.sessionId }),
      });
      if (refreshed.ok) {
        const data = await refreshed.json();
        client.post("session.refresh", {
          token: new URL(data.embed_url).searchParams.get("token"),
          expiresAt: data.expires_at,
          browserToken: data.browser_token,
          browserTokenExpiresAt: data.browser_token_expires_at,
        });
        return;
      }
      if (![404, 409, 410].includes(refreshed.status)) return;
    }

    // POST /v1/embed/sessions from your backend — NOT .../refresh.
    const response = await fetch("/api/moda-embed/create", {
      method: "POST",
      body: JSON.stringify({ canvasId }),
    });
    if (!response.ok) return; // transient — keep the old client, retry later
    const session = await response.json();
    if (!session?.session_id || !session?.embed_url) return;

    // New session = new session id: replace the client and reload the iframe.
    client.destroy();
    client = new ModaEmbedClient(iframe, session.session_id, session.embed_url);
    registerEmbedListeners(client); // your listener setup, including this handler
    iframe.src = session.embed_url;
  } finally {
    recovering = false;
  }
};

client.on("session:expired", recover);
client.on("session:revoked", recover);

Rule of thumb: session:refresh_requested → refresh; session:expired / session:revoked → recover as above. The handler branches on scope: a 'browser_token' expiry tries the edit-preserving refresh first and only creates once the backend proves the session dead (404/409); a 'session' expiry goes straight to create. Keep the recovery idempotent either way — both terminal events can fire for the same dead session — and see the annotated variant in the Browser SDK page for the full rationale.

Edits made in a tab after its session fully expired are not persisted — the session that authorized writes no longer exists, and they are not carried into the replacement session. A healthy refresh loop is what protects unsaved work; the create-on-expired handler is the backstop that stops a dead tab from failing silently.

Revoke on logout or close

Call revoke when access should end:

await fetch("/api/moda-embed/revoke", {
  method: "POST",
  body: JSON.stringify({ sessionId }),
});

Your backend should call:

DELETE /v1/embed/sessions/{session_id}
Authorization: Bearer moda_live_...
Moda-Version: 2026-05-01

Should you build an API wrapper?

Most teams do best with two small clients:

Client	Location	Purpose
`ModaEmbedClient`	Browser	Iframe commands and events only
`ModaApiClient`	Backend	Thin wrapper around the Moda Public API

Avoid a browser SDK that exposes general Moda API calls. It would either leak your API key or require your backend to proxy every possible operation. A backend wrapper is useful if your app uses several Public API endpoints:

class ModaApiClient {
  constructor(private apiKey: string) {}

  private request(path: string, init: RequestInit = {}) {
    return fetch(`https://api.moda.app/v1${path}`, {
      ...init,
      headers: {
        Authorization: `Bearer ${this.apiKey}`,
        "Moda-Version": "2026-05-01",
        "Content-Type": "application/json",
        ...init.headers,
      },
    });
  }

  listCanvases() {
    return this.request("/canvases");
  }

  createEmbedSession(body: unknown) {
    return this.request("/embed/sessions", {
      method: "POST",
      body: JSON.stringify(body),
    });
  }
}

Keep the wrapper thin so you can call new Public API endpoints without waiting for a browser SDK release.

Start here

Integration guides

Common Workflows

Let users choose a canvas

Build a canvas picker

Restrict canvases in an internal tool

Save and autosave

Use your own chat UI

Insert user-uploaded images

Insert server-generated images

Export from the iframe

Refresh long-running sessions

Recover from full expiry — create, don’t refresh

Revoke on logout or close

Should you build an API wrapper?

​Let users choose a canvas

​Build a canvas picker

​Restrict canvases in an internal tool

​Save and autosave

​Use your own chat UI

​Insert user-uploaded images

​Insert server-generated images

​Export from the iframe

​Refresh long-running sessions

​Recover from full expiry — create, don’t refresh

​Revoke on logout or close

​Should you build an API wrapper?

​Related Public API docs

Let users choose a canvas

Build a canvas picker

Restrict canvases in an internal tool

Save and autosave

Use your own chat UI

Insert user-uploaded images

Insert server-generated images

Export from the iframe

Refresh long-running sessions

Recover from full expiry — create, don’t refresh

Revoke on logout or close

Should you build an API wrapper?

Related Public API docs