Skills miro-api

Name: miro-api
Author: openclaw

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.

install

source · Clone the upstream repo

git clone https://github.com/openclaw/skills

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/openclaw/skills "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/bigbubbaagent-bot/miro-api" ~/.claude/skills/openclaw-skills-miro-api && rm -rf "$T"

OpenClaw · Install into ~/.openclaw/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/openclaw/skills "$T" && mkdir -p ~/.openclaw/skills && cp -r "$T/skills/bigbubbaagent-bot/miro-api" ~/.openclaw/skills/openclaw-skills-miro-api && rm -rf "$T"

manifest: skills/bigbubbaagent-bot/miro-api/SKILL.md

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)