miro-migration-deep-dive

Miro Migration Deep Dive

Overview

Comprehensive migration strategies for Miro REST API v2: export entire board content, import structured data into boards, migrate between teams/organizations, and re-platform from competing whiteboard tools.

Migration Types

Type	Complexity	Duration	Approach
Export board content	Low	Minutes	Read all items, save as JSON
Import data into board	Medium	Minutes	Batch create items via API
Move boards between teams	Medium	Hours	Copy + re-share
Re-platform (Lucidchart/FigJam)	High	Days–Weeks	Export → transform → import
Full org migration	High	Weeks	SCIM + board migration + member mapping

Board Content Export

Export every item on a board to a structured JSON file:

interface BoardExport {
  exportedAt: string;
  board: {
    id: string;
    name: string;
    description: string;
    owner: { id: string; name: string };
  };
  items: ExportedItem[];
  connectors: ExportedConnector[];
  tags: ExportedTag[];
  members: ExportedMember[];
}

async function exportBoard(boardId: string): Promise<BoardExport> {
  // Get board metadata
  const board = await miroFetch(`/v2/boards/${boardId}`);

  // Get all items (cursor-paginated)
  const items: any[] = [];
  let cursor: string | undefined;
  do {
    const params = new URLSearchParams({ limit: '50' });
    if (cursor) params.set('cursor', cursor);
    const page = await miroFetch(`/v2/boards/${boardId}/items?${params}`);
    items.push(...page.data);
    cursor = page.cursor;
  } while (cursor);

  // Get all connectors
  const connectors: any[] = [];
  cursor = undefined;
  do {
    const params = new URLSearchParams({ limit: '50' });
    if (cursor) params.set('cursor', cursor);
    const page = await miroFetch(`/v2/boards/${boardId}/connectors?${params}`);
    connectors.push(...page.data);
    cursor = page.cursor;
  } while (cursor);

  // Get all tags
  const tags = await miroFetch(`/v2/boards/${boardId}/tags`);

  // Get board members
  const members = await miroFetch(`/v2/boards/${boardId}/members?limit=100`);

  return {
    exportedAt: new Date().toISOString(),
    board: {
      id: board.id,
      name: board.name,
      description: board.description ?? '',
      owner: { id: board.owner?.id, name: board.owner?.name },
    },
    items: items.map(normalizeItem),
    connectors: connectors.map(normalizeConnector),
    tags: tags.data ?? [],
    members: members.data ?? [],
  };
}

function normalizeItem(item: any) {
  return {
    id: item.id,
    type: item.type,
    data: item.data,
    style: item.style,
    position: item.position,
    geometry: item.geometry,
    parentId: item.parent?.id,
    createdAt: item.createdAt,
    createdBy: item.createdBy?.id,
  };
}

Import Data into a Board

Recreate exported items on a new board:

import PQueue from 'p-queue';

interface ImportResult {
  created: number;
  failed: number;
  errors: Array<{ item: any; error: string }>;
  idMap: Map<string, string>;  // Old ID → New ID
}

async function importToBoard(
  targetBoardId: string,
  exportData: BoardExport,
  options: { offsetX?: number; offsetY?: number } = {}
): Promise<ImportResult> {
  const queue = new PQueue({ concurrency: 3, interval: 1000, intervalCap: 8 });
  const result: ImportResult = { created: 0, failed: 0, errors: [], idMap: new Map() };

  // Phase 1: Create items (excluding frames first, then frames)
  const frames = exportData.items.filter(i => i.type === 'frame');
  const nonFrames = exportData.items.filter(i => i.type !== 'frame');

  // Create frames first (they contain other items)
  for (const frame of frames) {
    await queue.add(async () => {
      try {
        const newItem = await createItemByType(targetBoardId, frame, options);
        result.idMap.set(frame.id, newItem.id);
        result.created++;
      } catch (err: any) {
        result.failed++;
        result.errors.push({ item: frame, error: err.message });
      }
    });
  }
  await queue.onIdle();

  // Then create other items
  for (const item of nonFrames) {
    await queue.add(async () => {
      try {
        const newItem = await createItemByType(targetBoardId, item, options);
        result.idMap.set(item.id, newItem.id);
        result.created++;
      } catch (err: any) {
        result.failed++;
        result.errors.push({ item, error: err.message });
      }
    });
  }
  await queue.onIdle();

  // Phase 2: Recreate connectors using new IDs
  for (const connector of exportData.connectors) {
    const newStartId = result.idMap.get(connector.startItem?.id);
    const newEndId = result.idMap.get(connector.endItem?.id);
    if (!newStartId || !newEndId) continue;

    await queue.add(async () => {
      try {
        await miroFetch(`/v2/boards/${targetBoardId}/connectors`, 'POST', {
          startItem: { id: newStartId },
          endItem: { id: newEndId },
          captions: connector.captions,
          style: connector.style,
          shape: connector.shape,
        });
        result.created++;
      } catch (err: any) {
        result.errors.push({ item: connector, error: err.message });
      }
    });
  }
  await queue.onIdle();

  // Phase 3: Recreate tags
  for (const tag of exportData.tags) {
    await queue.add(async () => {
      try {
        await miroFetch(`/v2/boards/${targetBoardId}/tags`, 'POST', {
          title: tag.title,
          fillColor: tag.fillColor,
        });
      } catch (err: any) {
        // Duplicate tag titles return 409 — safe to ignore
        if (!err.message?.includes('409')) {
          result.errors.push({ item: tag, error: err.message });
        }
      }
    });
  }
  await queue.onIdle();

  return result;
}

async function createItemByType(
  boardId: string,
  item: any,
  options: { offsetX?: number; offsetY?: number }
) {
  const position = {
    x: (item.position?.x ?? 0) + (options.offsetX ?? 0),
    y: (item.position?.y ?? 0) + (options.offsetY ?? 0),
  };

  const endpointMap: Record<string, string> = {
    sticky_note: 'sticky_notes',
    shape: 'shapes',
    card: 'cards',
    text: 'texts',
    frame: 'frames',
    image: 'images',
    document: 'documents',
    embed: 'embeds',
    app_card: 'app_cards',
  };

  const endpoint = endpointMap[item.type];
  if (!endpoint) throw new Error(`Unsupported item type: ${item.type}`);

  return miroFetch(`/v2/boards/${boardId}/${endpoint}`, 'POST', {
    data: item.data,
    style: item.style,
    position,
    geometry: item.geometry,
  });
}

Board Duplication Between Teams

async function duplicateBoard(
  sourceBoardId: string,
  targetTeamId: string,
  newName: string,
): Promise<{ newBoardId: string; importResult: ImportResult }> {
  // Step 1: Export source board
  console.log('Exporting source board...');
  const exportData = await exportBoard(sourceBoardId);

  // Step 2: Create new board in target team
  console.log('Creating target board...');
  const newBoard = await miroFetch('/v2/boards', 'POST', {
    name: newName,
    description: exportData.board.description,
    teamId: targetTeamId,
  });

  // Step 3: Import all content
  console.log('Importing items...');
  const importResult = await importToBoard(newBoard.id, exportData);

  console.log(`Done! Created ${importResult.created} items, ${importResult.failed} failed`);
  return { newBoardId: newBoard.id, importResult };
}

CSV/Spreadsheet Import

Import structured data (from spreadsheets, Jira, etc.) as Miro items:

interface CsvRow {
  title: string;
  description?: string;
  category?: string;
  priority?: string;
}

async function importCsvAsCards(
  boardId: string,
  rows: CsvRow[],
  layout: 'grid' | 'column' = 'grid'
): Promise<ImportResult> {
  const result: ImportResult = { created: 0, failed: 0, errors: [], idMap: new Map() };
  const queue = new PQueue({ concurrency: 3, interval: 1000, intervalCap: 8 });

  // Color mapping for categories
  const categoryColors: Record<string, string> = {
    bug: '#ff6b6b',
    feature: '#2d9bf0',
    improvement: '#51cf66',
    default: '#868e96',
  };

  for (let i = 0; i < rows.length; i++) {
    const row = rows[i];
    const x = layout === 'grid' ? (i % 5) * 300 : 0;
    const y = layout === 'grid' ? Math.floor(i / 5) * 200 : i * 200;

    await queue.add(async () => {
      try {
        const card = await miroFetch(`/v2/boards/${boardId}/cards`, 'POST', {
          data: {
            title: row.title,
            description: row.description ?? '',
          },
          style: {
            cardTheme: categoryColors[row.category?.toLowerCase() ?? 'default'] ?? categoryColors.default,
          },
          position: { x, y },
        });

        // Add priority as tag
        if (row.priority) {
          try {
            const tag = await miroFetch(`/v2/boards/${boardId}/tags`, 'POST', {
              title: row.priority,
              fillColor: row.priority === 'High' ? 'red' : 'yellow',
            });
            await miroFetch(`/v2/boards/${boardId}/items/${card.id}/tags`, 'POST', {
              tagId: tag.id,
            });
          } catch {
            // Tag might already exist — acceptable
          }
        }

        result.created++;
      } catch (err: any) {
        result.failed++;
        result.errors.push({ item: row, error: err.message });
      }
    });
  }

  await queue.onIdle();
  return result;
}

Migration Validation

async function validateMigration(
  sourceBoardId: string,
  targetBoardId: string,
): Promise<ValidationReport> {
  const sourceItems = await fetchAllItems(sourceBoardId);
  const targetItems = await fetchAllItems(targetBoardId);

  const sourceConnectors = await fetchAllConnectors(sourceBoardId);
  const targetConnectors = await fetchAllConnectors(targetBoardId);

  const checks = [
    {
      name: 'Item count match',
      pass: targetItems.length >= sourceItems.length * 0.95,  // 95% threshold
      detail: `Source: ${sourceItems.length}, Target: ${targetItems.length}`,
    },
    {
      name: 'Item types match',
      pass: compareTypeCounts(sourceItems, targetItems),
      detail: getTypeCountDiff(sourceItems, targetItems),
    },
    {
      name: 'Connectors migrated',
      pass: targetConnectors.length >= sourceConnectors.length * 0.9,
      detail: `Source: ${sourceConnectors.length}, Target: ${targetConnectors.length}`,
    },
  ];

  return {
    passed: checks.every(c => c.pass),
    checks,
    summary: `${checks.filter(c => c.pass).length}/${checks.length} checks passed`,
  };
}

Rollback Plan

async function rollbackMigration(
  targetBoardId: string,
  importResult: ImportResult,
): Promise<void> {
  console.log(`Rolling back: deleting ${importResult.created} items from ${targetBoardId}`);

  const queue = new PQueue({ concurrency: 5 });
  for (const [, newId] of importResult.idMap) {
    queue.add(async () => {
      await miroFetch(`/v2/boards/${targetBoardId}/items/${newId}`, 'DELETE').catch(() => {});
    });
  }
  await queue.onIdle();

  console.log('Rollback complete');
}

Error Handling

Issue	Cause	Solution
Rate limited during import	Too many items	Reduce concurrency, increase interval
Connector fails	Referenced item wasn't created	Check idMap for missing mappings
Image URL 404	External image no longer available	Skip or replace with placeholder
Position overlap	No offset applied	Use offsetX/offsetY options
Tag duplicate	Tag title already exists	Catch 409, reuse existing tag

Resources

• REST API Reference Guide
• Board Items
• REST API Comparison (v1 vs v2)
• Miro App Examples

Next Steps

This is the final Flagship skill. For starting a new integration from scratch, see miro-install-auth.