REST API Reference Guide

Miro REST API Reference Guide: v1 -> v2

If your app currently uses the Miro REST API v1, it’s time to plan your migration to v2. The Miro Developer Platform 2.0 has completely revamped the REST API, focusing on performance and reliability, as well as the developer experience. This document serves as a reference, mapping each v1 endpoint to its v2 counterpart. For a higher-level explanation of these changes, be sure to check out the comparison guide.

Boards

The following table provides a direct comparison of each v1 REST API endpoint for Boards and Board User Connections, including:

  • Create Board, Get Board, Get Board Members, Share Board, Update Board, Get Current User Boards
  • Get Board User Connection, Update Board User Connection, Delete Board User Connection

In addition, there are a few endpoints in the v2 REST API for which a v1 equivalent did not exist, which you may find interesting.

v1 endpointv2 endpoint

  • Request type: POST
  • API endpoint URL:
    https://api.miro.com/v1/boards
  • Headers:
'Accept: application/json'
'Authorization: Bearer {{ACCESS_TOKEN}}'
'Content-Type: application/json'
  • Payload:
"name": "BOARD_NAME",
"sharingPolicy": {
    "access": "private",
    "teamAccess": "private"
},
"description": "BOARD_DESCRIPTION"









  • Request type: POST
  • API endpoint URL:
    https://api.miro.com/v2/boards
  • Headers:
'Accept: application/json'
'Authorization: Bearer {{ACCESS_TOKEN}}'
'Content-Type: application/json'
  • Payload:
"name": "BOARD_NAME",
"policy": {
    "permissionsPolicy": {
        "collaborationToolsStartAccess": "all_editors",
        "copyAccess": "anyone",
        "sharingAccess": "team_members_with_editing_rights"
    },
    "sharingPolicy": {
        "access": "private",
        "inviteToAccountAndBoardLinkAccess": "no_access",
        "organizationAccess": "private",
        "teamAccess": "private"
    }
},
"description": "BOARD_DESCRIPTION",
"teamId": "TEAM_ID"

  • Request type: GET
  • API endpoint URL:
    https://api.miro.com/v1/boards/{BOARD_ID}
  • Headers:
'Accept: application/json'
'Authorization: Bearer {{ACCESS_TOKEN}}'

  • Request type: GET
  • API endpoint URL:
    https://api.miro.com/v2/boards/{BOARD_ID}
  • Headers:
'Accept: application/json'
'Authorization: Bearer {{ACCESS_TOKEN}}'

  • Request type: GET
  • API endpoint URL:
    https://api.miro.com/v1/boards/{BOARD_ID}/user-connections
  • Headers:
'Accept: application/json'
'Authorization: Bearer {{ACCESS_TOKEN}}'
  • Payload: No payload required, unless specifying for pagination.

  • Request type: GET
  • API endpoint URL:
    https://api.miro.com/v2/boards/{BOARD_ID}/members
  • Headers:
'Accept: application/json'
'Authorization: Bearer {{ACCESS_TOKEN}}'
  • Payload: No payload required, unless specifying for pagination.


  • Request type: POST
  • API endpoint URL:
    https://api.miro.com/v1/boards/{BOARD_ID}/share
  • Headers:
'Accept: application/json'
'Authorization: Bearer {{ACCESS_TOKEN}}'
'Content-Type: application/json'
  • Payload:
"emails": [
    "EMAIL_ADDRESS_1",
    "EMAIL_ADDRESS_2",
    "ETC"
],
"teamInvitationStrategy": "invite_when_required",
"role": "viewer",
"message": "OPTIONAL_MESSAGE_FOR_RECIPIENTS"

  • Request type: POST
  • API endpoint URL:
    https://api.miro.com/v2/boards/{BOARD_ID}/members
  • Headers:
'Accept: application/json'
'Authorization: Bearer {{ACCESS_TOKEN}}'
'Content-Type: application/json'
  • Payload:
"emails": [
    "EMAIL_ADDRESS_1",
    "EMAIL_ADDRESS_2",
    "ETC"
],
"role": "viewer",
"message": "OPTIONAL_MESSAGE_FOR_RECIPIENTS"

  • Request type: PATCH
  • API endpoint URL:
    https://api.miro.com/v1/boards/{BOARD_ID}
  • Headers:
'Accept: application/json'
'Authorization: Bearer {{ACCESS_TOKEN}}'
'Content-Type: application/json'
  • Payload:
"sharingPolicy": {
    "access": "private",
    "teamAccess": "private"
},
"name": "NEW_BOARD_NAME",
"description": "NEW_BOARD_DESCRIPTION"








  • Request type: PATCH
  • API endpoint URL:
    https://api.miro.com/v2/boards/{BOARD_ID}
  • Headers:
'Accept: application/json'
'Authorization: Bearer {{ACCESS_TOKEN}}'
'Content-Type: application/json'
  • Payload:
"name": "NEW_BOARD_NAME",
"policy": {
    "permissionsPolicy": {
        "collaborationToolsStartAccess": "all_editors",
        "copyAccess": "anyone",
        "sharingAccess": "team_members_with_editing_rights"
    },
    "sharingPolicy": {
        "access": "private",
        "inviteToAccountAndBoardLinkAccess": "no_access",
        "organizationAccess": "private",
        "teamAccess": "private"
    }
},
"description": "NEW_BOARD_DESCRIPTION",
"teamId": "NEW_TEAM_ID"

  • Request type: GET
  • API endpoint URL:
    https://api.miro.com/v1/teams/{BOARD_ID}/boards
  • Headers:
'Accept: application/json'
'Authorization: Bearer {{ACCESS_TOKEN}}'
  • Payload: No payload required, unless specifying for pagination.








  • Request type: GET
  • API endpoint URL:
    https://api.miro.com/v2/boards
  • Headers:
'Accept: application/json'
'Authorization: Bearer {{ACCESS_TOKEN}}'
  • Required query parameter:
?team_id=TEAM_ID
  • Payload: No payload required, unless specifying for pagination.
  • Note: This is not an exact equivalent for the Get Current User Boards function, but it can achieve the same result. This function returns a list of boards that meet the provided search criteria. When specifying the team_id, the response will include all of the boards in the team that are visible to the user with whom the authorization token is associated.

  • Request type: GET
  • API endpoint URL:
    https://api.miro.com/v1/board-user-connections/{CONNECTION_ID}
  • Headers:
'Accept: application/json'
'Authorization: Bearer {{ACCESS_TOKEN}}'

  • Request type: GET
  • API endpoint URL:
    https://api.miro.com/v2/boards/{BOARD_ID}/members/{BOARD_MEMBER_ID}
  • Headers:
'Accept: application/json'
'Authorization: Bearer {{ACCESS_TOKEN}}'
  • Note: Connections are no longer treated as entities in the v2 REST API.

  • Request type: PATCH
  • API endpoint URL:
    https://api.miro.com/v1/board-user-connections/{CONNECTION_ID}
  • Headers:
'Accept: application/json'
'Authorization: Bearer {{ACCESS_TOKEN}}'
'Content-Type: application/json'
  • Payload:
{"role":"viewer"}

  • Request type: PATCH
  • API endpoint URL:
    https://api.miro.com/v2/boards/{BOARD_ID}/members/{BOARD_MEMBER_ID}
  • Headers:
'Accept: application/json'
'Authorization: Bearer {{ACCESS_TOKEN}}'
'Content-Type: application/json'
  • Payload:
{"role": "viewer"}
  • Note: Connections are no longer treated as entities in the v2 REST API.

  • Request type: DELETE
  • API endpoint URL:
    https://api.miro.com/v1/board-user-connections/{CONNECTION_ID}
  • Headers:
'Accept: application/json'
'Authorization: Bearer {{ACCESS_TOKEN}}'

  • Request type: DELETE
  • API endpoint URL:
    https://api.miro.com/v2/boards/{BOARD_ID}/members/{BOARD_MEMBER_ID}
  • Headers:
'Accept: application/json'
'Authorization: Bearer {{ACCESS_TOKEN}}'
  • Note: Connections are no longer treated as entities in the v2 REST API.

Widgets / Items

The Miro v2 REST API has replaced the polymorphic Widget API endpoints with specific, independent API endpoints for each type of widget ("item") on a Miro board. The following table provides a direct comparison of each v1 REST API endpoint for Board Content, including:

  • List All Widgets, Get Widget, Delete Widgets
  • Create Widget, Update Widget for the following widget types: Card, Sticker/Sticky Note, Text, Shape

Lines are not yet supported in the v2 REST API.

In addition, there are several endpoints for board content in the v2 REST API for which a v1 equivalent did not exist, including:

  • Tags
  • Additional widget/item types: App Card, Document, Embed, Frame, Image
  • Each item type also offers additional endpoints, such as Get Card Item and Delete Card Item, as well as type-specific endpoints that offer additional options for interacting with that item type.
v1 endpointv2 endpoint

  • Request type: GET
  • API endpoint URL:
    https://api.miro.com/v1/boards/{BOARD_ID}/widgets/
  • Headers:
'Accept: application/json'
'Authorization: Bearer {{ACCESS_TOKEN}}'
  • Optional Query Parameter: (to filter by widget type)
    ?widgetType=WIDGET_TYPE

  • Request type: GET
  • API endpoint URL:
    https://api.miro.com/v2/boards/{BOARD_ID}/items
  • Headers:
'Accept: application/json'
'Authorization: Bearer {{ACCESS_TOKEN}}'
  • Optional Query Parameter: (to filter by item type)
    ?type=ITEM_TYPE
  • Payload: No payload required, unless specifying for pagination.

  • Request type: GET
  • API endpoint URL:
    https://api.miro.com/v1/boards/{BOARD_ID}/widgets/{WIDGET_ID}
  • Headers:
'Accept: application/json'
'Authorization: Bearer {{ACCESS_TOKEN}}'

  • Request type: GET
  • API endpoint URL:
    https://api.miro.com/v2/boards/{BOARD_ID}/items/{ITEM_ID}
  • Headers:
'Accept: application/json'
'Authorization: Bearer {{ACCESS_TOKEN}}'

  • Request type: POST
    https://api.miro.com/v1/boards/{BOARD_ID}/widgets
  • Headers:
'Accept: application/json'
'Authorization: Bearer {{ACCESS_TOKEN}}'
'Content-Type: application/json'
  • Payload:
{
     "type": "card",
     "title": "CARD_TITLE",
     "Description": "CARD_DESCRIPTION" 
}

  • Request type: POST
  • API endpoint URL:
    https://api.miro.com/v2/boards/{board_id}/cards
  • Headers:
'Accept: application/json'
'Authorization: Bearer {{ACCESS_TOKEN}}'
'Content-Type: application/json'
  • Payload:
{
    "title": "CARD_TITLE",
    "description": "CARD_DESCRIPTION"
}

  • Request type: PATCH
  • API endpoint URL:
    https://api.miro.com/v1/boards/{BOARD_ID}/widgets/{WIDGET_ID}
  • Headers:
'Accept: application/json'
'Authorization: Bearer {{ACCESS_TOKEN}}'
'Content-Type: application/json'
  • Payload:
{
   "title": "NEW_CARD_TITLE",
   "description": "NEW_CARD_DESCRIPTION"
}

  • Request type: PATCH
  • API endpoint URL:
    https://api.miro.com/v2/boards/{board_id}/cards/{ITEM_ID}
  • Headers:
'Accept: application/json'
'Authorization: Bearer {{ACCESS_TOKEN}}'
'Content-Type: application/json'
  • Payload:
{
    "title": "NEW_CARD_TITLE",
    "description": "NEW_CARD_DESCRIPTION"
}

  • Request type: POST
  • API endpoint URL:
    https://api.miro.com/v1/boards/{BOARD_ID}/widgets
  • Headers:
'Accept: application/json'
'Authorization: Bearer {{ACCESS_TOKEN}}'
'Content-Type: application/json'
  • Payload:
{
   "type": "sticker",
   "text": "STICKER_TEXT"
}



  • Request type: POST
  • API endpoint URL:
    https://api.miro.com/v2/boards/{board_id}/sticky_notes
  • Headers:
'Accept: application/json'
'Authorization: Bearer {{ACCESS_TOKEN}}'
'Content-Type: application/json'
  • Payload:
{
    "content": "STICKY_NOTE_TEXT",
    "shape": "square"
}
  • Note: The name for this widget/item type has been updated from Sticker to Sticky Note in v2 for improved clarity.

  • Request type: PATCH
  • API endpoint URL:
    https://api.miro.com/v1/boards/{BOARD_ID}/widgets/{WIDGET_ID}
  • Headers:
'Accept: application/json'
'Authorization: Bearer {{ACCESS_TOKEN}}'
'Content-Type: application/json'
  • Payload:
{
     "text": "NEW_STICKER_TEXT"
}

  • Request type: PATCH
  • API endpoint URL:
    https://api.miro.com/v2/boards/{board_id}/sticky_notes/{ITEM_ID}
  • Headers:
'Accept: application/json'
'Authorization: Bearer {{ACCESS_TOKEN}}'
'Content-Type: application/json'
  • Payload:
{
    "content": "NEW_STICKY_NOTE_TEXT",
    "shape": "rectangle"
}

  • Request type: POST
  • API endpoint URL:
    https://api.miro.com/v1/boards/{BOARD_ID}/widgets
  • Headers:
'Accept: application/json'
'Authorization: Bearer {{ACCESS_TOKEN}}'
'Content-Type: application/json'
  • Payload:
{
   "type": "text",
   "text": "MESSAGE"
}

  • Request type: POST
  • API endpoint URL:
    https://api.miro.com/v2/boards/{board_id}/texts
  • Headers:
'Accept: application/json'
'Authorization: Bearer {{ACCESS_TOKEN}}'
'Content-Type: application/json'
  • Payload:
{
    "content": "MESSAGE"
}
  • Note: The text field in the data object payload has been renamed from text to content.

  • Request type: PATCH
  • API endpoint URL:
    https://api.miro.com/v1/boards/{BOARD_ID}/widgets/{WIDGET_ID}
  • Headers:
'Accept: application/json'
'Authorization: Bearer {{ACCESS_TOKEN}}'
'Content-Type: application/json'
  • Payload:
{
     "text": "NEW_MESSAGE"
}



  • Request type: PATCH
  • API endpoint URL:
    https://api.miro.com/v2/boards/{board_id}/texts/{ITEM_ID}
  • Headers:
'Accept: application/json'
'Authorization: Bearer {{ACCESS_TOKEN}}'
'Content-Type: application/json'
  • Payload:
{
    "content": "NEW_MESSAGE"
}
  • Note: The text field in the data object payload has been renamed from text to content.

  • Request type: POST
  • API endpoint URL:
    https://api.miro.com/v1/boards/{BOARD_ID}/widgets
  • Headers:
'Accept: application/json'
'Authorization: Bearer {{ACCESS_TOKEN}}'
'Content-Type: application/json'
  • Payload:
{
   "type": "shape",
   "text": "SHAPE_TEXT",
   "style": {
     "shapeType": "rectangle"
   }
}

  • Request type: POST
  • API endpoint URL:
    https://api.miro.com/v2/boards/{board_id}/shapes
  • Headers:
'Accept: application/json'
'Authorization: Bearer {{ACCESS_TOKEN}}'
'Content-Type: application/json'
  • Payload:
{
    "content": "SHAPE_TEXT",
    "shape": "rectangle"
}
  • Note: The shape field in the data object payload has been renamed from shapeType to shape.

  • Request type: PATCH
  • API endpoint URL:
    https://api.miro.com/v1/boards/{BOARD_ID}/widgets/{WIDGET_ID}
  • Headers:
'Accept: application/json'
'Authorization: Bearer {{ACCESS_TOKEN}}'
'Content-Type: application/json'
  • Payload:
{
   "text": "NEW_SHAPE_TEXT",
   "style": {
     "shapeType": "callout"
   }
}

  • Request type: PATCH
  • API endpoint URL:
    https://api.miro.com/v2/boards/{board_id}/shapes/{ITEM_ID}
  • Headers:
'Accept: application/json'
'Authorization: Bearer {{ACCESS_TOKEN}}'
'Content-Type: application/json'
  • Payload:
{
    "content": "NEW_SHAPE_TEXT",
    "shape": "wedge_round_rectangle_callout"
}
  • Note: The shape field in the data object payload has been renamed from shapeType to shape.

  • Request type: POST
  • API endpoint URL:
    https://api.miro.com/v1/boards/{BOARD_ID}/widgets
  • Headers:
'Accept: application/json'
'Authorization: Bearer {{ACCESS_TOKEN}}'
'Content-Type: application/json'
  • Payload:
{
     "type": "line",
   "style": {
     "lineType": "straight"
   }
}

Note: Lines are not currently supported in the Miro v2 REST API. This is a known issue. If you’d like updates on this feature, please subscribe by voting on the Feature Request in our Roadmap.















  • Request type: PATCH
  • API endpoint URL:
    https://api.miro.com/v1/boards/{BOARD_ID}/widgets/{WIDGET_ID}
  • Headers:
'Accept: application/json'
'Authorization: Bearer {{ACCESS_TOKEN}}'
'Content-Type: application/json'
  • Payload:
{
   "style": {
     "lineType": "orthogonal"
   }
}

Note: Lines are not currently supported in the Miro v2 REST API. This is a known issue. If you’d like updates on this feature, please subscribe by voting on the Feature Request in our Roadmap.















  • Request type: DELETE
  • API endpoint URL:
    https://api.miro.com/v1/boards/{BOARD_ID}/widgets/{WIDGET_ID}
  • Headers:
'Accept: application/json'
'Authorization: Bearer {{ACCESS_TOKEN}}'

  • Request type: DELETE
  • API endpoint URL:
    https://api.miro.com/v2/boards/{BOARD_ID}/items/{ITEM_ID}
  • Headers:
'Accept: application/json'
'Authorization: Bearer {{ACCESS_TOKEN}}'

Teams

The following table provides a direct comparison of each v1 REST API endpoint for Teams and Team User Connections, including:

  • Get Team, Update Team, List All Team Members, Get Team Current User Connection, Invite to Team
  • Get Team User Connection, Update Team User Connection, Delete Team User Connection

In addition, there are a few endpoints in the v2 REST API for which a v1 equivalent did not exist, which you may find interesting.

v1 endpointv2 endpoint

  • Request type: GET
  • API endpoint URL:
    https://api.miro.com/v1/teams/{TEAM_ID}
  • Headers:
'Accept: application/json'
'Authorization: Bearer {{ACCESS_TOKEN}}'



  • Request type: GET
  • API endpoint URL:
    https://api.miro.com/v2/orgs/{ORG_ID}/teams/{TEAM_ID}
  • Headers:
'Accept: application/json'
'Authorization: Bearer {{ACCESS_TOKEN}}'
  • Note: In the v2 REST API, Teams endpoints are available only to Enterprise plans.

  • Request type: PATCH
  • API endpoint URL:
    https://api.miro.com/v1/teams/{TEAM_ID}
  • Headers:
'Accept: application/json'
'Authorization: Bearer {{ACCESS_TOKEN}}'
'Content-Type: application/json'
  • Payload:
"name": "NEW_TEAM_NAME"



  • Request type: PATCH
  • API endpoint URL:
    https://api.miro.com/v2/orgs/{ORG_ID}/teams/{TEAM_ID}
  • Headers:
'Accept: application/json'
'Authorization: Bearer {{ACCESS_TOKEN}}'
'Content-Type: application/json'
  • Payload:
    "picture": {"originalUrl": "NEW_TEAM_IMG_URL"},
    "name": "NEW_TEAM_NAME"
  • Note: In the v2 REST API, Teams endpoints are available only to Enterprise plans.

  • Request type: GET
  • API endpoint URL:
    https://api.miro.com/v1/teams/{TEAM_ID}/user-connections
  • Headers:
'Accept: application/json'
'Authorization: Bearer {{ACCESS_TOKEN}}'
  • Payload: No payload required, unless specifying for pagination.

  • Request type: GET
  • API endpoint URL:
    https://api.miro.com/v2/orgs/{ORG_ID}/teams/{TEAM_ID}/members
  • Headers:
'Accept: application/json'
'Authorization: Bearer {{ACCESS_TOKEN}}'
  • Payload: No payload required, unless specifying for pagination.
  • Note: In the v2 REST API, Teams endpoints are available only to Enterprise plans.

  • Request type: GET
  • API endpoint URL:
    https://developers.miro.com/reference/get-team-current-user-connection
  • Headers:
'Accept: application/json'
'Authorization: Bearer {{ACCESS_TOKEN}}'

Note: There is no exact equivalent of this endpoint in the v2 REST API. However, you can use Get Access Token Context to retrieve the user object for the current authorized user.







  • Request type: POST
  • API endpoint URL:
    https://api.miro.com/v1/teams/{TEAM_ID}/invite
  • Headers:
'Accept: application/json'
'Authorization: Bearer {{ACCESS_TOKEN}}'
'Content-Type: application/json'
  • Payload:
"emails": [
    "EMAIL_ADDRESS_1",
    "EMAIL_ADDRESS_2",
    "ETC"
]

  • Request type: POST
  • API endpoint URL:
    https://api.miro.com/v2/orgs/{ORG_ID}/teams/{TEAM_ID}/members
  • Headers:
'Accept: application/json'
'Authorization: Bearer {{ACCESS_TOKEN}}'
'Content-Type: application/json'
  • Payload:
    {"userEmail": "EMAIL_ADDRESS"}
  • Note: In the v2 REST API, Teams endpoints are available only to Enterprise plans. Also, note that unlike the v1 Invite to Team endpoint, this endpoint can only invite one new email address at a time.


  • Request type: GET
  • API endpoint URL:
    https://api.miro.com/v1/team-user-connections/{CONNECTION_ID}
  • Headers:
'Accept: application/json'
'Authorization: Bearer {{ACCESS_TOKEN}}'





  • Request type: GET
  • API endpoint URL:
https://api.miro.com/v2/orgs/{ORG_ID} \
        /teams/{TEAM_ID}/members/{MEMBER_ID}
  • Headers:
'Accept: application/json'
'Authorization: Bearer {{ACCESS_TOKEN}}'
  • Note: In the v2 REST API, Teams endpoints are available only to Enterprise plans. In addition, connections are no longer treated as entities in v2.

  • Request type: PATCH
  • API endpoint URL:
    https://api.miro.com/v1/team-user-connections/{CONNECTION_ID}
  • Headers:
'Accept: application/json'
'Authorization: Bearer {{ACCESS_TOKEN}}'
'Content-Type: application/json'
  • Payload:
    {"role":"viewer"}




  • Request type: PATCH
  • API endpoint URL:
https://api.miro.com/v2/orgs/{ORG_ID} \
        /teams/{TEAM_ID}/members/{MEMBER_ID}
  • Headers:
'Accept: application/json'
'Authorization: Bearer {{ACCESS_TOKEN}}'
'Content-Type: application/json'
  • Payload:
    {"role":"viewer"}
  • Note: In the v2 REST API, Teams endpoints are available only to Enterprise plans. In addition, connections are no longer treated as entities in v2.

  • Request type: DELETE
  • API endpoint URL:
    https://api.miro.com/v1/team-user-connections/{CONNECTION_ID}
  • Headers:
'Accept: application/json'
'Authorization: Bearer {{ACCESS_TOKEN}}'





  • Request type: DELETE
  • API endpoint URL:
https://api.miro.com/v2/orgs/{ORG_ID} \
        /teams/{TEAM_ID}/members/{MEMBER_ID}
  • Headers:
'Accept: application/json'
'Authorization: Bearer {{ACCESS_TOKEN}}'
  • Note: In the v2 REST API, Teams endpoints are available only to Enterprise plans. In addition, connections are no longer treated as entities in v2.

Users

While User objects remain unchanged between the v1 REST API and v2, there are no longer specific endpoints for retrieving those User objects. Instead, user objects can be found nested in the relevant API responses (such as in the createdBy and modifiedBy fields).

The following v1 endpoints will not be available in v2:

As an alternative, you can use Get Access Token Context to retrieve the user object for the current authorized user.

Pictures

Picture Objects have been removed, and the ability to programmatically set or change an App picture, a Board picture, or a Team picture is no longer available.

The following v1 endpoints are not available in v2:

Audit Logs

Audit logs are unchanged between v1 and v2. Note that audit logs are only available for enterprise plans, and that any application calling the Get logs endpoint will need to be installed by the Company Admin.

Authorization Info

The Authorization object and endpoints remain unchanged between v1 and v2. However, we do plan to stop offering non-expiring tokens in the near future, and move to the more-secure expiring access tokens for every app. This change, when finalized, will be backwards-compatible.

The following authorization endpoints are available in v2:

For more information on using the OAuth 2.0 authorization code flow, check out the Getting Started guide.


Did this page help you?