Miro API Skill
Master Miro whiteboard automation using the REST API v2 and Python SDK. This skill covers board creation, widget management, frames, shapes, connectors, templates, and real-time collaboration patterns for building automated visual workflows.
When to Use This Skill
USE when:
- Automating sprint retrospective board creation
- Building visual project status dashboards
- Creating automated architecture diagrams
- Setting up templated workshop boards
- Integrating Miro with CI/CD pipelines
- Automating user story mapping workflows
- Creating visual incident response boards
- Building automated onboarding boards
- Generating meeting facilitation templates
- Syncing data from external systems to Miro
DON'T USE when:
- Simple text-based collaboration (use Slack or Teams)
- Document-focused workflows (use Notion or Confluence)
- Code-focused diagramming (use Mermaid or PlantUML)
- Real-time whiteboarding without persistence
- Personal note-taking (use Obsidian)
Prerequisites
Miro App Setup
# 1. Create a Miro App at https://miro.com/app/settings/user-profile/apps
# 2. Choose REST API 2.0
# 3. Configure OAuth 2.0 scopes
# Required OAuth Scopes:
# - boards:read - Read board data
# - boards:write - Create and modify boards
# - team:read - Read team information
# - identity:read - Read user identity
# - microphone:read - Read board audio (optional)
# - screen_recording - Screen recording (optional)
# App Permissions for different use cases:
# Team App: boards:read, boards:write, team:read
# User App: boards:read, boards:write, identity:read
# Admin App: All scopes + organization management
# Get Access Token via OAuth 2.0:
# 1. Redirect user to: https://miro.com/oauth/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=REDIRECT_URI
# 2. Exchange code for token at: https://api.miro.com/v1/oauth/token
Python Environment Setup
# Create virtual environment
python -m venv miro-env
source miro-env/bin/activate # Linux/macOS
# miro-env\Scripts\activate # Windows
# Install Miro API SDK
pip install miro-api
# Install additional dependencies
pip install python-dotenv requests httpx aiohttp
# Create requirements.txt
cat > requirements.txt << 'EOF'
miro-api>=2.0.0
python-dotenv>=1.0.0
requests>=2.31.0
httpx>=0.25.0
aiohttp>=3.9.0
Pillow>=10.0.0
EOF
# Environment variables
cat > .env << 'EOF'
MIRO_ACCESS_TOKEN=your-access-token
MIRO_CLIENT_ID=your-client-id
MIRO_CLIENT_SECRET=your-client-secret
MIRO_TEAM_ID=your-team-id
EOF
API Authentication
# auth.py
# ABOUTME: Miro API authentication utilities
# ABOUTME: Handles OAuth2 token management and refresh
import os
from dotenv import load_dotenv
import requests
from datetime import datetime, timedelta
load_dotenv()
class MiroAuth:
"""Miro OAuth2 authentication handler"""
BASE_URL = "https://api.miro.com"
AUTH_URL = "https://miro.com/oauth/authorize"
TOKEN_URL = "https://api.miro.com/v1/oauth/token"
def __init__(self):
self.client_id = os.environ.get("MIRO_CLIENT_ID")
self.client_secret = os.environ.get("MIRO_CLIENT_SECRET")
self.access_token = os.environ.get("MIRO_ACCESS_TOKEN")
self.refresh_token = os.environ.get("MIRO_REFRESH_TOKEN")
self.token_expires = None
def get_authorization_url(self, redirect_uri: str, state: str = None) -> str:
"""Generate OAuth2 authorization URL"""
params = {
"response_type": "code",
"client_id": self.client_id,
"redirect_uri": redirect_uri,
}
if state:
params["state"] = state
query = "&".join(f"{k}={v}" for k, v in params.items())
return f"{self.AUTH_URL}?{query}"
def exchange_code_for_token(self, code: str, redirect_uri: str) -> dict:
"""Exchange authorization code for access token"""
response = requests.post(
self.TOKEN_URL,
data={
"grant_type": "authorization_code",
"client_id": self.client_id,
"client_secret": self.client_secret,
"code": code,
"redirect_uri": redirect_uri,
},
)
response.raise_for_status()
token_data = response.json()
self.access_token = token_data["access_token"]
self.refresh_token = token_data.get("refresh_token")
self.token_expires = datetime.now() + timedelta(
seconds=token_data.get("expires_in", 3600)
)
return token_data
def refresh_access_token(self) -> dict:
"""Refresh the access token"""
response = requests.post(
self.TOKEN_URL,
data={
"grant_type": "refresh_token",
"client_id": self.client_id,
"client_secret": self.client_secret,
"refresh_token": self.refresh_token,
},
)
response.raise_for_status()
token_data = response.json()
self.access_token = token_data["access_token"]
self.refresh_token = token_data.get("refresh_token", self.refresh_token)
return token_data
def get_headers(self) -> dict:
"""Get authorization headers for API requests"""
return {
"Authorization": f"Bearer {self.access_token}",
"Content-Type": "application/json",
}
Core Capabilities
1. Board Management
# boards.py
# ABOUTME: Miro board management operations
# ABOUTME: Create, read, update, delete boards
import os
from miro_api import Miro
from dotenv import load_dotenv
load_dotenv()
# Initialize Miro client
miro = Miro(access_token=os.environ.get("MIRO_ACCESS_TOKEN"))
def create_board(name: str, description: str = "", team_id: str = None) -> dict:
"""Create a new Miro board"""
team_id = team_id or os.environ.get("MIRO_TEAM_ID")
board = miro.boards.create(
name=name,
description=description,
team_id=team_id,
policy={
"permissionsPolicy": {
"collaborationToolsStartAccess": "all_editors",
"copyAccess": "anyone",
"sharingAccess": "team_members_with_editing_rights",
},
"sharingPolicy": {
"access": "private",
"inviteToAccountAndBoardLinkAccess": "editor",
"organizationAccess": "private",
"teamAccess": "edit",
},
},
)
return {
"id": board.id,
"name": board.name,
"view_link": board.view_link,
"created_at": board.created_at,
}
def get_board(board_id: str) -> dict:
"""Get board details"""
board = miro.boards.get(board_id)
return {
"id": board.id,
"name": board.name,
"description": board.description,
"view_link": board.view_link,
"created_at": board.created_at,
"modified_at": board.modified_at,
}
def list_boards(team_id: str = None, limit: int = 50) -> list:
"""List all boards in a team"""
team_id = team_id or os.environ.get("MIRO_TEAM_ID")
boards = miro.boards.get_all(team_id=team_id, limit=limit)
return [
{
"id": board.id,
"name": board.name,
"view_link": board.view_link,
}
for board in boards
]
def update_board(board_id: str, name: str = None, description: str = None) -> dict:
"""Update board properties"""
update_data = {}
if name:
update_data["name"] = name
if description:
update_data["description"] = description
board = miro.boards.update(board_id, **update_data)
return {"id": board.id, "name": board.name, "description": board.description}
def delete_board(board_id: str) -> bool:
"""Delete a board"""
miro.boards.delete(board_id)
return True
def copy_board(board_id: str, new_name: str, team_id: str = None) -> dict:
"""Copy an existing board"""
team_id = team_id or os.environ.get("MIRO_TEAM_ID")
board = miro.boards.copy(board_id, name=new_name, team_id=team_id)
return {
"id": board.id,
"name": board.name,
"view_link": board.view_link,
}
# Usage example
if __name__ == "__main__":
# Create a board
board = create_board(
name="Sprint Retrospective - Q1 2026",
description="Team retrospective for Q1 sprint",
)
print(f"Created board: {board['view_link']}")
# List boards
boards = list_boards(limit=10)
for b in boards:
print(f"- {b['name']}: {b['view_link']}")
2. Sticky Notes and Cards
# sticky_notes.py
# ABOUTME: Sticky note and card creation
# ABOUTME: Create, position, and style sticky notes
from miro_api import Miro
import os
miro = Miro(access_token=os.environ.get("MIRO_ACCESS_TOKEN"))
def create_sticky_note(
board_id: str,
content: str,
x: float = 0,
y: float = 0,
color: str = "yellow",
width: float = 200,
) -> dict:
"""Create a sticky note on a board"""
# Color mapping
colors = {
"yellow": "yellow",
"green": "green",
"blue": "blue",
"pink": "pink",
"orange": "orange",
"purple": "violet",
"gray": "gray",
"cyan": "cyan",
"red": "red",
"light_yellow": "light_yellow",
"light_green": "light_green",
"light_blue": "light_blue",
"light_pink": "light_pink",
}
sticky = miro.sticky_notes.create(
board_id=board_id,
data={"content": content, "shape": "square"},
style={"fillColor": colors.get(color, "yellow")},
position={"x": x, "y": y, "origin": "center"},
geometry={"width": width},
)
return {
"id": sticky.id,
"content": sticky.data.content,
"position": {"x": sticky.position.x, "y": sticky.position.y},
"color": sticky.style.fill_color,
}
def create_sticky_grid(
board_id: str,
items: list,
start_x: float = 0,
start_y: float = 0,
columns: int = 4,
spacing: float = 250,
color: str = "yellow",
) -> list:
"""Create a grid of sticky notes"""
created = []
for i, item in enumerate(items):
row = i // columns
col = i % columns
x = start_x + (col * spacing)
y = start_y + (row * spacing)
sticky = create_sticky_note(
board_id=board_id, content=item, x=x, y=y, color=color
)
created.append(sticky)
return created
def create_card(
board_id: str,
title: str,
description: str = "",
x: float = 0,
y: float = 0,
assignee_id: str = None,
due_date: str = None,
tags: list = None,
) -> dict:
"""Create a card widget"""
card_data = {"title": title, "description": description}
if assignee_id:
card_data["assigneeId"] = assignee_id
if due_date:
card_data["dueDate"] = due_date
if tags:
card_data["tagIds"] = tags
card = miro.cards.create(
board_id=board_id,
data=card_data,
position={"x": x, "y": y, "origin": "center"},
geometry={"width": 320, "height": 200},
)
return {
"id": card.id,
"title": card.data.title,
"position": {"x": card.position.x, "y": card.position.y},
}
def update_sticky_note(
board_id: str, sticky_id: str, content: str = None, color: str = None
) -> dict:
"""Update a sticky note"""
update_data = {}
if content:
update_data["data"] = {"content": content}
if color:
update_data["style"] = {"fillColor": color}
sticky = miro.sticky_notes.update(board_id, sticky_id, **update_data)
return {"id": sticky.id, "content": sticky.data.content}
def delete_sticky_note(board_id: str, sticky_id: str) -> bool:
"""Delete a sticky note"""
miro.sticky_notes.delete(board_id, sticky_id)
return True
# Retrospective board example
def create_retro_board(board_id: str) -> dict:
"""Create a retrospective board layout"""
# Create category headers
categories = [
{"title": "What went well", "color": "green", "x": 0},
{"title": "What to improve", "color": "pink", "x": 500},
{"title": "Action items", "color": "blue", "x": 1000},
]
created_stickies = {}
for cat in categories:
# Create header sticky
header = create_sticky_note(
board_id=board_id,
content=f"<strong>{cat['title']}</strong>",
x=cat["x"],
y=-200,
color=cat["color"],
width=400,
)
created_stickies[cat["title"]] = [header]
# Create placeholder stickies
for i in range(3):
placeholder = create_sticky_note(
board_id=board_id,
content="Add your thoughts here...",
x=cat["x"],
y=i * 150,
color=cat["color"],
)
created_stickies[cat["title"]].append(placeholder)
return created_stickies
if __name__ == "__main__":
board_id = "YOUR_BOARD_ID"
# Create grid of stickies
items = ["Task 1", "Task 2", "Task 3", "Task 4", "Task 5", "Task 6"]
stickies = create_sticky_grid(
board_id=board_id, items=items, columns=3, color="blue"
)
print(f"Created {len(stickies)} sticky notes")
3. Shapes and Drawing
# shapes.py
# ABOUTME: Shape creation and manipulation
# ABOUTME: Rectangles, circles, lines, and custom shapes
from miro_api import Miro
import os
miro = Miro(access_token=os.environ.get("MIRO_ACCESS_TOKEN"))
def create_shape(
board_id: str,
shape_type: str,
content: str = "",
x: float = 0,
y: float = 0,
width: float = 200,
height: float = 100,
fill_color: str = "#ffffff",
border_color: str = "#000000",
border_width: int = 2,
) -> dict:
"""Create a shape on the board
Shape types: rectangle, circle, triangle, rhombus, parallelogram,
trapezoid, pentagon, hexagon, octagon, wedge_round_rectangle_callout,
round_rectangle, star, flow_chart_process, flow_chart_decision,
flow_chart_terminator, flow_chart_data, flow_chart_document
"""
shape = miro.shapes.create(
board_id=board_id,
data={"content": content, "shape": shape_type},
style={
"fillColor": fill_color,
"borderColor": border_color,
"borderWidth": str(border_width),
"borderStyle": "normal",
"fontFamily": "arial",
"fontSize": "14",
"textAlign": "center",
"textAlignVertical": "middle",
},
position={"x": x, "y": y, "origin": "center"},
geometry={"width": width, "height": height},
)
return {
"id": shape.id,
"type": shape.data.shape,
"position": {"x": shape.position.x, "y": shape.position.y},
}
def create_rectangle(
board_id: str,
content: str = "",
x: float = 0,
y: float = 0,
width: float = 200,
height: float = 100,
fill_color: str = "#ffffff",
) -> dict:
"""Create a rectangle"""
return create_shape(
board_id=board_id,
shape_type="rectangle",
content=content,
x=x,
y=y,
width=width,
height=height,
fill_color=fill_color,
)
def create_circle(
board_id: str,
content: str = "",
x: float = 0,
y: float = 0,
diameter: float = 100,
fill_color: str = "#ffffff",
) -> dict:
"""Create a circle"""
return create_shape(
board_id=board_id,
shape_type="circle",
content=content,
x=x,
y=y,
width=diameter,
height=diameter,
fill_color=fill_color,
)
def create_flowchart_shape(
board_id: str,
shape_type: str,
content: str = "",
x: float = 0,
y: float = 0,
width: float = 150,
height: float = 80,
) -> dict:
"""Create a flowchart shape
Types: flow_chart_process, flow_chart_decision, flow_chart_terminator,
flow_chart_data, flow_chart_document, flow_chart_predefined_process,
flow_chart_manual_input, flow_chart_display, flow_chart_preparation
"""
colors = {
"flow_chart_process": "#e3f2fd",
"flow_chart_decision": "#fff3e0",
"flow_chart_terminator": "#f3e5f5",
"flow_chart_data": "#e8f5e9",
"flow_chart_document": "#fce4ec",
}
return create_shape(
board_id=board_id,
shape_type=shape_type,
content=content,
x=x,
y=y,
width=width,
height=height,
fill_color=colors.get(shape_type, "#ffffff"),
)
def create_flowchart(board_id: str, steps: list, start_x: float = 0, start_y: float = 0) -> list:
"""Create a flowchart from a list of steps
Each step: {"type": "process|decision|terminator", "content": "text"}
"""
created = []
current_y = start_y
for step in steps:
shape_type = f"flow_chart_{step.get('type', 'process')}"
height = 100 if step.get("type") == "decision" else 80
shape = create_flowchart_shape(
board_id=board_id,
shape_type=shape_type,
content=step["content"],
x=start_x,
y=current_y,
height=height,
)
created.append(shape)
current_y += height + 80 # Add spacing for connectors
return created
def update_shape(
board_id: str,
shape_id: str,
content: str = None,
fill_color: str = None,
x: float = None,
y: float = None,
) -> dict:
"""Update a shape"""
update_data = {}
if content is not None:
update_data["data"] = {"content": content}
if fill_color:
update_data["style"] = {"fillColor": fill_color}
if x is not None or y is not None:
position = {}
if x is not None:
position["x"] = x
if y is not None:
position["y"] = y
update_data["position"] = position
shape = miro.shapes.update(board_id, shape_id, **update_data)
return {"id": shape.id}
if __name__ == "__main__":
board_id = "YOUR_BOARD_ID"
# Create a simple flowchart
steps = [
{"type": "terminator", "content": "Start"},
{"type": "process", "content": "Initialize system"},
{"type": "decision", "content": "Valid input?"},
{"type": "process", "content": "Process data"},
{"type": "terminator", "content": "End"},
]
flowchart = create_flowchart(board_id, steps)
print(f"Created flowchart with {len(flowchart)} shapes")
4. Connectors and Lines
# connectors.py
# ABOUTME: Connector and line creation
# ABOUTME: Connect shapes, create arrows, and diagram flows
from miro_api import Miro
import os
miro = Miro(access_token=os.environ.get("MIRO_ACCESS_TOKEN"))
def create_connector(
board_id: str,
start_item_id: str,
end_item_id: str,
start_position: str = "right",
end_position: str = "left",
stroke_color: str = "#000000",
stroke_width: int = 2,
stroke_style: str = "normal",
start_cap: str = "none",
end_cap: str = "stealth",
caption: str = None,
) -> dict:
"""Create a connector between two items
Positions: top, right, bottom, left, auto
Caps: none, stealth, rounded_stealth, diamond, diamond_filled, oval, oval_filled,
arrow, triangle, triangle_filled, erd_one, erd_many, erd_one_or_many, erd_only_one,
erd_zero_or_one, erd_zero_or_many
Stroke styles: normal, dashed, dotted
"""
connector_data = {
"startItem": {"id": start_item_id, "position": {"x": start_position}},
"endItem": {"id": end_item_id, "position": {"x": end_position}},
}
connector_style = {
"strokeColor": stroke_color,
"strokeWidth": str(stroke_width),
"strokeStyle": stroke_style,
"startStrokeCap": start_cap,
"endStrokeCap": end_cap,
}
if caption:
connector_data["captions"] = [{"content": caption, "position": "50%"}]
connector = miro.connectors.create(
board_id=board_id,
data=connector_data,
style=connector_style,
)
return {
"id": connector.id,
"start_item": connector.start_item.id,
"end_item": connector.end_item.id,
}
def create_line(
board_id: str,
start_x: float,
start_y: float,
end_x: float,
end_y: float,
stroke_color: str = "#000000",
stroke_width: int = 2,
end_cap: str = "none",
) -> dict:
"""Create a standalone line"""
# For lines without connected items, we use absolute coordinates
connector = miro.connectors.create(
board_id=board_id,
data={
"startItem": {"position": {"x": start_x, "y": start_y}},
"endItem": {"position": {"x": end_x, "y": end_y}},
},
style={
"strokeColor": stroke_color,
"strokeWidth": str(stroke_width),
"startStrokeCap": "none",
"endStrokeCap": end_cap,
},
)
return {"id": connector.id}
def connect_flowchart_shapes(board_id: str, shape_ids: list, labels: list = None) -> list:
"""Connect a list of shapes in sequence"""
created = []
for i in range(len(shape_ids) - 1):
label = labels[i] if labels and i < len(labels) else None
connector = create_connector(
board_id=board_id,
start_item_id=shape_ids[i],
end_item_id=shape_ids[i + 1],
start_position="bottom",
end_position="top",
end_cap="stealth",
caption=label,
)
created.append(connector)
return created
def create_decision_branches(
board_id: str,
decision_shape_id: str,
yes_shape_id: str,
no_shape_id: str,
) -> list:
"""Create Yes/No branches from a decision diamond"""
yes_connector = create_connector(
board_id=board_id,
start_item_id=decision_shape_id,
end_item_id=yes_shape_id,
start_position="bottom",
end_position="top",
end_cap="stealth",
caption="Yes",
stroke_color="#4caf50",
)
no_connector = create_connector(
board_id=board_id,
start_item_id=decision_shape_id,
end_item_id=no_shape_id,
start_position="right",
end_position="left",
end_cap="stealth",
caption="No",
stroke_color="#f44336",
)
return [yes_connector, no_connector]
def create_erd_relationship(
board_id: str,
entity1_id: str,
entity2_id: str,
cardinality_start: str = "erd_one",
cardinality_end: str = "erd_many",
label: str = None,
) -> dict:
"""Create an ERD relationship line
Cardinalities: erd_one, erd_many, erd_one_or_many, erd_only_one,
erd_zero_or_one, erd_zero_or_many
"""
return create_connector(
board_id=board_id,
start_item_id=entity1_id,
end_item_id=entity2_id,
start_cap=cardinality_start,
end_cap=cardinality_end,
caption=label,
)
def update_connector(
board_id: str,
connector_id: str,
stroke_color: str = None,
caption: str = None,
) -> dict:
"""Update a connector"""
update_data = {}
if stroke_color:
update_data["style"] = {"strokeColor": stroke_color}
if caption:
update_data["captions"] = [{"content": caption, "position": "50%"}]
connector = miro.connectors.update(board_id, connector_id, **update_data)
return {"id": connector.id}
def delete_connector(board_id: str, connector_id: str) -> bool:
"""Delete a connector"""
miro.connectors.delete(board_id, connector_id)
return True
if __name__ == "__main__":
board_id = "YOUR_BOARD_ID"
# Example: Connect shapes
shape_ids = ["shape1_id", "shape2_id", "shape3_id"]
connectors = connect_flowchart_shapes(board_id, shape_ids)
print(f"Created {len(connectors)} connectors")
5. Frames and Organization
# frames.py
# ABOUTME: Frame creation for board organization
# ABOUTME: Group items, create sections, and manage layout
from miro_api import Miro
import os
from typing import List, Optional
miro = Miro(access_token=os.environ.get("MIRO_ACCESS_TOKEN"))
def create_frame(
board_id: str,
title: str,
x: float = 0,
y: float = 0,
width: float = 800,
height: float = 600,
fill_color: str = "#f5f5f5",
) -> dict:
"""Create a frame to organize board content"""
frame = miro.frames.create(
board_id=board_id,
data={"title": title, "format": "custom"},
style={"fillColor": fill_color},
position={"x": x, "y": y, "origin": "center"},
geometry={"width": width, "height": height},
)
return {
"id": frame.id,
"title": frame.data.title,
"position": {"x": frame.position.x, "y": frame.position.y},
"geometry": {"width": frame.geometry.width, "height": frame.geometry.height},
}
def create_frame_grid(
board_id: str,
titles: list,
columns: int = 3,
frame_width: float = 600,
frame_height: float = 400,
spacing: float = 50,
start_x: float = 0,
start_y: float = 0,
) -> list:
"""Create a grid of frames"""
created = []
for i, title in enumerate(titles):
row = i // columns
col = i % columns
x = start_x + col * (frame_width + spacing)
y = start_y + row * (frame_height + spacing)
frame = create_frame(
board_id=board_id,
title=title,
x=x,
y=y,
width=frame_width,
height=frame_height,
)
created.append(frame)
return created
def create_kanban_board(
board_id: str,
columns: list = None,
frame_width: float = 400,
frame_height: float = 800,
) -> list:
"""Create a Kanban-style board with columns"""
if columns is None:
columns = ["To Do", "In Progress", "Review", "Done"]
colors = {
"To Do": "#f5f5f5",
"In Progress": "#fff3e0",
"Review": "#e8f5e9",
"Done": "#e3f2fd",
}
frames = []
start_x = 0
for i, column in enumerate(columns):
frame = create_frame(
board_id=board_id,
title=column,
x=start_x + i * (frame_width + 50),
y=0,
width=frame_width,
height=frame_height,
fill_color=colors.get(column, "#f5f5f5"),
)
frames.append(frame)
return frames
def create_workshop_layout(
board_id: str, sections: list, section_width: float = 1000, section_height: float = 600
) -> dict:
"""Create a workshop board layout
sections: list of {"title": "name", "description": "desc", "color": "#hex"}
"""
created = {"frames": [], "headers": []}
for i, section in enumerate(sections):
# Create frame for section
frame = create_frame(
board_id=board_id,
title=section["title"],
x=0,
y=i * (section_height + 100),
width=section_width,
height=section_height,
fill_color=section.get("color", "#f5f5f5"),
)
created["frames"].append(frame)
return created
def update_frame(
board_id: str,
frame_id: str,
title: str = None,
width: float = None,
height: float = None,
) -> dict:
"""Update a frame"""
update_data = {}
if title:
update_data["data"] = {"title": title}
if width or height:
geometry = {}
if width:
geometry["width"] = width
if height:
geometry["height"] = height
update_data["geometry"] = geometry
frame = miro.frames.update(board_id, frame_id, **update_data)
return {"id": frame.id, "title": frame.data.title}
def get_items_in_frame(board_id: str, frame_id: str) -> list:
"""Get all items contained within a frame"""
frame = miro.frames.get(board_id, frame_id)
# Get child items
children = miro.frames.get_children(board_id, frame_id)
return [
{"id": child.id, "type": child.type}
for child in children
]
def add_items_to_frame(board_id: str, frame_id: str, item_ids: list) -> bool:
"""Add items to a frame by updating their parent"""
for item_id in item_ids:
# Items inside a frame are managed by their position
# They need to be within the frame's boundaries
pass
return True
def delete_frame(board_id: str, frame_id: str) -> bool:
"""Delete a frame"""
miro.frames.delete(board_id, frame_id)
return True
if __name__ == "__main__":
board_id = "YOUR_BOARD_ID"
# Create Kanban board
kanban = create_kanban_board(board_id)
print(f"Created Kanban with {len(kanban)} columns")
# Create workshop layout
sections = [
{"title": "Introduction", "color": "#e3f2fd"},
{"title": "Brainstorming", "color": "#fff3e0"},
{"title": "Voting", "color": "#e8f5e9"},
{"title": "Action Items", "color": "#f3e5f5"},
]
workshop = create_workshop_layout(board_id, sections)
print(f"Created workshop with {len(workshop['frames'])} sections")
6. Text and Images
# text_images.py
# ABOUTME: Text elements and image handling
# ABOUTME: Create text boxes, embed images, and manage media
from miro_api import Miro
import os
import requests
from io import BytesIO
miro = Miro(access_token=os.environ.get("MIRO_ACCESS_TOKEN"))
def create_text(
board_id: str,
content: str,
x: float = 0,
y: float = 0,
width: float = 200,
font_size: int = 14,
font_family: str = "arial",
text_align: str = "left",
color: str = "#000000",
) -> dict:
"""Create a text element"""
text = miro.texts.create(
board_id=board_id,
data={"content": content},
style={
"color": color,
"fillOpacity": "1.0",
"fontFamily": font_family,
"fontSize": str(font_size),
"textAlign": text_align,
},
position={"x": x, "y": y, "origin": "center"},
geometry={"width": width},
)
return {
"id": text.id,
"content": text.data.content,
"position": {"x": text.position.x, "y": text.position.y},
}
def create_heading(
board_id: str,
content: str,
x: float = 0,
y: float = 0,
level: int = 1,
) -> dict:
"""Create a heading text element"""
font_sizes = {1: 36, 2: 28, 3: 22, 4: 18}
font_size = font_sizes.get(level, 14)
return create_text(
board_id=board_id,
content=f"<strong>{content}</strong>",
x=x,
y=y,
width=500,
font_size=font_size,
)
def create_bullet_list(
board_id: str,
items: list,
x: float = 0,
y: float = 0,
) -> dict:
"""Create a bulleted list"""
content = "<ul>" + "".join(f"<li>{item}</li>" for item in items) + "</ul>"
return create_text(
board_id=board_id,
content=content,
x=x,
y=y,
width=400,
)
def upload_image_from_url(
board_id: str,
image_url: str,
x: float = 0,
y: float = 0,
width: float = None,
title: str = None,
) -> dict:
"""Create an image from a URL"""
image_data = {"url": image_url}
if title:
image_data["title"] = title
geometry = {}
if width:
geometry["width"] = width
image = miro.images.create(
board_id=board_id,
data=image_data,
position={"x": x, "y": y, "origin": "center"},
geometry=geometry if geometry else None,
)
return {
"id": image.id,
"position": {"x": image.position.x, "y": image.position.y},
}
def upload_image_from_file(
board_id: str,
file_path: str,
x: float = 0,
y: float = 0,
width: float = None,
) -> dict:
"""Upload an image from a local file"""
with open(file_path, "rb") as f:
image_data = f.read()
# Use the image upload endpoint
headers = {
"Authorization": f"Bearer {os.environ.get('MIRO_ACCESS_TOKEN')}",
}
files = {"resource": (os.path.basename(file_path), image_data)}
data = {"position": f'{{"x": {x}, "y": {y}, "origin": "center"}}'}
if width:
data["geometry"] = f'{{"width": {width}}}'
response = requests.post(
f"https://api.miro.com/v2/boards/{board_id}/images",
headers=headers,
files=files,
data=data,
)
response.raise_for_status()
return response.json()
def create_embed(
board_id: str,
url: str,
x: float = 0,
y: float = 0,
width: float = 400,
height: float = 300,
mode: str = "modal",
) -> dict:
"""Create an embedded content (web page, video, etc.)
Modes: inline, modal
"""
embed = miro.embeds.create(
board_id=board_id,
data={"url": url, "mode": mode},
position={"x": x, "y": y, "origin": "center"},
geometry={"width": width, "height": height},
)
return {
"id": embed.id,
"url": embed.data.url,
"position": {"x": embed.position.x, "y": embed.position.y},
}
def create_document_section(
board_id: str,
title: str,
description: str,
items: list,
x: float = 0,
y: float = 0,
) -> dict:
"""Create a document-like section with title, description, and bullet points"""
created = {}
# Create title
heading = create_heading(board_id, title, x=x, y=y, level=2)
created["title"] = heading
# Create description
desc = create_text(board_id, description, x=x, y=y + 60, width=500)
created["description"] = desc
# Create bullet list
bullets = create_bullet_list(board_id, items, x=x, y=y + 150)
created["items"] = bullets
return created
if __name__ == "__main__":
board_id = "YOUR_BOARD_ID"
# Create a document section
section = create_document_section(
board_id=board_id,
title="Project Overview",
description="This project aims to improve team collaboration through automated Miro workflows.",
items=[
"Automated board creation",
"Template-based layouts",
"Integration with CI/CD",
],
)
print(f"Created section with {len(section)} elements")
Integration Examples
GitHub Actions Integration
# .github/workflows/miro-sync.yml
name: Sync to Miro
on:
issues:
types: [opened, labeled]
pull_request:
types: [opened, closed, merged]
jobs:
sync-miro:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: '3.12'
- name: Install dependencies
run: |
pip install miro-api requests
- name: Create issue card in Miro
if: github.event_name == 'issues'
env:
MIRO_ACCESS_TOKEN: ${{ secrets.MIRO_ACCESS_TOKEN }}
MIRO_BOARD_ID: ${{ secrets.MIRO_BOARD_ID }}
run: |
python << 'EOF'
import os
from miro_api import Miro
miro = Miro(access_token=os.environ["MIRO_ACCESS_TOKEN"])
board_id = os.environ["MIRO_BOARD_ID"]
# Create sticky note for new issue
issue_title = "${{ github.event.issue.title }}"
issue_number = "${{ github.event.issue.number }}"
issue_url = "${{ github.event.issue.html_url }}"
miro.sticky_notes.create(
board_id=board_id,
data={
"content": f"#{issue_number}: {issue_title}\n\n{issue_url}"
},
style={"fillColor": "yellow"},
position={"x": 0, "y": 0, "origin": "center"},
)
print(f"Created sticky note for issue #{issue_number}")
EOF
- name: Update PR status in Miro
if: github.event_name == 'pull_request'
env:
MIRO_ACCESS_TOKEN: ${{ secrets.MIRO_ACCESS_TOKEN }}
MIRO_BOARD_ID: ${{ secrets.MIRO_BOARD_ID }}
run: |
python << 'EOF'
import os
from miro_api import Miro
miro = Miro(access_token=os.environ["MIRO_ACCESS_TOKEN"])
board_id = os.environ["MIRO_BOARD_ID"]
pr_title = "${{ github.event.pull_request.title }}"
pr_state = "${{ github.event.action }}"
colors = {
"opened": "light_blue",
"closed": "red",
"merged": "green",
}
miro.sticky_notes.create(
board_id=board_id,
data={"content": f"PR: {pr_title}\nStatus: {pr_state}"},
style={"fillColor": colors.get(pr_state, "gray")},
position={"x": 500, "y": 0, "origin": "center"},
)
EOF
Sprint Retrospective Automation
# retro_automation.py
# ABOUTME: Automated sprint retrospective board creation
# ABOUTME: Creates templated retro board with categories
from miro_api import Miro
import os
from datetime import datetime
miro = Miro(access_token=os.environ.get("MIRO_ACCESS_TOKEN"))
def create_retrospective_board(
sprint_number: int,
team_name: str,
team_id: str = None,
) -> dict:
"""Create a complete retrospective board for a sprint"""
team_id = team_id or os.environ.get("MIRO_TEAM_ID")
# Create board
board_name = f"Sprint {sprint_number} Retrospective - {team_name}"
board = miro.boards.create(
name=board_name,
description=f"Retrospective for Sprint {sprint_number}",
team_id=team_id,
)
board_id = board.id
# Create frames for categories
categories = [
{"title": "What Went Well", "color": "#c8e6c9", "x": 0},
{"title": "What Could Be Improved", "color": "#ffcdd2", "x": 700},
{"title": "Action Items", "color": "#bbdefb", "x": 1400},
]
frames = []
for cat in categories:
frame = miro.frames.create(
board_id=board_id,
data={"title": cat["title"], "format": "custom"},
style={"fillColor": cat["color"]},
position={"x": cat["x"], "y": 0, "origin": "center"},
geometry={"width": 600, "height": 800},
)
frames.append({"id": frame.id, "title": cat["title"]})
# Add placeholder stickies
for i in range(3):
miro.sticky_notes.create(
board_id=board_id,
data={"content": "Add your thoughts here..."},
style={"fillColor": cat["color"]},
position={
"x": cat["x"],
"y": -200 + (i * 150),
"origin": "center",
},
)
# Create header
miro.texts.create(
board_id=board_id,
data={
"content": f"<strong>Sprint {sprint_number} Retrospective</strong><br>{datetime.now().strftime('%B %d, %Y')}"
},
style={"fontSize": "36", "textAlign": "center"},
position={"x": 700, "y": -500, "origin": "center"},
geometry={"width": 800},
)
# Add voting instructions
miro.texts.create(
board_id=board_id,
data={
"content": "Instructions:<br>1. Add sticky notes to each category<br>2. Vote on items using dots<br>3. Discuss top voted items<br>4. Create action items"
},
style={"fontSize": "14"},
position={"x": -400, "y": 0, "origin": "center"},
geometry={"width": 300},
)
return {
"board_id": board_id,
"view_link": board.view_link,
"frames": frames,
}
def create_sprint_planning_board(
sprint_number: int,
team_name: str,
stories: list,
) -> dict:
"""Create a sprint planning board with user stories"""
board = miro.boards.create(
name=f"Sprint {sprint_number} Planning - {team_name}",
description=f"Planning board for Sprint {sprint_number}",
team_id=os.environ.get("MIRO_TEAM_ID"),
)
board_id = board.id
# Create Kanban columns
columns = ["Backlog", "To Do", "In Progress", "Review", "Done"]
col_width = 350
col_height = 1000
for i, col in enumerate(columns):
miro.frames.create(
board_id=board_id,
data={"title": col, "format": "custom"},
style={"fillColor": "#f5f5f5"},
position={"x": i * (col_width + 30), "y": 0, "origin": "center"},
geometry={"width": col_width, "height": col_height},
)
# Add stories to backlog
for j, story in enumerate(stories):
miro.cards.create(
board_id=board_id,
data={
"title": story.get("title", "User Story"),
"description": story.get("description", ""),
},
position={"x": 0, "y": -300 + (j * 150), "origin": "center"},
geometry={"width": 300, "height": 120},
)
return {"board_id": board_id, "view_link": board.view_link}
if __name__ == "__main__":
# Create retrospective board
retro = create_retrospective_board(sprint_number=15, team_name="Platform Team")
print(f"Retro board: {retro['view_link']}")
# Create planning board
stories = [
{"title": "As a user, I want to login with SSO", "description": "Implement SSO authentication"},
{"title": "As a user, I want dark mode", "description": "Add dark mode support"},
]
planning = create_sprint_planning_board(sprint_number=16, team_name="Platform Team", stories=stories)
print(f"Planning board: {planning['view_link']}")
Best Practices
1. Rate Limiting
# Rate limit handling
import time
from functools import wraps
def rate_limit_handler(max_retries=3, base_delay=1):
"""Decorator for handling Miro rate limits"""
def decorator(func):
@wraps(func)
def wrapper(*args, **kwargs):
for attempt in range(max_retries):
try:
return func(*args, **kwargs)
except Exception as e:
if "429" in str(e) or "rate" in str(e).lower():
delay = base_delay * (2 ** attempt)
print(f"Rate limited, waiting {delay}s...")
time.sleep(delay)
else:
raise
raise Exception("Max retries exceeded")
return wrapper
return decorator
@rate_limit_handler(max_retries=3)
def safe_create_sticky(board_id, content, x, y):
return miro.sticky_notes.create(
board_id=board_id,
data={"content": content},
position={"x": x, "y": y, "origin": "center"},
)
2. Batch Operations
# Batch creation for better performance
def batch_create_stickies(board_id: str, items: list, batch_size: int = 10):
"""Create stickies in batches to avoid rate limits"""
created = []
for i in range(0, len(items), batch_size):
batch = items[i:i + batch_size]
for item in batch:
sticky = miro.sticky_notes.create(
board_id=board_id,
data={"content": item["content"]},
style={"fillColor": item.get("color", "yellow")},
position={"x": item["x"], "y": item["y"], "origin": "center"},
)
created.append(sticky)
# Small delay between batches
if i + batch_size < len(items):
time.sleep(0.5)
return created
3. Error Handling
# Comprehensive error handling
from miro_api.exceptions import MiroApiException
def safe_api_call(func, *args, **kwargs):
"""Wrapper for safe API calls"""
try:
return func(*args, **kwargs)
except MiroApiException as e:
if e.status_code == 404:
print(f"Resource not found: {e}")
return None
elif e.status_code == 401:
print("Authentication failed - check token")
raise
elif e.status_code == 403:
print("Permission denied - check scopes")
raise
elif e.status_code == 429:
print("Rate limited - implement backoff")
time.sleep(60)
return func(*args, **kwargs)
else:
raise
4. Position Calculations
# Helper functions for positioning
def calculate_grid_position(index: int, columns: int, spacing: float = 250):
"""Calculate x, y for grid layout"""
row = index // columns
col = index % columns
return {
"x": col * spacing,
"y": row * spacing,
}
def calculate_circle_position(index: int, total: int, radius: float = 300, center_x: float = 0, center_y: float = 0):
"""Calculate x, y for circular layout"""
import math
angle = (2 * math.pi * index) / total
return {
"x": center_x + radius * math.cos(angle),
"y": center_y + radius * math.sin(angle),
}
Troubleshooting
Common Issues
Issue: 401 Unauthorized
# Verify token is valid
import requests
def verify_token(token: str) -> bool:
response = requests.get(
"https://api.miro.com/v1/users/me",
headers={"Authorization": f"Bearer {token}"}
)
return response.status_code == 200
# Check token scopes
def get_token_scopes(token: str) -> list:
response = requests.get(
"https://api.miro.com/v1/oauth-token",
headers={"Authorization": f"Bearer {token}"}
)
return response.json().get("scopes", [])
Issue: Items not appearing on board
# Check board permissions
def check_board_access(board_id: str) -> dict:
board = miro.boards.get(board_id)
return {
"id": board.id,
"permissions": board.policy.permissions_policy,
"sharing": board.policy.sharing_policy,
}
Issue: Rate limiting
# Implement exponential backoff
import time
def with_backoff(func, max_retries=5):
for i in range(max_retries):
try:
return func()
except Exception as e:
if "429" in str(e):
wait = (2 ** i) + (random.random() * 0.1)
time.sleep(wait)
else:
raise
raise Exception("Max retries exceeded")
Debug Commands
# Test API authentication
curl -X GET "https://api.miro.com/v1/users/me" \
-H "Authorization: Bearer $MIRO_ACCESS_TOKEN"
# List boards
curl -X GET "https://api.miro.com/v2/boards?team_id=$MIRO_TEAM_ID" \
-H "Authorization: Bearer $MIRO_ACCESS_TOKEN"
# Get board details
curl -X GET "https://api.miro.com/v2/boards/$BOARD_ID" \
-H "Authorization: Bearer $MIRO_ACCESS_TOKEN"
# Create sticky note
curl -X POST "https://api.miro.com/v2/boards/$BOARD_ID/sticky_notes" \
-H "Authorization: Bearer $MIRO_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"data": {"content": "Test note"}, "position": {"x": 0, "y": 0}}'
Version History
| Version | Date | Changes | |---------|------|---------| | 1.0.0 | 2026-01-17 | Initial release with comprehensive Miro API v2 patterns |
Resources
- Miro REST API Documentation
- Miro Python SDK
- Miro Developer Portal
- OAuth 2.0 Guide
- Webhooks Documentation
- Rate Limits
This skill provides production-ready patterns for Miro whiteboard automation, enabling powerful visual collaboration workflows and team productivity tools.