Create items in bulk
POST/v2-experimental/boards/:board_id/items/bulk
Adds different types of items to a board. You can add up to 20 items of the same or different type per create call. For example, you can create 3 shape items, 4 card items, and 5 sticky notes in one create call. The bulk create operation is transactional. If any item's create operation fails, the create operation for all the remaining items also fails, and none of the items will be created.
To try out this API in our documentation:
1. In the BODY PARAMS section, scroll down until you see ADD OBJECT (Figure 1).
Figure 1. Add object user interface in readme
2. Click ADD OBJECT, and then select or enter the appropriate values for parameters of the item that you want to add.
3. Repeat steps 1 and 2 for each item that you want to add.
Required scope
boards:writeRate limiting
Level 2 per item. For example, if you want to create one sticky note, one card, and one shape item in one call, the rate limiting applicable will be 300 credits. This is because create item calls take Level 2 rate limiting of 100 credits each, 100 for sticky note, 100 for card, and 100 for shape item.Request
Path Parameters
Unique identifier (ID) of the board where you want to create the item.
- application/json
Body
array
required
Array [
- AppCardData
- CardData
- DocumentUrlData
- EmbedUrlData
- ImageUrlData
- ShapeData
- StickyNoteData
- TextData
Array [
]
- AppCardStyle
- CardStyle
- ShapeStyle
- StickyNoteStyle
- TextStyle
]
Possible values: [app_card, text, shape, sticky_note, image, document, card, frame, embed]
Type of item that you want to create.
data
object
Contains data information applicable for each item type.
oneOf
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.
Hex value representing the color that fills the background area of the preview field, when it's displayed on the app card.
Possible values: [round, square]
Default value: round
The shape of the icon on the preview field.
A valid URL pointing to an image available online. The transport protocol must be HTTPS. Possible image file formats: JPG/JPEG, PNG, SVG.
Hex value representing the color of the text string assigned to value.
A short text displayed in a tooltip when clicking or hovering over the preview field.
The actual data value of the custom field. It can be any type of information that you want to convey.
Defines whether the card is owned by the application making the call.
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.
A short text header to identify the app card.
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.
A short text description to add context about the card.
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.
A short text header for the card.
A short text header to identify the document.
Default value: https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf
URL where the document is hosted.
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.
URL of the image to be used as the preview image for the embedded item.
Default value: https://www.youtube.com/watch?v=HlVSNEiFCBk
A valid URL pointing to the content resource that you want to embed in the board. Possible transport protocols: HTTP, HTTPS.
A short text header to identify the image.
Default value: https://miro.com/static/images/page/mr-index/localization/en/slider/ideation_brainstorming.png
URL of the image.
The text you want to display on the shape.
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.
The actual text (content) that appears in the sticky note item.
Possible values: [square, rectangle]
Default value: square
Defines the geometric shape of the sticky note and aspect ratio for its dimensions.
The actual text (content) that appears in the text item.
style
object
Contains information about item-specific styles.
oneOf
Hex value of the border color of the app card.
Default: #2d9bf0.
Hex value of the border color of the card.
Default: #2d9bf0.
Defines the color of the border of the shape.
Default: #1a1a1a (dark gray).
Possible values: <= 1
Defines the opacity level of the shape border.
Possible values: any number between 0.0 and 1.0, where:
0.0: the background color is completely transparent or invisible
1.0: the background color is completely opaque or solid
Default: 1.0 (solid color).
Possible values: [normal, dotted, dashed]
Defines the style used to represent the border of the shape.
Default: normal.
Possible values: >= 1 and <= 24
Defines the thickness of the shape border, in dp.
Default: 2.0.
Hex value representing the color for the text within the shape item.
Default: #1a1a1a.
Fill color for the shape.
Hex values: #f5f6f8 #d5f692 #d0e17a #93d275 #67c6c0 #23bfe7 #a6ccf5 #7b92ff #fff9b1 #f5d128 #ff9d48 #f16c7f #ea94bb #ffcee0 #b384bb #000000
Default: #ffffff.
Possible values: <= 1
Opacity level of the fill color.
Possible values: any number between 0 and 1, where:
0.0: the background color is completely transparent or invisible.
1.0: the background color is completely opaque or solid.
Default: 1.0 if fillColor is provided, 0.0 if fillColor is not provided.
Possible values: [arial, abril_fatface, bangers, eb_garamond, georgia, graduate, gravitas_one, fredoka_one, nixie_one, open_sans, permanent_marker, pt_sans, pt_sans_narrow, pt_serif, rammetto_one, roboto, roboto_condensed, roboto_slab, caveat, times_new_roman, titan_one, lemon_tuesday, roboto_mono, noto_sans, plex_sans, plex_serif, plex_mono, spoof, tiempos_text, formular]
Defines the font type for the text in the shape item.
Default: arial.
Possible values: >= 10 and <= 288
Defines the font size, in dp, for the text on the shape.
Default: 14.
Possible values: [left, right, center]
Defines how the sticky note text is horizontally aligned.
Default: center.
Possible values: [top, middle, bottom]
Defines how the sticky note text is vertically aligned.
Default: top.
Possible values: [gray, light_yellow, yellow, orange, light_green, green, dark_green, cyan, light_pink, pink, violet, red, light_blue, blue, dark_blue, black]
Fill color for the sticky note.
Default: light_yellow.
Possible values: [left, right, center]
Defines how the sticky note text is horizontally aligned.
Default: center.
Possible values: [top, middle, bottom]
Defines how the sticky note text is vertically aligned.
Default: top.
Hex value representing the color for the text within the text item.
Default: #1a1a1a.
Background color of the text item.
Default: #ffffff.
Possible values: <= 1
Opacity level of the background color.
Possible values: any number between 0.0 and 1.0, where:
0.0: the background color is completely transparent or invisible.
1.0: the background color is completely opaque or solid.
Default: 1.0 if fillColor is provided, 0.0 if fillColor is not provided.
Possible values: [arial, abril_fatface, bangers, eb_garamond, georgia, graduate, gravitas_one, fredoka_one, nixie_one, open_sans, permanent_marker, pt_sans, pt_sans_narrow, pt_serif, rammetto_one, roboto, roboto_condensed, roboto_slab, caveat, times_new_roman, titan_one, lemon_tuesday, roboto_mono, noto_sans, plex_sans, plex_serif, plex_mono, spoof, tiempos_text, formular]
Font type for the text in the text item.
Default: arial.
Possible values: >= 1
Font size, in dp.
Default: 14.
Possible values: [left, right, center]
Horizontal alignment for the item's content.
Default: center.
position
object
Contains information about the item's position on the board, such as its x coordinate, y coordinate, and the origin of the x and y coordinates.
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-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.
geometry
object
Contains geometrical information about the item, such as its width or height.
Height of the item, in pixels.
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 of the item, in pixels.
parent
object
Contains information about the parent frame for the item.
Unique identifier (ID) of the parent frame for the item.
Responses
- 201
- 400
- 429
Items created
- application/json
- Schema
- Example (from schema)
Schema
Array [
- AppCardDataResponse
- CardData
- DocumentDataResponse
- EmbedDataResponse
- ImageDataResponse
- ShapeData
- StickyNoteData
- TextData
Array [
]
- AppCardStyle
- CardStyle
- ShapeStyle
- StickyNoteStyle
- TextStyle
]
data
object[]
required
Contains the result data.
Unique identifier (ID) of an item.
data
object
Contains information about item-specific data.
oneOf
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.
Hex value representing the color that fills the background area of the preview field, when it's displayed on the app card.
Possible values: [round, square]
Default value: round
The shape of the icon on the preview field.
A valid URL pointing to an image available online. The transport protocol must be HTTPS. Possible image file formats: JPG/JPEG, PNG, SVG.
Hex value representing the color of the text string assigned to value.
A short text displayed in a tooltip when clicking or hovering over the preview field.
The actual data value of the custom field. It can be any type of information that you want to convey.
Defines whether the card is owned by the application making the call.
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.
A short text header to identify the app card.
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.
A short text description to add context about the card.
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.
A short text header for the card.
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.
A short text header to identify the document.
Type of the embedded item's content.
Short description of the embedded item.
HTML code of the embedded item.
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.
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.
Name of the content's provider.
Url of the content's provider.
Title of the embedded item.
A valid URL pointing to the content resource that you want to embed in the board. Possible transport protocols: HTTP, HTTPS.
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.
A short text header to identify the image.
The text you want to display on the shape.
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.
The actual text (content) that appears in the sticky note item.
Possible values: [square, rectangle]
Default value: square
Defines the geometric shape of the sticky note and aspect ratio for its dimensions.
The actual text (content) that appears in the text item.
style
object
Contains information about item-specific styles.
oneOf
Hex value of the border color of the app card.
Default: #2d9bf0.
Hex value of the border color of the card.
Default: #2d9bf0.
Defines the color of the border of the shape.
Default: #1a1a1a (dark gray).
Possible values: <= 1
Defines the opacity level of the shape border.
Possible values: any number between 0.0 and 1.0, where:
0.0: the background color is completely transparent or invisible
1.0: the background color is completely opaque or solid
Default: 1.0 (solid color).
Possible values: [normal, dotted, dashed]
Defines the style used to represent the border of the shape.
Default: normal.
Possible values: >= 1 and <= 24
Defines the thickness of the shape border, in dp.
Default: 2.0.
Hex value representing the color for the text within the shape item.
Default: #1a1a1a.
Fill color for the shape.
Hex values: #f5f6f8 #d5f692 #d0e17a #93d275 #67c6c0 #23bfe7 #a6ccf5 #7b92ff #fff9b1 #f5d128 #ff9d48 #f16c7f #ea94bb #ffcee0 #b384bb #000000
Default: #ffffff.
Possible values: <= 1
Opacity level of the fill color.
Possible values: any number between 0 and 1, where:
0.0: the background color is completely transparent or invisible.
1.0: the background color is completely opaque or solid.
Default: 1.0 if fillColor is provided, 0.0 if fillColor is not provided.
Possible values: [arial, abril_fatface, bangers, eb_garamond, georgia, graduate, gravitas_one, fredoka_one, nixie_one, open_sans, permanent_marker, pt_sans, pt_sans_narrow, pt_serif, rammetto_one, roboto, roboto_condensed, roboto_slab, caveat, times_new_roman, titan_one, lemon_tuesday, roboto_mono, noto_sans, plex_sans, plex_serif, plex_mono, spoof, tiempos_text, formular]
Defines the font type for the text in the shape item.
Default: arial.
Possible values: >= 10 and <= 288
Defines the font size, in dp, for the text on the shape.
Default: 14.
Possible values: [left, right, center]
Defines how the sticky note text is horizontally aligned.
Default: center.
Possible values: [top, middle, bottom]
Defines how the sticky note text is vertically aligned.
Default: top.
Possible values: [gray, light_yellow, yellow, orange, light_green, green, dark_green, cyan, light_pink, pink, violet, red, light_blue, blue, dark_blue, black]
Fill color for the sticky note.
Default: light_yellow.
Possible values: [left, right, center]
Defines how the sticky note text is horizontally aligned.
Default: center.
Possible values: [top, middle, bottom]
Defines how the sticky note text is vertically aligned.
Default: top.
Hex value representing the color for the text within the text item.
Default: #1a1a1a.
Background color of the text item.
Default: #ffffff.
Possible values: <= 1
Opacity level of the background color.
Possible values: any number between 0.0 and 1.0, where:
0.0: the background color is completely transparent or invisible.
1.0: the background color is completely opaque or solid.
Default: 1.0 if fillColor is provided, 0.0 if fillColor is not provided.
Possible values: [arial, abril_fatface, bangers, eb_garamond, georgia, graduate, gravitas_one, fredoka_one, nixie_one, open_sans, permanent_marker, pt_sans, pt_sans_narrow, pt_serif, rammetto_one, roboto, roboto_condensed, roboto_slab, caveat, times_new_roman, titan_one, lemon_tuesday, roboto_mono, noto_sans, plex_sans, plex_serif, plex_mono, spoof, tiempos_text, formular]
Font type for the text in the text item.
Default: arial.
Possible values: >= 1
Font size, in dp.
Default: 14.
Possible values: [left, right, center]
Horizontal alignment for the item's content.
Default: center.
position
object
Contains location information about the item, such as its x coordinate, y coordinate, and the origin of the x and y coordinates.
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.
Possible values: [canvas_center, parent_top_left]
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-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.
geometry
object
Contains geometrical information about the item, such as its width or height.
Height of the item, in pixels.
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 of the item, in pixels.
parent
object
Contains information about the parent this item attached to.
Unique identifier (ID) of a container item.
links
object
Contains applicable links for the current object.
Link to obtain more information about the current object.
createdBy
object
Contains information about the user who created the item.
Unique identifier (ID) of the user.
Indicates the type of object returned. In this case, type returns user.
Date and time when the item was created.
Format: UTC, adheres to ISO 8601, includes a trailing Z offset.
modifiedBy
object
Contains information about the user who last modified the item.
Unique identifier (ID) of the user.
Indicates the type of object returned. In this case, type returns user.
Date and time when the item was last modified.
Format: UTC, adheres to ISO 8601, includes a trailing Z offset.
links
object
required
Contains applicable links for the current object.
Link to obtain more information about the current object.
Type of the object.
{
"data": [
{
"id": "3458764517517819000",
"data": {},
"style": {},
"position": {
"origin": "center",
"relativeTo": "canvas_center",
"x": 100,
"y": 100
},
"geometry": {
"height": 60,
"rotation": 0,
"width": 320
},
"parent": {
"id": "3458764517517819001",
"links": {
"self": "http://api.miro.com/v2/boards/o9J_koQspF4=/object_type/3074457349143649487"
}
},
"isSupported": true,
"createdBy": {
"id": "3458764517517852417",
"type": "user"
},
"createdAt": "2022-03-30T17:26:50.000Z",
"modifiedBy": {
"id": "3458764517517852417",
"type": "user"
},
"modifiedAt": "2022-03-30T17:26:50.000Z",
"links": {
"self": "http://api.miro.com/v2/boards/o9J_koQspF4=/object_type/3074457349143649487"
}
}
],
"type": "fixed-list"
}
Malformed request
- application/json
- Schema
- Example (from schema)
Schema
Array [
]
Type of the error
Code of the error
Description of the error
context
object
fields
object[]
0-based index indicating a sub-operations from the input that caused a failure followed by parameter name
Description of the sub-operation related error
Status code of the error
{
"type": "error",
"code": 2.074,
"message": "Error message",
"context": {
"fields": [
{
"field": "string",
"message": "Invalid parameters",
"context": {}
}
]
},
"status": 400
}
Too many requests
- application/json
- Schema
- Example (from schema)
Schema
Code of the error
Description of the error
Status code of the error
Type of entity that is returned.
{
"code": 2.074,
"message": "Error message",
"context": {},
"status": 400,
"type": "error"
}