Get boards

GET /v2/boards

Retrieves a list of boards that match the search criteria provided in the request. If you are an Enterprise customer and a Company Admin, you can retrieve all boards, including all private boards (boards that haven't been specifically shared with you) by enabling Content Admin permissions. To enable Content Admin permissions, see Content Admin permissions for Company Admins. Note that you only get results instantaneously when you filter by the team_id, project_id, or both the team_id and project_id. If you use any other filter, you need to give a few seconds for the indexing of newly created boards before retrieving boards.

Required scope

boards:read

Rate limiting

Level 1

Request

Query Parameters

team_id string

project_id string

query string

Possible values: <= 500 characters

owner string

limit string

Possible values: >= 1 and <= 50

offset string

sort string

Possible values: [default, last_modified, last_opened, last_created, alphabetically]

Default value: default

Responses

Board search results.

application/json

Schema
Example (from schema)

Schema

data

object[]

Contains the result data.

Array [

createdAt date-time

Date and time when the board was created. Format: UTC, adheres to ISO 8601, includes a trailing Z offset.

createdBy

object

Contains information about the user who created the board.

id stringrequired

Unique identifier (ID) of the user.

name stringrequired

Name of the user.

type stringrequired

Indicates the type of object returned. In this case, type returns user.

currentUserMembership

object

Contains the current user's board membership details. The current user could be different from the board owner.

id stringrequired

Unique identifier (ID) of the user.

name stringrequired

Name of the user.

role string

Possible values: [viewer, commenter, editor, coowner, owner]

Role of the board member.

type stringrequired

Type of the object that is returned. In this case, type returns board_member.

description stringrequired

Description of the board.

id stringrequired

Unique identifier (ID) of the board.

lastOpenedAt date-time

Date and time when the board was last opened by any user. This information is only available when the boards are sorted by last_opened. Format: UTC, adheres to ISO 8601, includes a trailing Z offset.

lastOpenedBy

object

Contains information about the user who opened the board last. This information is only available when the boards are sorted by last_opened.

id string

Unique identifier (ID) of the user.

name string

Name of the user.

type string

Indicates the type of object returned. In this case, type returns user.

modifiedAt date-time

Date and time when the board was last modified. Format: UTC, adheres to ISO 8601, includes a trailing Z offset.

modifiedBy

object

Contains information about the user who created the board.

id stringrequired

Unique identifier (ID) of the user.

name stringrequired

Name of the user.

type stringrequired

Indicates the type of object returned. In this case, type returns user.

name stringrequired

Name of the board.

owner

object

Contains information about the user who created the board.

id stringrequired

Unique identifier (ID) of the user.

name stringrequired

Name of the user.

type stringrequired

Indicates the type of object returned. In this case, type returns user.

picture

object

id int64

Id of the picture

imageURL string

Url of the picture

originalUrl string

Original team picture url for icon generation

type string

Default value: picture

Type of the object returned.

policy

object

Defines the permissions policies and sharing policies for the board.

permissionsPolicy

object

Defines the permissions policies for the board.

collaborationToolsStartAccess string

Possible values: [all_editors, board_owners_and_coowners]

Default value: all_editors

Defines who can start or stop timer, voting, video chat, screen sharing, attention management. Others will only be able to join. To change the value for the collaborationToolsStartAccess parameter, contact Miro Customer Support.

copyAccess string

Possible values: [anyone, team_members, team_editors, board_owner]

Default value: anyone

Defines who can copy the board, copy objects, download images, and save the board as a template or PDF.

sharingAccess string

Possible values: [team_members_with_editing_rights, owner_and_coowners]

Default value: team_members_with_editing_rights

Defines who can change access and invite users to this board. To change the value for the sharingAccess parameter, contact Miro Customer Support.

sharingPolicy

object

Defines the public-level, organization-level, and team-level access for the board. The access level that a user gets depends on the highest level of access that results from considering the public-level, team-level, organization-level, and direct sharing access.

access string

Possible values: [private, view, edit, comment]

Defines the public-level access to the board.

inviteToAccountAndBoardLinkAccess string

Possible values: [viewer, commenter, editor, coowner, owner, guest, no_access]

Default value: no_access

Defines the user role when inviting a user via the invite to team and board link. For Enterprise users, the inviteToAccountAndBoardLinkAccess parameter is always set to no_access.

organizationAccess string

Possible values: [private, view, comment, edit]

Default value: private

Defines the organization-level access to the board. If the board is created for a team that does not belong to an organization, the organizationAccess parameter is always set to the default value.

teamAccess string

Possible values: [private, view, comment, edit]

Defines the team-level access to the board.

team

object

id stringrequired

Team id

name stringrequired

Team name

picture

object

id int64

Id of the picture

imageURL string

Url of the picture

originalUrl string

Original team picture url for icon generation

type string

Default value: picture

Type of the object returned.

type string

Default value: team

Type of the object returned.

project

object

id stringrequired

Project ID.

name stringrequired

Name of the project.

type stringrequired

Default value: project

Type of the object returned.

type stringrequired

Type of the object that is returned. In this case, type returns board.

viewLink string

URL to view the board.

]

total int64

Total number of results available. If the value of the total parameter is higher than the value of the size parameter, this means that there are more results that you can retrieve. To retrieve more results, you can make another request and set the offset value accordingly. For example, if there are 30 results, and the request has the offset set to 0 and the limit set to 20, the size parameter will return 20 and the total parameter will return 30. This means that there are 9 more results to retrieve (as the offset is zero-based).

size int32

Number of results returned in the response. The size is the number of results returned considering the offset and the limit values sent in the request. For example, if there are 30 results, and the request has the offset set to 0 and the limit set to 20, the size of the results will be 20.
If there are 10 results, and the request has the offset set to 0 and the limit set to 20, the size of the results will be 10.
If there are 30 results, and the request has the offset set to 28 and the limit set to 20, the size of the results will be 2 as the offset is the zero-based offset of the first item in the collection.

offset int32

Zero-based index of the first item in the collection. For example, If there are 30 results, and the request has the offset set to 28, the response will return 2 results.

limit int32

Maximum number of results returned based on the limit specified in the request. For example, if there are 30 results, and the request has the offset set to 0 and the limit set to 20, the size of the results will be 20. The rest of the results will not be returned. To retrieve the rest of the results, you must make another request and set the appropriate value for the offset parameter. In this example, you will set the offset parameter to 20 as the offset is zero-based.

links

object

Contains pagination links for the collection.

first string

Link to retrieve information in the first page of the collection.

last string

Link to the retrieve information in the last page of the collection.

next string

Link to retrieve information in the next page of the collection.

prev string

Link to retrieve information in the previous page of the collection.

self string

Link to retrieve information in the current page of the collection.

type string

{
  "data": [
    {
      "createdAt": "2024-04-11T15:04:04.096Z",
      "createdBy": {
        "id": "3074457353169356300",
        "name": "John Smith",
        "type": "user"
      },
      "currentUserMembership": {
        "id": "3074457353169356300",
        "name": "John Smith",
        "role": "viewer",
        "type": "board_member"
      },
      "description": "Sample board description",
      "id": "uXjVOD6LSME=",
      "lastOpenedAt": "2024-04-11T15:04:04.097Z",
      "lastOpenedBy": {
        "id": "3074457353169356300",
        "name": "John Smith",
        "type": "user"
      },
      "modifiedAt": "2024-04-11T15:04:04.097Z",
      "modifiedBy": {
        "id": "3074457353169356300",
        "name": "John Smith",
        "type": "user"
      },
      "name": "Sample board name",
      "owner": {
        "id": "3074457353169356300",
        "name": "John Smith",
        "type": "user"
      },
      "picture": {
        "id": 3074457345618261500,
        "imageURL": "https://miro.images/5252525252/125252/266/144/1/size210.jpg",
        "originalUrl": "https://miro.com/original-image.jpg",
        "type": "picture"
      },
      "policy": {
        "permissionsPolicy": {
          "collaborationToolsStartAccess": "all_editors",
          "copyAccess": "anyone",
          "sharingAccess": "team_members_with_editing_rights"
        },
        "sharingPolicy": {
          "access": "private",
          "inviteToAccountAndBoardLinkAccess": "no_access",
          "organizationAccess": "private",
          "teamAccess": "private"
        }
      },
      "team": {
        "id": "3074457345618265000",
        "name": "My Team",
        "picture": {
          "id": 3074457345618261500,
          "imageURL": "https://miro.images/5252525252/125252/266/144/1/size210.jpg",
          "originalUrl": "https://miro.com/original-image.jpg",
          "type": "picture"
        },
        "type": "team"
      },
      "project": {
        "id": "3074457345618265000",
        "name": "Product Guild project",
        "type": "project"
      },
      "type": "board",
      "viewLink": "https://miro.com/app/board/uXjVOD6LSME="
    }
  ],
  "total": 1,
  "size": 1,
  "offset": 0,
  "limit": 20,
  "links": {
    "first": "http://api.miro.com/v2/boards/o9J_lJWSHdg=/items?limit=10&cursor=MzQ1ODc2NaSDN&#RDMDA3MzYyOX==",
    "last": "http://api.miro.com/v2/boards/o9J_lJWSHdg=/items?limit=10&cursor=MzQ1ODc2NDUyNDUyMDA3MzYyOX==",
    "next": "http://api.miro.com/v2/boards/o9J_lJWSHdg=/items?limit=10&cursor=MzQ1ODc2NDUyNDsdgsFEwfFJCw==",
    "prev": "http://api.miro.com/v2/boards/o9J_lJWSHdg=/items?limit=10&cursor=",
    "self": "http://api.miro.com/v2/boards/o9J_lJWSHdg=/items?limit=10&cursor=MzQ1OD1245643FWUyMDA3MzYyOX=="
  },
  "type": "string"
}

Malformed request

application/json

Schema
Example (from schema)

Schema

code string

Code of the error

message string

Description of the error

status int32

Status code of the error

type string

Type of the error

{
  "code": "error",
  "message": "Error message",
  "status": 400,
  "type": "error"
}

Not found

application/json

Schema
Example (from schema)

Schema

code string

Code of the error

message string

Description of the error

status int32

Status code of the error

type string

Type of the error

{
  "code": "error",
  "message": "Error message",
  "status": 400,
  "type": "error"
}

Too many requests

application/json

Schema
Example (from schema)

Schema

code string

Code of the error

message string

Description of the error

status int32

Status code of the error

type string

Type of the error

{
  "code": "error",
  "message": "Error message",
  "status": 400,
  "type": "error"
}

Get boards

/v2/boards

Required scope

Rate limiting

Request​

Query Parameters

Responses​

Request

Responses