canonical: https://jentic.com/apis/miro.com/miro

# Miro API

Jentic publishes the only available OpenAPI specification for Miro API, keeping it validated and agent-ready. Miro is a collaborative whiteboard platform whose v2 REST API exposes endpoints for managing boards, board items (sticky notes, shapes, text, connectors, frames, images), board members, tags, and organisation teams. The 21 endpoints cover the core flows for programmatically creating, updating, and reading whiteboard content. Suited to workflow tools, integrations, and AI agents that draft visual artifacts.

## For AI agents

Create boards and add sticky notes, shapes, text, connectors, frames, and images on Miro. Manage board members, tags, and organisation teams through a single REST API.

## Scope

Does not handle real-time cursor sync, video conferencing, or document editing - use for programmatic board content and membership management only.

## Capabilities

- Create a new board with POST /v2/boards and update or archive it via PATCH and DELETE /v2/boards/{board_id}
- List items on a board through GET /v2/boards/{board_id}/items and inspect a single item with /items/{item_id}
- Add sticky notes, shapes, text, connectors, frames, and images using the dedicated POST endpoints under /v2/boards/{board_id}
- Move or restyle existing items via PATCH /v2/boards/{board_id}/items/{item_id} and remove them with DELETE on the same path
- Invite collaborators with POST /v2/boards/{board_id}/members and read membership via GET on the same path
- Apply taxonomy with GET and POST /v2/boards/{board_id}/tags
- List teams and members in an organisation via GET /v2/orgs/{org_id}/teams and /v2/orgs/{org_id}/members

## Use cases

### AI-Generated Brainstorm Boards

An agent creates a board with POST /v2/boards, adds frames for each topic, and posts sticky notes generated from a brief. POST /v2/boards/{board_id}/sticky_notes places each idea at coordinates inside the right frame. Useful for kicking off design or planning sessions with structured starting content.

Example prompt: POST /v2/boards, then POST /v2/boards/{board_id}/sticky_notes for each idea with x/y coordinates inside the chosen frame

### Diagram Sync from Source of Truth

Render a system diagram on Miro from a source-of-truth definition such as YAML or Terraform state. The agent creates shapes for each node and connectors for each edge via POST /v2/boards/{board_id}/shapes and /connectors. When the source updates, the agent diffs and patches existing items by id rather than rebuilding the board.

Example prompt: POST shapes for each node, POST /v2/boards/{board_id}/connectors with start_item_id and end_item_id for each edge, then PATCH any existing items whose source has changed

### Retrospective Capture and Tagging

After a sprint retrospective, an agent reads the items on the retro board, classifies them into 'keep', 'change', and 'try', and applies the corresponding tags via POST /v2/boards/{board_id}/tags and PATCH on each item. Captures the outcome in a structured way without manual tagging.

Example prompt: GET /v2/boards/{board_id}/items, classify each sticky text, then PATCH each /items/{item_id} adding the matching tag

### Org and Team Provisioning

Provision new Miro teams as part of HR onboarding by reading existing structure with GET /v2/orgs/{org_id}/teams and adding members to relevant boards via POST /v2/boards/{board_id}/members. Keeps Miro access in sync with the source-of-truth directory without manual board sharing.

Example prompt: GET /v2/orgs/{org_id}/members for the new hire's email, then POST /v2/boards/{board_id}/members on every board where the team should have access

### Agent-Driven Whiteboard Content

An AI agent uses Jentic to draft visuals on demand: brainstorms, retros, or architecture views. Jentic scopes the bearer token so the agent never holds it directly, and Jentic surfaces the right item-creation endpoint per intent so the agent does not memorise the catalogue of POST routes.

Example prompt: Search Jentic for 'add a sticky note to a Miro board', load the schema, and post the agent's outputs as sticky notes to the chosen board

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /v2/boards | Create a board |
| GET | /v2/boards/{board_id}/items | List items on a board |
| POST | /v2/boards/{board_id}/sticky_notes | Add a sticky note |
| POST | /v2/boards/{board_id}/shapes | Add a shape |
| POST | /v2/boards/{board_id}/connectors | Add a connector |
| PATCH | /v2/boards/{board_id}/items/{item_id} | Update an item |
| POST | /v2/boards/{board_id}/members | Invite a board member |
| GET | /v2/orgs/{org_id}/teams | List org teams |

## Key resources

- **Boards** — Create, update, list, and archive Miro boards
- **Items** — Sticky notes, shapes, text, connectors, frames, and images on a board
- **Members** — Invite, list, and manage board collaborators
- **Tags** — Define and apply tags to items on a board
- **Org** — List teams and members at the organisation level

## Why Jentic

- **Setup:** Wiring Miro by hand means handling its bearer auth against api.miro.com, refreshing OAuth tokens, and coding the board, item, and membership calls yourself. Through Jentic you install once, import Miro from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Miro puts the board id and item id in the URL path (/v2/boards/{board_id}/items/{item_id}), so a rule can pin your agent to one board: it can add sticky notes and shapes there and nothing else. You choose the operations it may call, so adding a member is not included unless you add it.
- **Credential handling:** Your Miro bearer token is stored once, encrypted, by your own Jentic One instance and injected at execution time, with OAuth refresh handled centrally. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'add a sticky note' or 'create a Miro board', and Jentic returns the matching operation with its input schema, including the right coordinate and content fields, so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Mural** — Mural is a collaborative whiteboard platform with templates aimed at facilitated workshops
- **Figma** — Figma handles design fidelity that can be embedded into or complement Miro boards
- **Linear** — Linear converts retrospective sticky notes from Miro into trackable tasks

## FAQ

### Why is there no official OpenAPI spec for Miro API?

Miro does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Miro API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Miro API use?

Miro v2 uses HTTP bearer token authentication. Tokens are typically obtained via Miro's OAuth 2.0 install flow and sent in the Authorization header as `Bearer <token>`. Jentic stores the bearer in its vault and injects it per call.

### Can I add a sticky note to a Miro board with this API?

Yes. POST /v2/boards/{board_id}/sticky_notes accepts the note text, fill colour, and absolute or frame-relative coordinates. The response includes the new item id, which can be passed to PATCH /v2/boards/{board_id}/items/{item_id} to move or restyle it later.

### How do I draw a connector between two items?

First create the source and target items (shape, sticky note, frame, etc.) and capture their item ids. Then POST /v2/boards/{board_id}/connectors with start_item_id and end_item_id; Miro draws the connector between them.

### How do I create a Miro board through Jentic?

Run `pip install jentic`, search Jentic for 'create a Miro board', and Jentic returns the POST /v2/boards operation with its input schema. Provide a name and optional description, then execute. The response contains the new board_id.

### Can I list members of a Miro organisation?

Yes. GET /v2/orgs/{org_id}/members returns members at the organisation level and GET /v2/orgs/{org_id}/teams returns the teams. Use these endpoints to drive provisioning flows that match Miro access to your directory.

### Can I limit what my agent is allowed to do with the Miro API?

Yes. Because you run Jentic One yourself, your own rules decide which Miro operations and which bearer token the agent may use. Since Miro puts the board id and item id in the URL path, such as /v2/boards/{board_id}/items/{item_id}, a rule can pin the agent to a single board so it can add sticky notes and shapes there and nothing else. You pick the operations it may call, so inviting a board member via POST /v2/boards/{board_id}/members stays off limits unless you explicitly allow it.