openapi: 3.0.1
info:
title: Miro Developer Platform AI Interaction Logs Items API
version: v2.0
description: '<img src="https://content.pstmn.io/47449ea6-0ef7-4af2-bac1-e58a70e61c58/aW1hZ2UucG5n" width="1685" height="593">
### Miro Developer Platform concepts
- New to the Miro Developer Platform? Interested in learning more about platform concepts??
[Read our introduction page](https://beta.developers.miro.com/docs/introduction) and familiarize yourself with the Miro Developer Platform capabilities in a few minutes.
### Getting started with the Miro REST API
- [Quickstart (video):](https://beta.developers.miro.com/docs/try-out-the-rest-api-in-less-than-3-minutes) try the REST API in less than 3 minutes.
- [Quickstart (article):](https://beta.developers.miro.com/docs/build-your-first-hello-world-app-1) get started and try the REST API in less than 3 minutes.
### Miro REST API tutorials
Check out our how-to articles with step-by-step instructions and code examples so you can:
- [Get started with OAuth 2.0 and Miro](https://beta.developers.miro.com/docs/getting-started-with-oauth)
### Miro App Examples
Clone our [Miro App Examples repository](https://github.com/miroapp/app-examples) to get inspiration, customize, and explore apps built on top of Miro''s Developer Platform 2.0.
'
servers:
- url: https://api.miro.com/
tags:
- name: Items
paths:
/v2/boards/{board_id}/items:
get:
description: '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`.<br/><h3>Required scope</h3> <a target=_blank href=https://developers.miro.com/reference/scopes>boards:read</a> <br/><h3>Rate limiting</h3> <a target=_blank href="/reference/rate-limiting#rate-limit-tiers">Level 2</a><br/>'
operationId: get-items
parameters:
- in: query
name: limit
schema:
type: string
default: '10'
description: The maximum number of results to return per call. If the number of items in the response is greater than the limit specified, the response returns the cursor parameter with a value.
maximum: 50
minimum: 10
- in: query
name: type
schema:
type: string
enum:
- text
- shape
- sticky_note
- image
- document
- card
- app_card
- preview
- frame
- embed
- doc_format
- data_table_format
description: "If you want to get a list of items of a specific type, specify an item type. For example, if you want to retrieve the list of card items, set `type` to `cards`. A `document` is meant for uploaded documents like PDFs while `doc_format` is a Miro structured document similar to a Google Doc.\n Possible values: `app_card`, `card`, `data_table_format`, `document`, `embed`, `frame`, `image`, `shape`, `sticky_note`, `text`, `doc_format`"
- in: query
name: cursor
schema:
type: string
description: 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, set the `cursor` parameter equal to the `cursor` value you received in the response of the previous request.
- description: Unique identifier (ID) of the board for which you want to retrieve the list of available items.
in: path
name: board_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/GenericItemCursorPaged'
description: Items retrieved
'400':
$ref: '#/components/responses/400'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
summary: Get items on board
tags:
- Items
/v2/boards/{board_id}/items/{item_id}:
get:
description: Retrieves information for a specific item on a board.<br/><h3>Required scope</h3> <a target=_blank href=https://developers.miro.com/reference/scopes>boards:read</a> <br/><h3>Rate limiting</h3> <a target=_blank href="/reference/rate-limiting#rate-limit-tiers">Level 1</a><br/>
operationId: get-specific-item
parameters:
- description: Unique identifier (ID) of the board from which you want to retrieve a specific item.
in: path
name: board_id
required: true
schema:
type: string
- description: Unique identifier (ID) of the item that you want to retrieve.
in: path
name: item_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/GenericItem'
description: Item retrieved
'400':
$ref: '#/components/responses/400'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
summary: Get specific item on board
tags:
- Items
patch:
description: Updates the position or the parent of an item on a board.<br/><h3>Required scope</h3> <a target=_blank href=https://developers.miro.com/reference/scopes>boards:write</a> <br/><h3>Rate limiting</h3> <a target=_blank href="/reference/rate-limiting#rate-limit-tiers">Level 2</a><br/>
operationId: update-item-position-or-parent
parameters:
- description: Unique identifier (ID) of the board where you want to update the item.
in: path
name: board_id
required: true
schema:
type: string
- description: Unique identifier (ID) of the item that you want to update.
in: path
name: item_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/GenericItemUpdate'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/GenericItem'
description: Item updated
'400':
$ref: '#/components/responses/400'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
summary: Update item position or parent
tags:
- Items
delete:
description: Deletes an item from a board.<br/><h3>Required scope</h3> <a target=_blank href=https://developers.miro.com/reference/scopes>boards:write</a> <br/><h3>Rate limiting</h3> <a target=_blank href="/reference/rate-limiting#rate-limit-tiers">Level 3</a><br/>
operationId: delete-item
parameters:
- description: Unique identifier (ID) of the board from which you want to delete the item.
in: path
name: board_id
required: true
schema:
type: string
- description: Unique identifier (ID) of the item that you want to delete.
in: path
name: item_id
required: true
schema:
type: string
responses:
'204':
content:
application/json:
schema:
type: object
description: Item deleted
'400':
$ref: '#/components/responses/400'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
summary: Delete item
tags:
- Items
/v2/boards/{board_id_PlatformContainers}/items:
get:
description: Retrieves a list of items within a specific frame. A frame is a parent item and all items within a frame are child items. 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`.<br/><h3>Required scope</h3> <a target=_blank href=https://developers.miro.com/reference/scopes>boards:read</a> <br/><h3>Rate limiting</h3> <a target=_blank href="/reference/rate-limiting#rate-limit-tiers">Level 2</a><br/>
operationId: get-items-within-frame
parameters:
- description: Unique identifier (ID) of the board that contains the frame for which you want to retrieve the list of available items.
in: path
name: board_id_PlatformContainers
required: true
schema:
type: string
- description: ID of the frame for which you want to retrieve the list of available items.
in: query
name: parent_item_id
required: true
schema:
type: string
minimum: 0
- in: query
name: limit
schema:
type: string
default: '10'
description: The maximum number of results to return per call. If the number of items in the response is greater than the limit specified, the response returns the cursor parameter with a value.
maximum: 50
minimum: 10
- in: query
name: type
schema:
type: string
description: "If you want to get a list of items of a specific type, specify an item type. For example, if you want to retrieve the list of card items, set `type` to `cards`.\n Possible values: `app_card`, `card`, `document`, `embed`, `frame`, `image`, `shape`, `sticky_note`, `text`"
- in: query
name: cursor
schema:
type: string
description: 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, set the `cursor` parameter equal to the `cursor` value you received in the response of the previous request.
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/GenericItemCursorPaged'
description: Items within frame retrieved
'400':
content:
application/json:
schema:
type: object
description: Test error obj
properties:
code:
type: string
description: Code of the error
example: error
message:
type: string
description: Description of the error
example: Error message
status:
type: integer
format: int32
description: Status code of the error
example: 400
type:
type: string
description: Type of the error
example: error
description: Malformed request
'404':
content:
application/json:
schema:
type: object
description: Test error obj
properties:
code:
type: string
description: Code of the error
example: error
message:
type: string
description: Description of the error
example: Error message
status:
type: integer
format: int32
description: Status code of the error
example: 400
type:
type: string
description: Type of the error
example: error
description: Not found
'429':
content:
application/json:
schema:
type: object
description: Test error obj
properties:
code:
type: string
description: Code of the error
example: error
message:
type: string
description: Description of the error
example: Error message
status:
type: integer
format: int32
description: Status code of the error
example: 400
type:
type: string
description: Type of the error
example: error
description: Too many requests
summary: Get items within frame
tags:
- Items
/v2-experimental/boards/{board_id}/items/{item_id}:
delete:
description: Deletes an item from a board.<br/><h3>Required scope</h3> <a target=_blank href=https://developers.miro.com/reference/scopes>boards:write</a> <br/><h3>Rate limiting</h3> <a target=_blank href="/reference/rate-limiting#rate-limit-tiers">Level 3</a><br/>
operationId: delete-item-experimental
parameters:
- description: Unique identifier (ID) of the board from which you want to delete the item.
in: path
name: board_id
required: true
schema:
type: string
- description: Unique identifier (ID) of the item that you want to delete.
in: path
name: item_id
required: true
schema:
type: string
responses:
'204':
content:
application/json:
schema:
type: object
description: Item deleted
'400':
content:
application/json:
schema:
type: object
description: Test error obj
properties:
code:
type: string
description: Code of the error
example: error
message:
type: string
description: Description of the error
example: Error message
status:
type: integer
format: int32
description: Status code of the error
example: 400
type:
type: string
description: Type of the error
example: error
description: Malformed request
'404':
content:
application/json:
schema:
type: object
description: Test error obj
properties:
code:
type: string
description: Code of the error
example: error
message:
type: string
description: Description of the error
example: Error message
status:
type: integer
format: int32
description: Status code of the error
example: 400
type:
type: string
description: Type of the error
example: error
description: Not found
'429':
content:
application/json:
schema:
type: object
description: Test error obj
properties:
code:
type: string
description: Code of the error
example: error
message:
type: string
description: Description of the error
example: Error message
status:
type: integer
format: int32
description: Status code of the error
example: 400
type:
type: string
description: Type of the error
example: error
description: Too many requests
summary: Delete item
tags:
- Items
components:
schemas:
FrameData:
type: object
description: Contains frame item data, such as the title, frame type, or frame format.
properties:
format:
type: string
default: custom
description: Only custom frames are supported at the moment.
enum:
- custom
- desktop
- phone
- tablet
- a4
- letter
- ratio_1x1
- ratio_4x3
- ratio_16x9
title:
type: string
description: Title of the frame. This title appears at the top of the frame.
example: Sample frame title
type:
type: string
default: freeform
description: Only free form frames are supported at the moment.
enum:
- freeform
- heap
- grid
- rows
- columns
AppCardData:
type: object
description: Contains app card item data, such as the title, description, or fields.
properties:
description:
type: string
description: A short text description to add context about the app card.
example: Sample app card description
fields:
type: array
description: 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.
items:
$ref: '#/components/schemas/CustomField'
owned:
type: boolean
description: Defines whether the card is owned by the application making the call.
status:
type: string
description: 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`.
enum:
- disconnected
- connected
- disabled
title:
type: string
description: A short text header to identify the app card.
example: sample app card item
DocumentData:
type: object
properties:
documentUrl:
type: string
description: '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`.'
example: https://api.miro.com/v2/boards/uXjVOfjkmAk=/resources/98765467890987654?redirect=false
title:
type: string
description: A short text header to identify the document.
example: Sample document title
createdBy:
type: object
description: Contains information about the user who created the item.
properties:
id:
type: string
description: Unique identifier (ID) of the user.
example: '3458764517517852417'
type:
type: string
description: Indicates the type of object returned. In this case, `type` returns `user`.
example: user
CardData:
type: object
description: Contains card item data, such as the title, description, due date, or assignee ID.
properties:
assigneeId:
type: string
format: int64
description: 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.
example: '3074457362577955300'
description:
type: string
description: A short text description to add context about the card.
example: sample card description
dueDate:
type: string
format: date-time
description: '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](https://en.wikipedia.org/wiki/ISO_8601), includes a [trailing Z offset](https://en.wikipedia.org/wiki/ISO_8601#Coordinated_Universal_Time_(UTC)).'
example: '2023-10-12T22:00:55.000Z'
title:
type: string
description: A short text header for the card.
example: sample card item
GenericItemCursorPaged:
type: object
properties:
data:
type: array
description: Contains the result data.
items:
$ref: '#/components/schemas/GenericItem'
total:
type: integer
format: int64
description: 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:
type: integer
format: int32
description: 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`.<br>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.
example: 1
cursor:
type: string
description: 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.
example: MzQ1ODc2NDUyMjQ5MDA4Mjg5NX4=
limit:
type: integer
format: int32
description: 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.
example: 20
links:
$ref: '#/components/schemas/PageLinks'
CustomField:
type: object
description: 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.
properties:
fillColor:
type: string
description: Hex value representing the color that fills the background area of the preview field, when it's displayed on the app card.
example: '#2fa9e3'
iconShape:
type: string
default: round
description: The shape of the icon on the preview field.
enum:
- round
- square
iconUrl:
type: string
description: 'A valid URL pointing to an image available online.
The transport protocol must be HTTPS.
Possible image file formats: JPG/JPEG, PNG, SVG.'
example: https://cdn-icons-png.flaticon.com/512/5695/5695864.png
textColor:
type: string
description: Hex value representing the color of the text string assigned to `value`.
example: '#1a1a1a'
tooltip:
type: string
description: A short text displayed in a tooltip when clicking or hovering over the preview field.
example: Completion status indicator
value:
type: string
description: 'The actual data value of the custom field.
It can be any type of information that you want to convey.'
example: 'Status: in progress'
Geometry:
type: object
description: Contains geometrical information about the item, such as its width or height.
properties:
height:
type: number
format: double
description: Height of the item, in pixels.
example: 60
rotation:
type: number
format: double
description: 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:
type: number
format: double
description: Width of the item, in pixels.
example: 320
modifiedBy:
type: object
description: Contains information about the user who last modified the item.
properties:
id:
type: string
description: Unique identifier (ID) of the user.
example: '3458764517517852417'
type:
type: string
description: Indicates the type of object returned. In this case, `type` returns `user`.
example: user
GenericItemUpdate:
type: object
properties:
parent:
$ref: '#/components/schemas/Parent'
position:
$ref: '#/components/schemas/PositionChange'
Position:
type: object
description: Contains location information about the item, such as its x coordinate, y coordinate, and the origin of the x and y coordinates.
properties:
origin:
type: string
default: center
description: '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.'
enum:
- center
relativeTo:
type: string
enum:
- canvas_center
- parent_top_left
x:
type: number
format: double
description: '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.'
example: 100
y:
type: number
format: double
description: '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.'
example: 100
GenericItem:
type: object
description: Contains the result data.
properties:
createdAt:
type: string
format: date-time
description: 'Date and time when the item was created. <br>Format: UTC, adheres to [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), includes a [trailing Z offset](https://en.wikipedia.org/wiki/ISO_8601#Coordinated_Universal_Time_(UTC)).'
example: '2022-03-30T17:26:50.000Z'
createdBy:
$ref: '#/components/schemas/createdBy'
data:
$ref: '#/components/schemas/WidgetDataOutput'
geometry:
$ref: '#/components/schemas/Geometry'
id:
type: string
description: Unique identifier (ID) of an item.
example: '3458764517517819000'
modifiedAt:
type: string
format: date-time
description: 'Date and time when the item was last modified. <br>Format: UTC, adheres to [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), includes a [trailing Z offset](https://en.wikipedia.org/wiki/ISO_8601#Coordinated_Universal_Time_(UTC)).'
example: '2022-03-30T17:26:50.000Z'
modifiedBy:
$ref: '#/components/schemas/modifiedBy'
parent:
$ref: '#/components/schemas/Parent'
position:
$ref: '#/components/schemas/Position'
type:
type: string
description: Type of item that is returned.
example: sticky_note
required:
- id
- type
TextData:
type: object
description: Contains text item data, such as the title, content, or description. For more information on the JSON properties, see [Data](https://developers.miro.com/reference/data).
properties:
content:
type: string
description: The actual text (content) that appears in the text item.
example: Hello
required:
- content
EmbedData:
type: object
properties:
contentType:
type: string
description: Type of the embedded item's content.
example: video
description:
type: string
description: Short description of the embedded item.
example: So this is how to organize your life with Miro (a virtual whiteboard) for collaboration, brainstorming, and project management. Students, designers, agile en...
html:
type: string
description: Html code of the embedded item.
example: <iframe class=\"embedly-embed\" src=\"//cdn.embedly.com/widgets/media.html?src=...&display_name=YouTube&url=...&schema=youtube\" width=\"854\" height=\"480\" scrolling=\"no\" title=\"YouTube embed\" frameborder=\"0\" allow=\"autoplay; fullscreen\" allowfullscreen=\"true\"></iframe>
mode:
type: string
description: 'Defines how the content in the embed item is displayed on the board.
`inline`: The embedded content is displ
# --- truncated at 32 KB (41 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/miro/refs/heads/main/openapi/miro-items-api-openapi.yml