Create shape item
POST/v2/boards/:board_id/shapes
Adds a shape item to a board.
Required scope
boards:writeRate limiting
Level 2Request
Path Parameters
Unique identifier (ID) of the board where you want to create the item.
- application/json
Body
required
- flow_chart_or
- flow_chart_summing_junction
- 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
- flow_chart_connector
- flow_chart_magnetic_disk
- flow_chart_input_output
- flow_chart_decision
- flow_chart_delay
- flow_chart_display
- flow_chart_document
- flow_chart_magnetic_drum
- flow_chart_internal_storage
- flow_chart_manual_input
- flow_chart_manual_operation
- flow_chart_merge
- flow_chart_multidocuments
- flow_chart_note_curly_left
- flow_chart_note_curly_right
- flow_chart_note_square
- flow_chart_offpage_connector
- flow_chart_or
- flow_chart_predefined_process_2
- flow_chart_preparation
- flow_chart_process
- flow_chart_online_storage
- flow_chart_summing_junction
- flow_chart_terminator
data
object
Contains shape item data, such as the content or the type of the shape.
The text you want to display on the shape.
Not supported for shapes:
Default value: rectangle
Defines the geometric shape of the item when it is rendered on the board.
Basic shapes
Flowchart shapes
style
object
Contains information about the shape style, such as the border color or opacity.
All properties in style object are supported for shape types aren't listed below.
| Shape type | Unsupported properties |
|---|---|
| flow_chart_or | fontSize, fontFamily, color, textAlign, textAlignVertical |
| flow_chart_summing_junction | fontSize, fontFamily, color, textAlign, textAlignVertical |
| flow_chart_note_curly_left | fillColor, fillOpacity |
| flow_chart_note_curly_right | fillColor, fillOpacity |
| flow_chart_note_square | fillColor, fillOpacity |
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: Flowchart shapes: 1.0. Basic shapes: 1.0 if fillColor provided, 0.0 if no fillColor 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, unknown]
Defines how the shape text is horizontally aligned.
Default:
Flowchart shapes: center.
Basic shapes: left.
unknown is returned for unsupported shapes.
Possible values: [top, middle, bottom, unknown]
Defines how the shape text is vertically aligned.
Default:
Flowchart shapes: middle.
Basic shapes: top.
unknown is returned for unsupported shapes.
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
- 404
- 429
Shape item created
- application/json
- Schema
- Example (from schema)
Schema
- flow_chart_or
- flow_chart_summing_junction
- 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
- flow_chart_connector
- flow_chart_magnetic_disk
- flow_chart_input_output
- flow_chart_decision
- flow_chart_delay
- flow_chart_display
- flow_chart_document
- flow_chart_magnetic_drum
- flow_chart_internal_storage
- flow_chart_manual_input
- flow_chart_manual_operation
- flow_chart_merge
- flow_chart_multidocuments
- flow_chart_note_curly_left
- flow_chart_note_curly_right
- flow_chart_note_square
- flow_chart_offpage_connector
- flow_chart_or
- flow_chart_predefined_process_2
- flow_chart_preparation
- flow_chart_process
- flow_chart_online_storage
- flow_chart_summing_junction
- flow_chart_terminator
Unique identifier (ID) of an item.
data
object
Contains shape item data, such as the content or the type of the shape.
The text you want to display on the shape.
Not supported for shapes:
Default value: rectangle
Defines the geometric shape of the item when it is rendered on the board.
Basic shapes
Flowchart shapes
style
object
Contains information about the shape style, such as the border color or opacity.
All properties in style object are supported for shape types aren't listed below.
| Shape type | Unsupported properties |
|---|---|
| flow_chart_or | fontSize, fontFamily, color, textAlign, textAlignVertical |
| flow_chart_summing_junction | fontSize, fontFamily, color, textAlign, textAlignVertical |
| flow_chart_note_curly_left | fillColor, fillOpacity |
| flow_chart_note_curly_right | fillColor, fillOpacity |
| flow_chart_note_square | fillColor, fillOpacity |
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: Flowchart shapes: 1.0. Basic shapes: 1.0 if fillColor provided, 0.0 if no fillColor 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, unknown]
Defines how the shape text is horizontally aligned.
Default:
Flowchart shapes: center.
Basic shapes: left.
unknown is returned for unsupported shapes.
Possible values: [top, middle, bottom, unknown]
Defines how the shape text is vertically aligned.
Default:
Flowchart shapes: middle.
Basic shapes: top.
unknown is returned for unsupported shapes.
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.
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.
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.
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.
parent
object
Contains information about the parent frame for the item.
Unique identifier (ID) of the parent frame for the item.
links
object
Contains applicable links for the current object.
Link to obtain more information about the current object.
links
object
Contains applicable links for the item.
Link to obtain information about the child items related to the frame.
Link to obtain information about the current item.
Type of item that is returned.
{
"id": "3458764517517819000",
"data": {
"content": "Hello",
"shape": "rectangle"
},
"style": {
"borderColor": "string",
"borderOpacity": "string",
"borderStyle": "normal",
"borderWidth": "string",
"color": "#1a1a1a",
"fillColor": "#8fd14f",
"fillOpacity": "string",
"fontFamily": "arial",
"fontSize": "string",
"textAlign": "left",
"textAlignVertical": "top"
},
"position": {
"origin": "center",
"relativeTo": "canvas_center",
"x": 100,
"y": 100
},
"geometry": {
"height": 60,
"rotation": 0,
"width": 320
},
"createdAt": "2022-03-30T17:26:50.000Z",
"createdBy": {
"id": "3458764517517852417",
"type": "user"
},
"modifiedAt": "2022-03-30T17:26:50.000Z",
"modifiedBy": {
"id": "3458764517517852417",
"type": "user"
},
"parent": {
"id": "3074457362577955300",
"links": {
"self": "http://api.miro.com/v2/boards/o9J_koQspF4=/object_type/3074457349143649487"
}
},
"links": {
"related": "http://api.miro.com/v2/boards/o9J_koQspF4=/items?parent_item_id=307445734914369434&limit=10&cursor=",
"self": "http://api.miro.com/v2/boards/o9J_koQspF4=/item/3074457349143649487"
},
"type": "shape"
}
Malformed request
- application/json
- Schema
- Example (from schema)
Schema
Code of the error
Description of the error
Status code of the error
Type of the error
{
"code": "error",
"message": "Error message",
"status": 400,
"type": "error"
}
Not found
- application/json
- Schema
- Example (from schema)
Schema
Code of the error
Description of the error
Status code of the error
Type of the error
{
"code": "error",
"message": "Error message",
"status": 400,
"type": "error"
}
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 the error
{
"code": "error",
"message": "Error message",
"status": 400,
"type": "error"
}