Get items on board

GET 
/v2/boards/:board_id/items

Retrieves a list of items for a specific board. You can retrieve all items on the board, a list of child items inside a parent item, or a list of specific types of items by specifying URL query parameter values.

This method returns results using a cursor-based approach. A cursor-paginated method returns a portion of the total set of results based on the limit specified and a cursor that points to the next portion of the results. To retrieve the next portion of the collection, on your next call to the same method, set the cursor parameter equal to the cursor value you received in the response of the previous request. For example, if you set the limit query parameter to 10 and the board contains 20 objects, the first call will return information about the first 10 objects in the response along with a cursor parameter and value. In this example, let's say the cursor parameter value returned in the response is foo. If you want to retrieve the next set of objects, on your next call to the same method, set the cursor parameter value to foo.

Required scope

boards:read

Rate limiting

Level 2

Request

Path Parameters

board_id stringrequired

Unique identifier (ID) of the board for which you want to retrieve the list of available items.

Query Parameters

limit string

Possible values: >= 10 and <= 50

Default value: 10

type string

Possible values: [text, shape, sticky_note, image, document, card, app_card, preview, frame, embed]

cursor string

Responses

200

Items retrieved

application/json

Schema

Schema

data

object[]

Contains the result data.

Array [

createdAt date-time

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

createdBy

object

Contains information about the user who created the item.

id string

Unique identifier (ID) of the user.

type string

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

data

object

Contains the item data, such as the item title, content, or description.

oneOf

TextData

content stringrequired

The actual text (content) that appears in the text item.

EmbedData

contentType string

Type of the embedded item's content.

description string

Short description of the embedded item.

html string

Html code of the embedded item.

mode string

Possible values: [inline, modal]

Defines how the content in the embed item is displayed on the board. inline: The embedded content is displayed directly on the board. modal: The embedded content is displayed inside a modal overlay on the board.

previewUrl string

The URL to download the resource. You must use your access token to access the URL. The URL contains the redirect parameter and the format parameter to control the request execution as described in the following parameters: format parameter: By default, the image format is set to the preview image. If you want to download the original image, set the format parameter in the URL to original. redirect: By default, the redirect parameter is set to false and the resource object containing the URL and the resource type is returned with a 200 OK HTTP code. This URL is valid for 60 seconds. You can use this URL to retrieve the resource file. If the redirect parameter is set to true, a 307 TEMPORARY_REDIRECT HTTP response is returned. If you follow HTTP 3xx responses as redirects, you will automatically be redirected to the resource file and the content type returned can be image/png, 'image/svg', or 'image/jpg', depending on the original image type.

providerName string

Name of the content's provider.

providerUrl string

Url of the content's provider.

title string

Title of the embedded item.

url string

A valid URL pointing to the content resource that you want to embed in the board. Possible transport protocols: HTTP, HTTPS.

CardData

assigneeId int64

Unique user identifier. In the GUI, the user ID is mapped to the name of the user who is assigned as the owner of the task or activity described in the card. The identifier is numeric, and it is automatically assigned to a user when they first sign up.

description string

A short text description to add context about the card.

dueDate date-time

The date when the task or activity described in the card is due to be completed. In the GUI, users can select the due date from a calendar. Format: UTC, adheres to ISO 8601, includes a trailing Z offset.

title string

A short text header for the card.

AppCardData

description string

A short text description to add context about the app card.

fields

object[]

Array where each object represents a custom preview field. Preview fields are displayed on the bottom half of the app card in the compact view.

Array [

fillColor string

Hex value representing the color that fills the background area of the preview field, when it's displayed on the app card.

iconShape string

Possible values: [round, square]

Default value: round

The shape of the icon on the preview field.

iconUrl string

A valid URL pointing to an image available online. The transport protocol must be HTTPS. Possible image file formats: JPG/JPEG, PNG, SVG.

textColor string

Hex value representing the color of the text string assigned to value.

tooltip string

A short text displayed in a tooltip when clicking or hovering over the preview field.

value string

The actual data value of the custom field. It can be any type of information that you want to convey.

]

owned boolean

Defines whether the card is owned by the application making the call.

status string

Possible values: [disconnected, connected, disabled]

Status indicating whether an app card is connected and in sync with the source. When the source for the app card is deleted, the status returns disabled.

title string

A short text header to identify the app card.

ImageData

imageUrl string

The URL to download the resource. You must use your access token to access the URL. The URL contains the redirect parameter and the format parameter to control the request execution as described in the following parameters: format parameter: By default, the image format is set to the preview image. If you want to download the original image, set the format parameter in the URL to original. redirect: By default, the redirect parameter is set to false and the resource object containing the URL and the resource type is returned with a 200 OK HTTP code. This URL is valid for 60 seconds. You can use this URL to retrieve the resource file. If the redirect parameter is set to true, a 307 TEMPORARY_REDIRECT HTTP response is returned. If you follow HTTP 3xx responses as redirects, you will automatically be redirected to the resource file and the content type returned can be image/png, 'image/svg', or 'image/jpg', depending on the original image type.

title string

A short text header to identify the image.

DocumentData

documentUrl string

The URL to download the resource. You must use your access token to access the URL. The URL contains the redirect parameter to control the request execution. redirect: By default, the redirect parameter is set to false and the resource object containing the URL and the resource type is returned with a 200 OK HTTP code. This URL is valid for 60 seconds. You can use this URL to retrieve the resource file. If the redirect parameter is set to true, a 307 TEMPORARY_REDIRECT HTTP response is returned. If you follow HTTP 3xx responses as redirects, you will automatically be redirected to the resource file and the content type returned is application/octet-stream.

title string

A short text header to identify the document.

ShapeData

content string

The text you want to display on the shape.

shape string

Possible values: [rectangle, round_rectangle, circle, triangle, rhombus, parallelogram, trapezoid, pentagon, hexagon, octagon, wedge_round_rectangle_callout, star, flow_chart_predefined_process, cloud, cross, can, right_arrow, left_arrow, left_right_arrow, left_brace, right_brace]

Default value: rectangle

Defines the geometric shape of the item when it is rendered on the board.

FrameData

format string

Possible values: [custom, desktop, phone, tablet, a4, letter, ratio_1x1, ratio_4x3, ratio_16x9]

Default value: custom

Only custom frames are supported at the moment.

title string

Title of the frame. This title appears at the top of the frame.

type string

Possible values: [freeform, heap, grid, rows, columns]

Default value: freeform

Only free form frames are supported at the moment.

StickyNoteData

content string

The actual text (content) that appears in the sticky note item.

shape string

Possible values: [square, rectangle]

Default value: square

Defines the geometric shape of the sticky note and aspect ratio for its dimensions.

geometry

object

Contains geometrical information about the item, such as its width or height.

height double

Height of the item, in pixels.

rotation double

Rotation angle of an item, in degrees, relative to the board. You can rotate items clockwise (right) and counterclockwise (left) by specifying positive and negative values, respectively.

width double

Width of the item, in pixels.

id stringrequired

Unique identifier (ID) of an item.

modifiedAt date-time

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

modifiedBy

object

Contains information about the user who last modified the item.

id string

Unique identifier (ID) of the user.

type string

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

parent

object

Contains information about the parent frame for the item.

id int64

Unique identifier (ID) of the parent frame for the item.

position

object

Contains location information about the item, such as its x coordinate, y coordinate, and the origin of the x and y coordinates.

origin string

Possible values: [center]

Default value: center

Area of the item that is referenced by its x and y coordinates. For example, an item with a center origin will have its x and y coordinates point to its center. The center point of the board has x: 0 and y: 0 coordinates. Currently, only one option is supported.

relativeTo string

Possible values: [canvas_center, parent_top_left]

x double

X-axis coordinate of the location of the item on the board. By default, all items have absolute positioning to the board, not the current viewport. Default: 0. The center point of the board has x: 0 and y: 0 coordinates.

y double

Y-axis coordinate of the location of the item on the board. By default, all items have absolute positioning to the board, not the current viewport. Default: 0. The center point of the board has x: 0 and y: 0 coordinates.

type stringrequired

Type of item that is returned.

]

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 considering the cursor and the limit values sent in the request. For example, if there are 20 results, the request does not have a cursor value, and the limit set to 10, the size of the results will be 10.
In this example, the response will also return a cursor value that can be used to retrieve the next set of 10 remaining results in the collection.

cursor string

A cursor-paginated method returns a portion of the total set of results based on the limit specified and a cursor that points to the next portion of the results. To retrieve the next set of results of the collection, set the cursor parameter in your next request to the value returned in this parameter.

limit int32

Maximum number of results returned based on the limit specified in the request. For example, if there are 20 results, the request has no cursor value, and the limit is 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 cursor parameter value that you obtained from the response.

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.

Example (from schema)

{
  "data": [
    {
      "createdAt": "2022-03-30T17:26:50.000Z",
      "createdBy": {
        "id": "3458764517517852417",
        "type": "user"
      },
      "data": {},
      "geometry": {
        "height": 60,
        "rotation": 0,
        "width": 320
      },
      "id": "3458764517517819000",
      "modifiedAt": "2022-03-30T17:26:50.000Z",
      "modifiedBy": {
        "id": "3458764517517852417",
        "type": "user"
      },
      "parent": {
        "id": "3074457362577955300"
      },
      "position": {
        "origin": "center",
        "relativeTo": "canvas_center",
        "x": 100,
        "y": 100
      },
      "type": "sticky_note"
    }
  ],
  "total": 0,
  "size": 1,
  "cursor": "MzQ1ODc2NDUyMjQ5MDA4Mjg5NX4=",
  "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=="
  }
}

400

Malformed request

application/json

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

Example (from schema)

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

404

Not found

application/json

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

Example (from schema)

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

429

Too many requests

application/json

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

Example (from schema)

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

Loading...