Search documentation

Search for a topic, a control, or an event type.

    Docs / Workflows / Integrations / Miro

    Miro

    Read and manage boards, sticky notes, text, shapes, frames and connectors in a connected Miro team.

    Connecting

    Miro is available to organisations with the Miro connection feature enabled in OAIZ. This requirement applies to new connections and reconnections.

    Authorize OAIZ through Miro OAuth using the account that should act on the boards, select the Miro team and finish the return to OAIZ. Each connection acts for that user in the selected team. Board access and changes also depend on that user’s Miro permissions.

    boards:read
    Allows the connection to read boards and their canvas content.
    boards:write
    Allows the connection to create, change and delete boards and their canvas content.

    Boards, items and connectors

    Boards hold canvas items and connectors. A board name is display text. Use the complete returned IDs to identify resources, including any punctuation in a board ID. Board content operations check that the board belongs to the connection’s selected team.

    boardId
    The stable board identifier returned by a board listing or board creation. Supply it for operations on an existing board and its content.
    itemId
    The stable canvas item identifier returned by item listing, reading or creation. Use it together with its boardId.
    connectorId
    The stable connector identifier returned by connector listing, reading or creation. Connector operations use this ID together with boardId.

    Read tools

    List Boards
    Read one page of accessible boards in the selected team, including their IDs, names and returned links.
    Get Board
    Read one board’s details, including its description and any returned team, owner and modification information.
    List Items
    Read one page of canvas item summaries, optionally filtered by item type. Long text content is shortened to 200 characters in the listing.
    Get Item
    Read one canvas item’s returned content, style, position, geometry and parent frame.
    List Connectors
    Read one page of connectors with their IDs and any returned attachment, caption and style details.
    Get Connector
    Read one connector and the attachment, shape, caption and style information Miro returns.

    Write tools

    Create Board
    Create a board in the selected team with a name and optional description. Returns the created board.
    Update Board
    Change a board’s name or description. Returns its update status and the board when Miro supplies a completed result.
    Delete Board
    Delete a board and its canvas content. Returns the board ID and deletion confirmation.
    Create Sticky Note
    Add a sticky note with content and optional colour, shape, position, size and parent frame.
    Update Sticky Note
    Change an existing sticky note’s content or supported appearance and layout fields.
    Create Text
    Add a text item with optional text styling, position, width, rotation and parent frame.
    Update Text
    Change a text item’s content or supported text styling and layout fields.
    Create Shape
    Add a shape with optional content, styling, position, geometry and parent frame.
    Update Shape
    Change a shape’s content, shape type or supported styling and layout fields.
    Create Frame
    Add a frame with a title and optional position, dimensions and styling.
    Update Frame
    Change a frame’s title or supported styling and layout fields.
    Delete Item
    Delete a canvas item. Returns its board and item IDs with deletion confirmation.
    Create Connector
    Connect two distinct existing items on the same board, with optional shape, captions and style. Returns the connector.
    Update Connector
    Change a connector’s attachments, shape, captions or style. Returns the connector information supplied by Miro.
    Delete Connector
    Delete one connector. Returns its board and connector IDs with deletion confirmation.

    Reading more than one page

    Board listings use offset and return nextOffset when another page is available. Pass that value as the next offset. The default limit is 20 boards, with a range of 1 to 50.

    Item and connector listings use an opaque nextCursor. Pass it as cursor and repeat boardId to continue. Their limits default to 10, with a range of 10 to 50. An omitted limit uses the value from the cursor. Item listings also carry the original type filter when it is omitted.

    Each cursor belongs to its listing operation, board and options. Start a fresh listing when changing the board, limit or item type filter. Item and connector cursors are separate. These listings return one page at a time, rather than a complete board export. returnedCount counts that page, while totalCount is included only when Miro supplies it.

    Connector attachments and appearance

    A connector attaches startItem.id and endItem.id to two different existing items on its board. Frames are unsupported attachment targets. Each end can use snapTo with auto, top, right, bottom or left, or a custom position with both x and y. Choose one positioning option per end.

    Custom attachment coordinates are percentage strings from "0%" to "100%" relative to the attached item. For example, {"x":"100%","y":"50%"} selects the centre of its right edge. Caption positions also use percentage strings along the connector. These are REST API values, so keep the percent sign and quotes.

    Connector shape can be straight, elbowed or curved. Up to 20 captions can contain text or inline HTML, with at most 200 characters each. Style supports caption and line colours, line patterns, end decorations and caption orientation. fontSize is a decimal string from "10" to "288", and strokeWidth is a decimal string from "1" to "24", such as "2.5".

    Update inputs and results

    Omitted fields are not sent to Miro. Supply only the fields to change, and leave other fields out. Explicit null values and empty updates are rejected. Canvas creation and updates return the item with its boardId and itemId, plus content and layout fields supplied by Miro. Connector attachment and style details in results also depend on what Miro returns.