miro-api（Miro API 文档）

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:

1. Go to https://miro.com/app/settings/user-profile/apps
2. Click "Create new app" or "Personal access token"
3. Select required scopes (boards:read, items:write, etc.)
4. Copy token (shown only once)
5. 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:

1. Check X-RateLimit-Remaining before requests
2. Implement exponential backoff on 429 responses
3. Batch operations when possible
4. Cache board/item data locally
5. 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

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

1. Fetch data from external source (Jira, Airtable, etc.)
2. Transform to Miro item format
3. Batch create items on board
4. 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

1. Token Management

- Never commit tokens to git - Use environment variables - Rotate tokens regularly - Use minimal required scopes

1. Data Privacy

- Don't log sensitive board content - Encrypt data in transit (HTTPS) - Validate webhook signatures

1. 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

Links

• API Docs: https://developer.miro.com/
• Playground: https://developers.miro.com/playground
• Status: https://status.miro.com
• Support: https://support.miro.com
• Community: https://community.miro.com

Version History

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