How to Integrate Bolt.new with Mural

Mural integration starts with understanding which access level you have. If you have a Free or Team Mural account, you can use the embed approach immediately — no API credentials needed. If you have a Business or Enterprise account, you can additionally use the REST API for programmatic mural management. For the embed URL (works on all plans): open any mural in Mural, click the Share button in the top-right corner, select 'Get embed link', choose 'Visitor access' (view and collaborate without requiring a Mural account) or 'Member access', and copy the embed URL. It looks like `https://app.mural.co/embed/...`. This URL can be placed directly in an iframe in your Bolt.new app — no server-side code required. For the REST API (Business/Enterprise only): go to app.mural.co/api or navigate to your Mural workspace settings → Developers → API Access. Create a new API application and generate a Personal Access Token (PAT). The token is a long string starting with `eyJ...` (a JWT). Copy it immediately — it may not be shown again. Add it to your .env file as MURAL_API_TOKEN. You will also need your workspace ID, which appears in the Mural URL as `https://app.mural.co/t/{workspaceId}/...`. For API calls that create murals in a specific room, also note the room ID from `https://app.mural.co/t/{workspaceId}/r/{roomId}`. All API calls to Mural use the base URL `https://app.mural.co/api/public/v1`. The token goes in the Authorization header as `Bearer {token}`. Outbound calls to this URL work from Bolt's WebContainer during development.

1// lib/mural.ts
2const MURAL_API_BASE = 'https://app.mural.co/api/public/v1';
3
4export async function muralFetch<T = unknown>(
5  endpoint: string,
6  init: RequestInit = {}
7): Promise<T> {
8  const token = process.env.MURAL_API_TOKEN;
9  if (!token) {
10    throw new Error(
11      'MURAL_API_TOKEN is not set. Get it from app.mural.co → Settings → Developers. ' +
12      'Note: REST API access requires a Mural Business or Enterprise plan.'
13    );
14  }
15
16  const url = `${MURAL_API_BASE}${endpoint.startsWith('/') ? endpoint : '/' + endpoint}`;
17  const response = await fetch(url, {
18    ...init,
19    headers: {
20      Authorization: `Bearer ${token}`,
21      'Content-Type': 'application/json',
22      Accept: 'application/json',
23      ...init.headers,
24    },
25  });
26
27  if (!response.ok) {
28    const errorText = await response.text();
29    throw new Error(`Mural API ${response.status} ${endpoint}: ${errorText}`);
30  }
31
32  return response.json() as Promise<T>;
33}
34
35// Generate a Mural embed URL from a mural share link or ID
36export function getMuralEmbedUrl(muralShareLink: string): string {
37  // If it's already an embed URL, return as-is
38  if (muralShareLink.includes('/embed/')) return muralShareLink;
39  // Convert share link to embed URL format
40  return muralShareLink.replace('/t/', '/embed/t/');
41}

The Mural embed is the fastest path to showing a collaborative whiteboard inside your Bolt.new app. It requires no API credentials, works on all Mural plans, and functions immediately in Bolt's WebContainer preview. The iframe renders the full Mural experience — sticky notes, shapes, cursor tracking, and real-time collaboration — as if users were on app.mural.co directly. Mural's embed URLs are generated per-mural and include access control: you can set them to require Mural account login or allow anonymous visitor access. For internal tools, 'Member access' ensures only your workspace members can interact. For client portals where external stakeholders participate, 'Visitor access' lets anyone with the link join without needing a Mural account. The iframe embed has a few important configuration details. The sandbox attribute controls what the iframe is allowed to do — Mural requires at minimum `allow-same-origin allow-scripts allow-popups allow-forms` for full functionality. Without `allow-popups`, some Mural features (file upload, external links) may not work. Without `allow-same-origin`, Mural cannot store settings in the browser. For responsive embeds, set the iframe to `width: 100%` and control height explicitly — Mural does not auto-resize to fit its content. A height of 600-800px works well for most workshop use cases. On mobile, Mural embeds can be difficult to use — consider showing a 'Open in Mural' link on small screens instead of the embedded iframe. When building a project-specific Mural dashboard, store the embed URL in your database alongside other project data (Supabase, etc.) so each project can have its own associated mural without hardcoding URLs.

1// components/MuralEmbed.tsx
2'use client';
3import { useState } from 'react';
4
5interface MuralEmbedProps {
6  embedUrl: string;
7  title?: string;
8  height?: number;
9  showOpenLink?: boolean;
10}
11
12export function MuralEmbed({
13  embedUrl,
14  title = 'Mural Whiteboard',
15  height = 600,
16  showOpenLink = true,
17}: MuralEmbedProps) {
18  const [isLoaded, setIsLoaded] = useState(false);
19
20  // Convert share URL to embed URL if needed
21  const iframeUrl = embedUrl.includes('/embed/')
22    ? embedUrl
23    : embedUrl.replace('/t/', '/embed/t/');
24
25  return (
26    <div className="w-full">
27      {/* Desktop: show embed */}
28      <div className="hidden md:block relative">
29        {!isLoaded && (
30          <div
31            className="absolute inset-0 bg-gray-100 animate-pulse rounded-lg flex items-center justify-center"
32            style={{ height }}
33          >
34            <span className="text-gray-500 text-sm">Loading Mural...</span>
35          </div>
36        )}
37        <iframe
38          src={iframeUrl}
39          title={title}
40          width="100%"
41          height={height}
42          sandbox="allow-same-origin allow-scripts allow-popups allow-forms allow-pointer-lock"
43          allowFullScreen
44          onLoad={() => setIsLoaded(true)}
45          className="rounded-lg border border-gray-200"
46        />
47      </div>
48
49      {/* Mobile: show link only */}
50      <div className="md:hidden bg-gray-50 border border-gray-200 rounded-lg p-6 text-center">
51        <p className="text-gray-600 mb-3">Open this mural on a larger screen for the best experience</p>
52        {showOpenLink && (
53          <a
54            href={embedUrl}
55            target="_blank"
56            rel="noopener noreferrer"
57            className="inline-flex items-center gap-2 text-blue-600 hover:underline font-medium"
58          >
59            Open in Mural
60          </a>
61        )}
62      </div>
63
64      {showOpenLink && (
65        <div className="hidden md:flex justify-end mt-2">
66          <a
67            href={embedUrl}
68            target="_blank"
69            rel="noopener noreferrer"
70            className="text-sm text-gray-500 hover:text-gray-700 hover:underline"
71          >
72            Open in Mural ↗
73          </a>
74        </div>
75      )}
76    </div>
77  );
78}

With the Mural REST API (Business/Enterprise plans), you can programmatically list all murals in your workspace, filter them by room or workspace, and display them dynamically in your app without hardcoding embed URLs. This powers scenarios like a project portal that automatically shows the mural associated with each project. The primary listing endpoint is `GET /workspaces/{workspaceId}/murals`. This returns a paginated list of murals in your workspace with fields including `id`, `title`, `createdOn`, `updatedOn`, `shareLink`, `status`, and the room/workspace they belong to. Use `next` (cursor-based pagination) to fetch all pages for large workspaces. For room-specific murals: `GET /rooms/{roomId}/murals` returns only murals in that room. If your workspace is organized into rooms by client, project, or team, this lets you build workspace-aware navigation — showing the team lead only murals from their team's room. The `shareLink` in the API response is the full Mural URL. Converting it to an embed URL is straightforward: replace `/t/` with `/embed/t/` in the path. Store the shareLink in your database when creating murals programmatically, and generate embed URLs dynamically in your frontend. For searching and filtering murals, the list API supports `title` (fuzzy match), `status` (active, archived), and date range filters. This is useful for a mural library feature where team members can search for past workshop outputs by topic or date.

1// app/api/mural/murals/route.ts
2import { NextResponse } from 'next/server';
3import { muralFetch, getMuralEmbedUrl } from '@/lib/mural';
4
5interface MuralItem {
6  id: string;
7  title: string;
8  createdOn: number;
9  updatedOn: number;
10  shareLink: string;
11  status: string;
12}
13
14interface MuralListResponse {
15  value: MuralItem[];
16  next?: string;
17}
18
19export async function GET() {
20  const workspaceId = process.env.MURAL_WORKSPACE_ID;
21  if (!workspaceId) {
22    return NextResponse.json(
23      { error: 'MURAL_WORKSPACE_ID is not configured' },
24      { status: 500 }
25    );
26  }
27
28  const data = await muralFetch<MuralListResponse>(
29    `/workspaces/${workspaceId}/murals?limit=50`
30  );
31
32  const murals = (data.value ?? []).map(m => ({
33    id: m.id,
34    title: m.title,
35    createdOn: new Date(m.createdOn).toISOString(),
36    updatedOn: new Date(m.updatedOn).toISOString(),
37    shareLink: m.shareLink,
38    embedUrl: getMuralEmbedUrl(m.shareLink),
39    status: m.status,
40  }));
41
42  return NextResponse.json({ murals, total: murals.length });
43}

The Mural creation API (`POST /rooms/{roomId}/murals`) lets you generate new whiteboards on demand — useful for automating the setup of recurring workshops, creating dedicated murals for each new project or client, or building a self-service portal where team members can request a new whiteboard. The create request body requires `title` (the mural name) and optionally `roomId`, `workspaceId`, `templateId`, `backgroundColor`, `height`, and `width`. Templates are particularly valuable for standardized workshops — a retrospective template ensures every sprint retro starts with the same layout and sections. Template IDs can be found in your Mural workspace's template library. The created mural response includes the full mural object with the `shareLink` and `id`. Save these to your database immediately — you will need the ID if you want to add content later, and the shareLink for embedding. Store both `shareLink` and `id` so you have both the embed URL and the ability to make subsequent API calls on the specific mural. After creating a mural, Mural takes a few seconds to fully initialize the new whiteboard. If you embed the mural immediately after creation, it may show a loading screen briefly. Consider adding a polling check or a 3-second delay before redirecting users to the new mural. For deployment: all Mural API calls are outbound HTTP requests that work in Bolt's WebContainer during development. There is no webhook or incoming connection requirement for the create, list, or embed use cases. Deploy to Netlify when you are ready for production, and add your MURAL_API_TOKEN, MURAL_WORKSPACE_ID, and MURAL_DEFAULT_ROOM_ID environment variables in Netlify's dashboard.

1// app/api/mural/create/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3import { muralFetch, getMuralEmbedUrl } from '@/lib/mural';
4
5interface CreatedMural {
6  id: string;
7  title: string;
8  shareLink: string;
9  createdOn: number;
10}
11
12export async function POST(request: NextRequest) {
13  const { title, templateId, roomId } = await request.json();
14
15  if (!title?.trim()) {
16    return NextResponse.json({ error: 'title is required' }, { status: 400 });
17  }
18
19  const targetRoomId = roomId ?? process.env.MURAL_DEFAULT_ROOM_ID;
20  if (!targetRoomId) {
21    return NextResponse.json(
22      { error: 'roomId is required — set MURAL_DEFAULT_ROOM_ID in .env or pass roomId in request' },
23      { status: 400 }
24    );
25  }
26
27  const body: Record<string, unknown> = { title: title.trim() };
28  if (templateId) body.templateId = templateId;
29
30  const mural = await muralFetch<CreatedMural>(`/rooms/${targetRoomId}/murals`, {
31    method: 'POST',
32    body: JSON.stringify(body),
33  });
34
35  return NextResponse.json({
36    id: mural.id,
37    title: mural.title,
38    shareLink: mural.shareLink,
39    embedUrl: getMuralEmbedUrl(mural.shareLink),
40    createdOn: new Date(mural.createdOn).toISOString(),
41  }, { status: 201 });
42}