A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Miro API is how an app or AI agent works with a Miro account: reading boards, adding sticky notes and shapes to a board, connecting two items with a line, and sharing a board with people. Access is granted through an OAuth token and a set of scopes, where the board scopes decide whether the token can read a board or change what is on it, and a token reaches only the boards and the data its scopes allow. The current version replaced an older single interface with separate methods for each kind of item.
How an app or AI agent connects to Miro determines what it can reach. There is a route for making calls and a hosted server that exposes Miro tools to agents, and each is governed by the token behind it and the permissions that token carries.
The REST API answers at https://api.miro.com and returns JSON. Version 2 has separate typed endpoints for each kind of item, such as sticky notes, shapes, and connectors, while a few platform endpoints like the OAuth token exchange still sit under version 1. A call authenticates with an OAuth access token sent as a Bearer token.
Miro runs a hosted Model Context Protocol server at https://mcp.miro.com that exposes Miro tools to AI agents, covering creating a board, creating items, reading content, and replying to comments. It authenticates through OAuth, and an organization admin must enable it for an Enterprise organization before its members can connect. It launched in public beta.
Miro uses the OAuth 2.0 authorization code grant. The user is sent to authorize the app, the returned code is exchanged for an access token and a refresh token, and the access token is sent as a Bearer token. By default an access token is valid for 60 minutes and the refresh token for 60 days, and each refresh issues a new pair, so the 60-day window keeps resetting for an app in regular use. Miro recommends expiring tokens.
An app declares the scopes it needs at install. The board scopes boards:read and boards:write cover boards, their items, and their members; identity:read returns the current user's profile and email; team:read and organizations:read and the organizations:teams scopes reach team and organization data on Enterprise plans. A token can act only within the scopes it was granted.
The Miro API is split into areas an agent can act on, like boards, the items on a board, board members, tags, and groups. Each area has its own methods, and the board scopes decide whether an agent can read a board or change what is on it.
List boards, read a single board, create a board, copy an existing board, update a board, and delete a board.
List the items on a board, read a single item, move an item, and delete an item, across every item type at once.
Create, read, update, and delete sticky note items on a board.
Create, read, update, and delete shape items on a board.
Create, read, update, and delete text items on a board.
Create, read, update, and delete card items on a board.
Add an image to a board from a URL, read an image item, replace it, and delete it.
Create, read, update, and delete frames, the containers that group items into sections of a board.
List, read, create, update, and delete connectors, the lines that link two items on a board.
Share a board with people, list its members, read a member, change a member's role, and remove a member.
List a board's tags, read a tag, create a tag, update a tag, and delete a tag.
List the groups on a board, read a group, create a group from items, update a group, and ungroup items.
Read an organization, list and read its members, and create, read, update, and delete the teams inside it.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
BoardsList boards, read a single board, create a board, copy an existing board, update a board, and delete a board.6 | ||||||
| GET | /v2/boards | List the boards the token can access. | read | boards:read | Current | |
Returns the boards visible to the connected user. Read access to boards is granted by the boards:read scope. Acts onboard Permission (capability) boards:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/boards/{board_id} | Get a single board by its identifier. | read | boards:read | Current | |
Read access to boards is granted by the boards:read scope. Acts onboard Permission (capability) boards:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/boards | Create a new board. | write | boards:write | Current | |
Creating, changing, and deleting boards is granted by the boards:write scope. Acts onboard Permission (capability) boards:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v2/boards | Copy an existing board into a new one, passing the source board through a copy_from query parameter. | write | boards:write | Current | |
The source board is named in the copy_from query parameter rather than the path. Granted by the boards:write scope. Acts onboard Permission (capability) boards:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v2/boards/{board_id} | Update a board's name, description, sharing policy, or permissions. | write | boards:write | Current | |
Granted by the boards:write scope. Acts onboard Permission (capability) boards:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v2/boards/{board_id} | Delete a board and everything on it. | write | boards:write | Current | |
Removes the board and all of its items. Granted by the boards:write scope. Acts onboard Permission (capability) boards:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ItemsList the items on a board, read a single item, move an item, and delete an item, across every item type at once.4 | ||||||
| GET | /v2/boards/{board_id}/items | List the items on a board, optionally filtered by type or by a parent frame. | read | boards:read | Current | |
Returns every item type in one call. The parent_item_id parameter narrows it to the items inside a frame. Granted by the boards:read scope. Acts onitem Permission (capability) boards:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/boards/{board_id}/items/{item_id} | Get a single item on a board by its identifier. | read | boards:read | Current | |
Granted by the boards:read scope. Acts onitem Permission (capability) boards:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v2/boards/{board_id}/items/{item_id} | Move an item or change its parent frame. | write | boards:write | Current | |
This generic update changes position and parent only. Content changes use the type-specific update method for that item. Granted by the boards:write scope. Acts onitem Permission (capability) boards:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v2/boards/{board_id}/items/{item_id} | Delete an item from a board, whatever its type. | write | boards:write | Current | |
Granted by the boards:write scope. Acts onitem Permission (capability) boards:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Sticky notesCreate, read, update, and delete sticky note items on a board.2 | ||||||
| POST | /v2/boards/{board_id}/sticky_notes | Create a sticky note on a board. | write | boards:write | Current | |
Granted by the boards:write scope. Acts onsticky_note Permission (capability) boards:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v2/boards/{board_id}/sticky_notes/{item_id} | Update a sticky note's text, color, or position. | write | boards:write | Current | |
Granted by the boards:write scope. Read and delete for a sticky note use the generic item methods. Acts onsticky_note Permission (capability) boards:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ShapesCreate, read, update, and delete shape items on a board.2 | ||||||
| POST | /v2/boards/{board_id}/shapes | Create a shape on a board. | write | boards:write | Current | |
Granted by the boards:write scope. Acts onshape Permission (capability) boards:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v2/boards/{board_id}/shapes/{item_id} | Update a shape's type, text, style, or position. | write | boards:write | Current | |
Granted by the boards:write scope. Acts onshape Permission (capability) boards:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
TextCreate, read, update, and delete text items on a board.2 | ||||||
| POST | /v2/boards/{board_id}/texts | Create a text item on a board. | write | boards:write | Current | |
Granted by the boards:write scope. Acts ontext Permission (capability) boards:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v2/boards/{board_id}/texts/{item_id} | Update a text item's content, style, or position. | write | boards:write | Current | |
Granted by the boards:write scope. Acts ontext Permission (capability) boards:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CardsCreate, read, update, and delete card items on a board.2 | ||||||
| POST | /v2/boards/{board_id}/cards | Create a card on a board. | write | boards:write | Current | |
Granted by the boards:write scope. Acts oncard Permission (capability) boards:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v2/boards/{board_id}/cards/{item_id} | Update a card's title, description, dates, or position. | write | boards:write | Current | |
Granted by the boards:write scope. Acts oncard Permission (capability) boards:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ImagesAdd an image to a board from a URL, read an image item, replace it, and delete it.2 | ||||||
| POST | /v2/boards/{board_id}/images | Add an image to a board from a public URL. | write | boards:write | Current | |
A companion endpoint adds an image by uploading a file from the device. Granted by the boards:write scope. Acts onimage Permission (capability) boards:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/boards/{board_id}/images/{item_id} | Get an image item on a board. | read | boards:read | Current | |
Granted by the boards:read scope. Acts onimage Permission (capability) boards:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
FramesCreate, read, update, and delete frames, the containers that group items into sections of a board.2 | ||||||
| POST | /v2/boards/{board_id}/frames | Create a frame, a labelled section that can hold other items. | write | boards:write | Current | |
Items placed inside a frame move with it. Granted by the boards:write scope. Acts onframe Permission (capability) boards:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/boards/{board_id}/frames/{item_id} | Get a frame on a board. | read | boards:read | Current | |
Granted by the boards:read scope. The items list method, with a parent_item_id, returns the items inside a frame. Acts onframe Permission (capability) boards:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ConnectorsList, read, create, update, and delete connectors, the lines that link two items on a board.4 | ||||||
| GET | /v2/boards/{board_id}/connectors | List the connectors on a board. | read | boards:read | Current | |
Granted by the boards:read scope. Acts onconnector Permission (capability) boards:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/boards/{board_id}/connectors | Create a connector linking two items on a board. | write | boards:write | Current | |
A connector references the start and end item ids. Granted by the boards:write scope. Acts onconnector Permission (capability) boards:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v2/boards/{board_id}/connectors/{connector_id} | Update a connector's endpoints, style, or captions. | write | boards:write | Current | |
Connectors use a connector_id in the path rather than the generic item_id. Granted by the boards:write scope. Acts onconnector Permission (capability) boards:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v2/boards/{board_id}/connectors/{connector_id} | Delete a connector from a board. | write | boards:write | Current | |
Granted by the boards:write scope. Acts onconnector Permission (capability) boards:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Board membersShare a board with people, list its members, read a member, change a member's role, and remove a member.4 | ||||||
| POST | /v2/boards/{board_id}/members | Share a board by inviting people to it by email and setting their role. | write | boards:write | Current | |
Grants people access to the board at the role chosen. Granted by the boards:write scope. Acts onboard_member Permission (capability) boards:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/boards/{board_id}/members | List the members of a board and their roles. | read | boards:read | Current | |
Returns who can reach the board and at what role. Granted by the boards:read scope. Acts onboard_member Permission (capability) boards:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v2/boards/{board_id}/members/{board_member_id} | Change a board member's role. | write | boards:write | Current | |
Granted by the boards:write scope. Acts onboard_member Permission (capability) boards:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v2/boards/{board_id}/members/{board_member_id} | Remove a member from a board. | write | boards:write | Current | |
Revokes that person's access to the board. Granted by the boards:write scope. Acts onboard_member Permission (capability) boards:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
TagsList a board's tags, read a tag, create a tag, update a tag, and delete a tag.4 | ||||||
| GET | /v2/boards/{board_id}/tags | List the tags on a board. | read | boards:read | Current | |
Tags can be attached to cards and sticky notes. Granted by the boards:read scope. Acts ontag Permission (capability) boards:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/boards/{board_id}/tags | Create a tag on a board. | write | boards:write | Current | |
Granted by the boards:write scope. Acts ontag Permission (capability) boards:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v2/boards/{board_id}/tags/{tag_id} | Update a tag's title or color. | write | boards:write | Current | |
Granted by the boards:write scope. Acts ontag Permission (capability) boards:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v2/boards/{board_id}/tags/{tag_id} | Delete a tag, removing it from every item it was on. | write | boards:write | Current | |
Granted by the boards:write scope. Acts ontag Permission (capability) boards:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
GroupsList the groups on a board, read a group, create a group from items, update a group, and ungroup items.4 | ||||||
| GET | /v2/boards/{board_id}/groups | List the groups on a board and the items in each. | read | boards:read | Current | |
A group ties several items together so they move as one. Granted by the boards:read scope. Acts ongroup Permission (capability) boards:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/boards/{board_id}/groups | Create a group from a set of items. | write | boards:write | Current | |
Granted by the boards:write scope. Acts ongroup Permission (capability) boards:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v2/boards/{board_id}/groups/{group_id} | Update a group, replacing its set of items. | write | boards:write | Current | |
Granted by the boards:write scope. Acts ongroup Permission (capability) boards:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v2/boards/{board_id}/groups/{group_id} | Ungroup the items in a group, keeping the items by default or deleting them with a delete_items query parameter. | write | boards:write | Current | |
By default the items survive and only the grouping is removed; setting delete_items to true deletes the items too. Granted by the boards:write scope. Acts ongroup Permission (capability) boards:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Organizations & teamsRead an organization, list and read its members, and create, read, update, and delete the teams inside it.5 | ||||||
| GET | /v2/orgs/{org_id} | Get an organization's details on an Enterprise plan. | read | organizations:read | Current | |
Enterprise plans only. Granted by the organizations:read scope, which is separate from the board scopes. Acts onorganization Permission (capability) organizations:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/orgs/{org_id}/members | List the members of an organization on an Enterprise plan. | read | organizations:read | Current | |
Enterprise plans only. Granted by the organizations:read scope. Acts onorganization_member Permission (capability) organizations:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/orgs/{org_id}/teams | List the teams in an organization on an Enterprise plan. | read | organizations:teams:read | Current | |
Enterprise plans only. Granted by the organizations:teams:read scope. Acts onteam Permission (capability) organizations:teams:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/orgs/{org_id}/teams | Create a team in an organization on an Enterprise plan. | write | organizations:teams:write | Current | |
Enterprise plans only. Granted by the organizations:teams:write scope. Acts onteam Permission (capability) organizations:teams:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v2/orgs/{org_id}/teams/{team_id} | Delete a team in an organization on an Enterprise plan. | write | organizations:teams:write | Current | |
Enterprise plans only. Granted by the organizations:teams:write scope. Acts onteam Permission (capability) organizations:teams:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Miro can notify an app or AI agent when something changes on a board, instead of the app repeatedly asking.
| Event | What it signals | Triggered by |
|---|
Miro limits how fast an app or AI agent can call through a credit budget that is spent per minute, where each method costs a set number of credits.
Miro meters requests with a credit budget rather than a flat request count. Each app gets 100,000 credits per minute, and every method is assigned a weight level that sets its cost: a Level 1 method costs 50 credits, Level 2 costs 100, Level 3 costs 500, and Level 4 costs 2,000, which works out to 2,000, 1,000, 200, and 50 calls per minute respectively if only that method is used. Every response carries the headers X-RateLimit-Limit for the per-minute credit total, X-RateLimit-Remaining for the credits left, and X-RateLimit-Reset for when the budget resets. Going over returns HTTP 429 with the code tooManyRequests.
List endpoints page through results, taking a limit parameter for the page size. Most endpoints use offset-based paging through a cursor or offset, and Miro is moving newer and heavier endpoints, such as audit logs, to cursor-based paging, where each response returns a cursor to pass into the next call. The exact default and maximum page size are set per endpoint, so each endpoint's own reference states its values.
Responses are JSON. Page size is capped per endpoint through the limit parameter, and bulk item creation, which adds several items in one call, has its own batch ceiling. Miro does not publish a single request payload size limit across the whole API.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | badRequest | The request was malformed, or a parameter is missing or invalid. | Read the message field, correct the request, and resend. |
| 401 | tokenNotProvided | No access token was sent, or the token is invalid or expired. The code field may also read oauthError for a bad authorization code. | Send a valid Bearer access token, refreshing it first if it has expired. |
| 403 | insufficientPermissions | The token is valid but lacks the scope the request needs. The message names the required scope, such as boards:write. | Grant the named scope to the app and have the user reauthorize. |
| 404 | notFound | The board, item, or other resource does not exist, or the token cannot see it. | Confirm the identifier is correct and the token has access to the resource. |
| 409 | conflict | The request conflicts with the current state, such as removing the last administrator of a team or organization. | Resolve the conflicting state, then retry. |
| 429 | tooManyRequests | The credit budget for the current minute is spent. The response body reads 'Request rate limit exceeded'. | Wait until the time in the X-RateLimit-Reset header, then retry. |
| 500 | internalError | An error on Miro's side. It is uncommon. | Retry after a short backoff, and contact Miro support if it persists. |
Miro runs version 2 of its REST API, which replaced the older version 1 widget interface with separate typed endpoints for each kind of item.
Version 2 is the current Miro REST API. It replaced version 1's single polymorphic widget interface with separate typed endpoints for each kind of item, such as sticky notes, shapes, cards, images, frames, and connectors, each with its own create, read, update, and delete methods. A few platform endpoints, including the OAuth token exchange, remain under version 1. Miro ships dated changes through its changelog and governs endpoint retirements through a published lifecycle policy.
Miro officially discontinued the experimental webhooks feature and its subscription endpoints on 5 December 2025. The endpoints no longer function, and Miro said it is exploring other options that provide the stability needed to build on top of Miro. Until a replacement ships, there is no supported way to receive pushed board events.
Miro added an experimental tools namespace to the Web SDK, letting an app read and set the active board tool. It includes getTool to read the current tool and setTool to change it. This is a Web SDK change rather than a REST API change.
Version 1 still hosts a few platform endpoints, such as the OAuth token exchange.
Miro API changelog ↗Bollard AI sits between a team's AI agents and Miro. Grant each agent exactly the access it needs, read or write, board by board, and every call is checked and logged.