name: miro-api description: Complete Miro REST API reference for building integrations, automating workflows, and programmatically managing boards, cards, shapes, users, and team resources. Language-agnostic documentation with examples, authentication patterns, rate limiting, webhooks, and error handling.

Miro REST API

The Miro REST API enables programmatic access to create, read, update, and delete boards, items, users, and team resources. This skill provides comprehensive documentation for integrating Miro with external systems, automating workflows, and building custom applications.

Quick Start

Base URL: https://api.miro.com/v2

Authentication: OAuth 2.0 or Personal Access Tokens

Example Request:

curl -X GET https://api.miro.com/v2/boards \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"

Response:

{
  "data": [
    {
      "id": "board-id-123",
      "name": "My Board",
      "owner": {"id": "user-id", "email": "user@example.com"},
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-20T14:45:00Z"
    }
  ]
}

Core Capabilities

1. Board Management

List boards - Get all boards in your workspace
Create boards - Programmatically create new boards
Update board settings - Modify name, sharing, permissions
Delete boards - Soft-delete boards (recoverable)
Board sharing & access - Manage team member permissions

2. Items (Cards, Shapes, Text, Stickies)

Create items - Add cards, shapes, text, stickies, images to boards
Read items - Fetch item details, properties, attachments
Update items - Modify content, position, style, metadata
Delete items - Remove items from boards
Batch operations - Efficient bulk create/update

3. Shapes & Connectors

Shape library - Rectangle, circle, diamond, line, arrow, etc.
Shape styling - Fill color, stroke, line width, opacity
Connectors - Create connections between shapes
Geometry - Position, rotation, dimensions

4. Text & Rich Content

Text shapes - Add formatted text to boards
Rich text - Bold, italic, underline, font sizes
Text alignment - Left, center, right, justified
Font families - System fonts and custom typefaces

5. Images & Files

Upload images - Add images to boards
Image management - Reference, replace, delete
Attachments - Embed files and URLs

6. Frames & Grouping

Frames - Organizational containers for items
Groups - Logical grouping of related items
Hierarchy - Nested structures and relationships

7. Comments & Collaboration

Add comments - Comment on boards and items
Thread replies - Nested comment threads
Mentions - Tag team members (@username)
Comment reactions - Emoji reactions to comments

8. Users & Team Management

List team members - Get users in workspace
User profiles - Email, name, role, permissions
Invitations - Invite users to workspace
Team settings - Manage workspace configuration

9. Webhooks & Events

Board events - item.created, item.updated, item.deleted
Comment events - comment.created, comment.deleted
Webhook management - Register, test, delete webhooks
Event payload - Complete event data with timestamps

10. Advanced Features

Exports - Export boards as PNG/PDF/CSV
Import - Batch import items from external sources
Integrations - Connect with Slack, Jira, Figma, etc.
Custom metadata - Attach custom properties to items

Authentication

OAuth 2.0 (Recommended for Production)

1. Register app at https://miro.com/app/settings/user-profile/apps
2. Redirect user to authorization endpoint
3. Exchange auth code for access token
4. Use token in Authorization header: Bearer <token>
5. Refresh token when expired (3600 seconds)

Personal Access Tokens (Development)

curl -X GET https://api.miro.com/v2/boards \
  -H "Authorization: Bearer YOUR_PERSONAL_TOKEN"

Creating a PAT:

Go to https://miro.com/app/settings/user-profile/apps
Click "Create new app" or "Personal access token"
Select required scopes (boards:read, items:write, etc.)
Copy token (shown only once)
Store securely (never commit to version control)

API Endpoints Overview

Boards

GET /boards - List all boards
POST /boards - Create new board
GET /boards/{board_id} - Get board details
PATCH /boards/{board_id} - Update board
DELETE /boards/{board_id} - Delete board

Items

GET /boards/{board_id}/items - List items on board
POST /boards/{board_id}/items - Create item
GET /boards/{board_id}/items/{item_id} - Get item details
PATCH /boards/{board_id}/items/{item_id} - Update item
DELETE /boards/{board_id}/items/{item_id} - Delete item

Comments

GET /boards/{board_id}/comments - List comments
POST /boards/{board_id}/comments - Add comment
GET /boards/{board_id}/comments/{comment_id} - Get comment
PATCH /boards/{board_id}/comments/{comment_id} - Update comment
DELETE /boards/{board_id}/comments/{comment_id} - Delete comment

Team Members

GET /teams/{team_id}/members - List team members
POST /teams/{team_id}/members - Invite member
DELETE /teams/{team_id}/members/{user_id} - Remove member

Webhooks

GET /teams/{team_id}/webhooks - List webhooks
POST /teams/{team_id}/webhooks - Create webhook
PATCH /teams/{team_id}/webhooks/{webhook_id} - Update webhook
DELETE /teams/{team_id}/webhooks/{webhook_id} - Delete webhook

Rate Limiting

Default Limits:

300 requests per minute (5 req/sec)
50,000 requests per month

Headers:

X-RateLimit-Limit - Limit for this time window
X-RateLimit-Remaining - Requests left
X-RateLimit-Reset - Unix timestamp when limit resets

Handling Rate Limits:

# Check remaining requests
X-RateLimit-Remaining: 45

# Wait until reset time
curl -i https://api.miro.com/v2/boards | grep X-RateLimit

Best Practices:

Check X-RateLimit-Remaining before requests
Implement exponential backoff on 429 responses
Batch operations when possible
Cache board/item data locally
Use webhooks for real-time updates instead of polling

Error Handling

Common HTTP Status Codes

200 OK - Successful request
201 Created - Resource created
204 No Content - Successful deletion
400 Bad Request - Invalid parameters
401 Unauthorized - Missing/invalid token
403 Forbidden - Insufficient permissions
404 Not Found - Resource doesn't exist
429 Too Many Requests - Rate limited
500 Server Error - Miro API error

Error Response Format

{
  "code": 400,
  "message": "Invalid request parameter",
  "details": {
    "param": "board_id",
    "reason": "Expected UUID format"
  }
}

Supported Item Types

Type	Description	Can Contain
`CARD`	Note-like item with title + content	Text, emoji
`SHAPE`	Geometric shapes (rect, circle, etc.)	Fill, stroke styling
`TEXT`	Rich text formatting	Bold, italic, colors
`STICKY`	Virtual sticky note	Text, color options
`IMAGE`	Image/photo uploads	File data
`FRAME`	Container/group for items	Nested items
`CONNECTOR`	Line connecting shapes	Source/target references
`EMBED`	Embedded content (Figma, YouTube, etc.)	External URLs

Pagination

Query Parameters:

limit - Items per page (1-100, default 100)
cursor - Pagination cursor (from previous response)

Response:

{
  "data": [...items...],
  "cursor": "next-page-cursor-token",
  "limit": 100
}

Field Selection (Sparse Fieldsets)

Optimize responses by requesting specific fields:

GET /boards/{board_id}/items?fields=id,type,title,position

Real-Time Updates

Option 1: Webhooks (Recommended)

Receive instant notifications for board changes
No polling required
Supports filtering by event type

Option 2: Polling

Periodic GET requests to check for changes
Less efficient but works everywhere
Implement exponential backoff

SDK & Library Support

Official SDKs:

JavaScript/Node.js
Python
Go

Community Libraries:

Java, C#, Ruby, PHP
(Check GitHub for latest)

Integration Patterns

Sync External Data to Miro

Fetch data from external source (Jira, Airtable, etc.)
Transform to Miro item format
Batch create items on board
Set custom metadata for tracking

Slack Integration

User mentions @miro-bot in Slack
→ Bot creates board or card
→ Sends link back to Slack channel

Jira Sync

Jira ticket created → POST to Miro board
Miro item updated → PATCH Jira ticket
Real-time sync via webhooks

Security Best Practices

Token Management
- Never commit tokens to git
- Use environment variables
- Rotate tokens regularly
- Use minimal required scopes
Data Privacy
- Don't log sensitive board content
- Encrypt data in transit (HTTPS)
- Validate webhook signatures
Access Control
- Verify user permissions before operations
- Use board/item permissions
- Audit API usage

Reference Files

See detailed documentation:

references/endpoints.md - Complete endpoint reference
references/authentication.md - Auth patterns and flows
references/webhooks.md - Webhook setup and payloads
references/errors.md - Error codes and handling
references/examples.md - Code examples (curl, HTTP)
references/rate-limiting.md - Detailed rate limit info
references/best-practices.md - Performance and design patterns

Version History

v2 (Current) - Latest stable API
v1 (Deprecated) - Legacy, use v2

Miro REST API Reference

Description