miro-upgrade-migration

name	miro-upgrade-migration
description	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.6.0
license	MIT
author	Jeremy Longshore <[e-mail]>
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.

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