openapi: 3.0.1
info:
title: Miro Developer Platform AI Interaction Logs Text 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: Text items
paths:
/v2/boards/{board_id}/texts:
post:
description: Adds a text item to 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: create-text-item
parameters:
- description: Unique identifier (ID) of the board where you want to create the item.
in: path
name: board_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TextCreateRequest'
required: true
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/TextItem'
description: Text item created
'400':
$ref: '#/components/responses/400'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
summary: Create text item
tags:
- Text items
/v2/boards/{board_id}/texts/{item_id}:
get:
description: Retrieves information for a specific text 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-text-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/TextItem'
description: Text item retrieved
'400':
$ref: '#/components/responses/400'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
summary: Get text item
tags:
- Text items
patch:
description: Updates a text item on a board based on the data and style properties provided in the request body.<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-text-item
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/TextUpdateRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/TextItem'
description: Text item updated
'400':
$ref: '#/components/responses/400'
'404':
$ref: '#/components/responses/404'
'409':
$ref: '#/components/responses/409'
'429':
$ref: '#/components/responses/429'
summary: Update text item
tags:
- Text items
delete:
description: Deletes a text item from the 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-text-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: Text item deleted
'400':
$ref: '#/components/responses/400'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
summary: Delete text item
tags:
- Text items
components:
schemas:
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
TextCreateRequest:
type: object
properties:
data:
$ref: '#/components/schemas/TextData'
style:
$ref: '#/components/schemas/TextStyle'
position:
$ref: '#/components/schemas/PositionChange'
geometry:
$ref: '#/components/schemas/WidthOnlyAdjustableGeometry'
parent:
$ref: '#/components/schemas/Parent'
required:
- data
Parent:
type: object
description: Contains information about the parent frame for the item.
properties:
id:
type: string
format: int64
description: Unique identifier (ID) of the parent frame for the item.
example: '3074457362577955300'
UpdateTextStyle:
type: object
description: Contains information about the style of a text item, such as the fill color or font family.
properties:
color:
type: string
description: Hex value representing the color for the text within the text item.
example: '#1a1a1a'
fillColor:
type: string
description: Background color of the text item.
example: '#e6e6e6'
fillOpacity:
type: string
description: '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'
maximum: 1
minimum: 0
fontFamily:
type: string
description: Font type for the text in the text item.
enum:
- 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
fontSize:
type: string
description: Font size, in dp.
minimum: 1
textAlign:
type: string
description: Horizontal alignment for the item's content.
enum:
- left
- right
- center
TextStyle:
type: object
description: Contains information about the style of a text item, such as the fill color or font family.
properties:
color:
type: string
description: 'Hex value representing the color for the text within the text item.
Default: `#1a1a1a`.'
example: '#1a1a1a'
fillColor:
type: string
description: 'Background color of the text item.
Default: `#ffffff`.'
example: '#e6e6e6'
fillOpacity:
type: string
description: '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.'
maximum: 1
minimum: 0
fontFamily:
type: string
description: 'Font type for the text in the text item.
Default: `arial`.'
enum:
- 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
fontSize:
type: string
description: 'Font size, in dp.
Default: `14`.'
minimum: 1
textAlign:
type: string
description: 'Horizontal alignment for the item''s content.
Default: `center.`'
enum:
- left
- right
- center
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
SelfLink:
type: object
description: Contains applicable links for the current object.
properties:
self:
type: string
description: Link to obtain more information about the current object.
example: http://api.miro.com/v2/boards/o9J_koQspF4=/object_type/3074457349143649487
PositionChange:
type: object
description: 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.
properties:
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.'
default: 0
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.'
default: 0
example: 100
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
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
TextItem:
type: object
properties:
id:
type: string
description: Unique identifier (ID) of an item.
example: '3458764517517819000'
data:
$ref: '#/components/schemas/TextData'
style:
$ref: '#/components/schemas/TextStyle'
position:
$ref: '#/components/schemas/Position'
geometry:
$ref: '#/components/schemas/Geometry'
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'
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/ParentLinksEnvelope'
links:
$ref: '#/components/schemas/WidgetLinks'
type:
type: string
description: Type of item that is returned.
example: text
required:
- id
- type
WidgetLinks:
type: object
description: Contains applicable links for the item.
properties:
related:
type: string
description: Link to obtain information about the child items related to the frame.
example: http://api.miro.com/v2/boards/o9J_koQspF4=/items?parent_item_id=307445734914369434&limit=10&cursor=
self:
type: string
description: Link to obtain information about the current item.
example: http://api.miro.com/v2/boards/o9J_koQspF4=/item/3074457349143649487
WidthOnlyAdjustableGeometry:
type: object
description: Contains geometrical information about the item, such as its width or rotation. You can only specify the width of the text item as the height is dynamically updated based on the content.
properties:
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.
The minimum `width` of a `text` widget is relative to the font size of the `text` widget. The width must be at least 1.7 times wider than the font size.
For example, if the font size of the `text` item is `14`, the minimum `width` is `24`.'
TextUpdateRequest:
type: object
properties:
data:
$ref: '#/components/schemas/TextData'
style:
$ref: '#/components/schemas/UpdateTextStyle'
position:
$ref: '#/components/schemas/PositionChange'
geometry:
$ref: '#/components/schemas/WidthOnlyAdjustableGeometry'
parent:
$ref: '#/components/schemas/Parent'
ParentLinksEnvelope:
type: object
description: Contains information about the parent frame for the item.
properties:
id:
type: string
format: int64
description: Unique identifier (ID) of the parent frame for the item.
example: '3074457362577955300'
links:
$ref: '#/components/schemas/SelfLink'
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
securitySchemes:
oAuth2AuthCode:
type: oauth2
description: For more information, see https://developers.miro.com/reference/authorization-flow-for-expiring-tokens
flows:
authorizationCode:
authorizationUrl: https://miro.com/oauth/authorize
tokenUrl: https://api.miro.com/v1/oauth/token
scopes:
boards:read: Retrieve information about boards, board members, or items
boards:write: Create, update, or delete boards, board members, or items
microphone:listen: Access a user's microphone to record audio in an iFrame
screen:record: Access a user's screen to record it in an iFrame
webcam:record: Allows an iFrame to access a user's camera to record video
organizations:read: Read information about the organization, such as name, plan, number of licenses, organization settings, or organization members.
organizations:teams:read: Read team information, such as the list of teams, team settings, team members, for an organization.
organizations:teams:write: Create or delete teams, update team information, team settings, team members, for an organization.
x-settings:
publish: true