Migrate Miro integrations from REST API v1 to v2 and upgrade @mirohq/miro-api SDK.
Use when upgrading SDK versions, migrating v1 widget endpoints to v2 item endpoints,
or handling breaking changes in the Miro platform.
Trigger with phrases like "upgrade miro", "miro migration",
"miro v1 to v2", "update miro SDK", "miro breaking changes".
Migrate Miro integrations from REST API v1 to v2 and upgrade @mirohq/miro-api SDK.
Use when upgrading SDK versions, migrating v1 widget endpoints to v2 item endpoints,
or handling breaking changes in the Miro platform.
Trigger with phrases like "upgrade miro", "miro migration",
"miro v1 to v2", "update miro SDK", "miro breaking changes".
allowed-tools
Read, Write, Edit, Bash(npm:*), Bash(npx:*)
version
1.7.0
license
MIT
author
Jeremy Longshore <jeremy@intentsolutions.io>
tags
["saas","miro","migration","upgrade"]
compatibility
Designed for Claude Code
Miro Upgrade & Migration
Overview
Guide for migrating from Miro REST API v1 to v2, upgrading the @mirohq/miro-api SDK, and handling the key breaking changes between versions.
Prerequisites
Before applying this guide, confirm you have a Miro app or workspace appropriate to the task, a dedicated non-production board where changes can be tested safely, and only the OAuth scopes or administrative access the procedure requires.
Key Breaking Changes: v1 to v2
Terminology Changes
v1 Term
v2 Term
Notes
Widget
Item
All board elements renamed
Line
Connector
Lines renamed, gained captions and snapTo
Sticker
Sticky Note
Type value: sticky_note
Widget API (polymorphic)
Per-type endpoints
No more universal create endpoint
text property
content property
In data objects
shapeType
shape (in data)
Moved from style to data object
startWidget / endWidget
startItem / endItem
Connector endpoints
Board User Connection
Board Member
Sharing/permissions model
Endpoint Migration Map
# v1 (DEPRECATED) → v2 (CURRENT)
POST /v1/boards/{id}/widgets → POST /v2/boards/{id}/sticky_notes
POST /v2/boards/{id}/shapes
POST /v2/boards/{id}/cards
POST /v2/boards/{id}/texts
POST /v2/boards/{id}/frames
POST /v2/boards/{id}/images
POST /v2/boards/{id}/documents
POST /v2/boards/{id}/embeds
POST /v2/boards/{id}/app_cards
GET /v1/boards/{id}/widgets → GET /v2/boards/{id}/items
GET /v1/boards/{id}/widgets/{widget_id} → GET /v2/boards/{id}/items/{item_id}
(or type-specific: /v2/boards/{id}/sticky_notes/{item_id})
POST /v1/boards/{id}/widgets (type: line) → POST /v2/boards/{id}/connectors
GET /v1/boards/{id}/widgets?type=line → GET /v2/boards/{id}/connectors
Request Body Changes
// v1: Create a sticky note (via universal widgets endpoint)// POST /v1/boards/{id}/widgets
{
"type": "sticker",
"text": "Hello World",
"style": {
"stickerBackgroundColor": "#FFFF00"
},
"x": 100,
"y": 200,
"width": 200
}
// v2: Create a sticky note (dedicated endpoint)// POST /v2/boards/{id}/sticky_notes
{
"data": {
"content": "Hello World", // "text" → "content""shape": "square"// Required in v2
},
"style": {
"fillColor": "light_yellow"// Named colors or hex
},
"position": {
"x": 100, // Nested under "position""y": 200
},
"geometry": {
"width": 200// Nested under "geometry"
}
}
# Run tests
npm test# Verify against a test board
MIRO_TEST_BOARD_ID=your-test-board npm run test:integration
# Check for any remaining v1 patterns
grep -r "widgets\|sticker\|startWidget\|endWidget\|shapeType" src/ --include="*.ts"
Use the ordered procedures and code samples in this guide as a sequence: begin with the prerequisites, apply the configuration or operational step for the target environment, then perform the documented validation or cleanup before proceeding. Keep credentials in the documented secret store; never hard-code them in source.
Output
Following this guide produces the Miro integration outcome for its topic—configuration, validation evidence, operational recovery, or a documented migration result. Record command output and relevant identifiers so a failed step is traceable.
Examples
Start with the smallest applicable command or code example in the relevant section, using a dedicated test board and non-production credentials. Confirm the expected response or validation result before applying the pattern to production.
