---
updatedAt: 2026-03-19T19:37:18.000Z
agentTools:
  projectIndex: https://developers.miro.com/llms.txt
---

# REST API comparison guide

This page outlines the changes in certain data objects, and in how those objects relate to others. For a complete map of each v1 endpoint to its v2 counterpart, check out the [reference guide](https://developers.miro.com/docs/rest-api-reference-guide).

## Authorization

**Note:** This migration does **not** apply to [Miro's OAuth2.0 endpoint](https://developers.miro.com/reference/exchange-authorization-code-with-access-token) (/v1/oauth). It is not part of the required migration and it will continue to support all versions of the Miro REST API.

## Connections

One of the major changes for the v2 REST API is that connections are no longer treated as entities. A `board`, a `user`, and a `team` are all entities, but the relationship between any two of these is determined by the interactions between the objects. Treating the relationship and those interactions as an entity unto itself made the v1 platform unnecessarily complex.

To improve the developer experience for the v2 REST API, we decided to use a more intuitive approach to manage these relationships. Rather than creating and maintaining a special object to represent the connection between two other objects, the objects are now associated through actions, such as inviting a user to a board.

This means that [Board User Connection objects](https://developers.miro.com/v1.0/reference/board-user-connection-object) and [Team User Connection objects](https://developers.miro.com/v1.0/reference/team-user-connection-object) no longer exist. Their endpoints have been replaced in v2 with more intuitive API calls, such as [Share Board](https://developers.miro.com/reference/share-board). For a full list of the v2 equivalent for these endpoints, please see the [reference guide](https://developers.miro.com/docs/rest-api-reference-guide).

## Date and Time

In the v2 REST API, timestamps have changed from the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format (used in the v1 REST API) to the broader [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. These formats are derived from the same basic date-time structure, and both follow the "most-to-least-significant" order, i.e. `[YYYY]-[MM]-[DD]T[HH]:[MM]:[SS]`. For nearly every developer, this change should be unnoticeable.

The significant distinction in this format switch is that time zones must be indicated using the trailing Z format, and can no longer take advantage of the -0 shortcut to indicate that there is no preferred time zone.

## Boards

Working with Board objects in the v2 Miro REST API should feel familiar, as the board object is largely unchanged compared to the v1 REST API.

### Board information

Many of the basic information fields in the board object remain unchanged between v1 and v2. These fields include:

* `type` continues to be `board`
* `id` continues to be the ID used in the board view link
* `name` continues to be the name of the board
* `description` continues to be the description of the board, or an empty string if there is no description set
* `viewLink` continues to be the direct link to open the Miro board

`picture` is no longer included in the board object, and cannot be updated programmatically. Can be retrieved via the [GET Specific Board](https://developers.miro.com/reference/get-specific-board) endpoint in v2.

`createdAt` and `modifiedAt` are mostly unchanged, with the [caveat noted above](https://developers.miro.com/docs/rest-api-comparison-guide#date-and-time).

### User information

The user information contained in a board object remains the same between v1 and v2. A user object is returned for `createdBy`, `modifiedBy`, and `owner`. User objects are [unchanged in v2](https://developers.miro.com/docs/rest-api-comparison-guide#users).

### Board User Connection / Board Member

With the larger initiative to [remove Connections as objects](https://developers.miro.com/docs/rest-api-comparison-guide#connections), the [Board User Connection object](https://developers.miro.com/v1.0/reference/board-user-connection-object) is now represented by a [Board Member object](https://developers.miro.com/reference/board-member-model). The objects themselves are intentionally similar and should be familiar to work with. However, the Board User Connection endpoints are not available in v2, and have been replaced with more intuitive endpoints and interactions. To see the recommended replacement endpoints, please refer to the [REST API Reference Guide](https://developers.miro.com/docs/rest-api-reference-guide#get-board-user-connection).

A v1 board object also includes a `currentUserConnection` value, which is a Board User Connection object. In the v2 REST API, this information is now contained in the `currentUserMembership` field, which is a Board Member object.

For a side-by-side comparison of the Board User Connection and Board Member objects, refer to the table below.

<table>
<tr>
<th style="width:50%">Board User Connection object</th>
<th>Board Member object</th>
</tr>
<tr>
<td>

`type` was set to `board-user-connection`

</td>
<td>

`type` is now set to `board_member`

</td>
</tr>
<tr>
<td>

`role` could be `viewer`, `commenter`, `editor`, or `owner`

</td>
<td>

`role` can still be `viewer`, `commenter`, `editor`, or `owner`

</td>
</tr>
<tr>
<td>

`user` returned a nested User object

</td>
<td>

`name` returns the String object of the user’s name

</td>
</tr>
<tr>
<td>

`id` returned the unique identifier of the connection

</td>
<td>

`id` now returns the unique identifier of the user

</td>
</tr>
<tr>
<td>

Optionally, this object could also contain values for `createdAt`, `createdBy`, `modifiedAt`, and `modifiedBy`.

</td>
<td>

These values are not included in a Board Member object.  
<br>

</td>
</tr>
</table>

### Team information

The team information contained in a board object remains the same between v1 and v2. A nested team object is returned for `team` and continues to contain the same three fields used by the v1 REST API:

* `type` returns `team`
* `name` returns a String object of the team name
* `id` returns the unique identifier for this team

### Sharing and Permissions information

In the v2 REST API, sharing and permissions have been expanded to include more configuration options. A board object continues to include a `sharingPolicy` field, but the [Sharing Policy](https://developers.miro.com/reference/sharing-policy-model) has been expanded in v2. See the table below for a side-by-side comparison of the `sharingPolicy` field across v1 and v2.

<table>
<tr>
<th style="width:50%">

`sharingPolicy` in v1

</th>
<th>

`sharingPolicy` in v2

</th>
</tr>
<tr>
<td>

`sharingPolicy.access` determines the global access level of the board. Can be `private`, `view`, `comment`, or `edit`.

</td>
<td>Unchanged in v2</td>
</tr>
<tr>
<td>

`sharingPolicy.teamAccess` determines the team access level of the board. Can be `private`, `view`, `comment`, or `edit`.

</td>
<td>Unchanged in v2</td>
</tr>
<tr>
<td>Not available in v1</td>
<td>

`sharingPolicy.organizationAccess` determines the organization access level of the board. Can be `private`, `view`, `comment`, or `edit`.

</td>
</tr>
<tr>
<td>Not available in v1</td>
<td>

`inviteToAccountAndBoardLinkAccess` determines a user’s role when inviting that user to the team and the board. Can be `viewer`, `commenter`, `editor`, `coowner`, `owner`, `guest`, or `no_access`.

</td>
</tr>
</table>

In addition to the expanded Sharing Policy, a v2 board object also contains a [Permissions Policy](https://developers.miro.com/reference/permissions-policy-model) and a [Policy](https://developers.miro.com/reference/rest-api-policy-data-model) object that encompasses both the Sharing Policy and the Permissions Policy.

## Widgets / Items

In the Miro REST API v1, the Widget endpoints were polymorphic – meaning that one endpoint was used to interact with all potential widget types. The structure of the call would differ depending on what type of widget you were creating or updating. In the v2 REST API, we have replaced this with an independent endpoint for each type of widget (now called "item") on a Miro board.

The new endpoints should feel familiar to you, as they were designed to mostly follow the structure of the type-specific payloads of the previous widget endpoints. The new endpoints should also feel easier to use, as the expected payload of the call will always be consistent, rather than changing based on the context of the widget type.

This guide will compare the new object structures, but for a full map of v1 endpoint calls to their v2 equivalents, please see the [reference guide](https://developers.miro.com/docs/rest-api-reference-guide#widgets--items). Note that there is no longer a universal item `create` endpoint, but `get`, `update`, and `delete` are still available at the item-level.

### Item

In the v2 REST API, board items are now distinct implementations of [Item](https://developers.miro.com/reference/rest-api-item-model). When comparing a v1 widget object and a v2 item object, many of the basic information fields in the object remain unchanged between v1 and v2. These fields include:

* `type` continues to indicate the type of widget/item. This can be any of 10-15 values, including `shape`, `frame`, etc.
* `id` continues to be the unique identifier of the widget/item
* `createdAt` and `modifiedAt` continue to be timestamps, with the [caveat noted above](https://developers.miro.com/docs/rest-api-comparison-guide#date-and-time)
* `createdBy` and `modifiedBy` continue to be user objects, which are unchanged between v1 and v2.

The v1 widget object also offered `capabilities` and `metadata`. Neither of these are currently available for v2 item objects.

In the v2 REST API, all item objects also include the following fields:

* a [`data` object](https://developers.miro.com/reference/data) that contains properties specific to the item type
* a [`style` object](https://developers.miro.com/reference/style) that contains properties specific to the item type
* a [`geometry` object](https://developers.miro.com/reference/geometry) that contains a `width`, a `height`, and a `rotation` for the item
* a [`position` object](https://developers.miro.com/reference/position) that contains the `x` and `y` coordinates of the center of the item on the board, as well as an `origin` which indicates the point of the item that the x- and y- coordinates refer to.

### Cards

For both the v1 card widget and the v2 card item, the `type` is `card`.  The [card-specific widget properties](https://developers.miro.com/v1.0/reference/card) are reflected in the card item [`data`](https://developers.miro.com/reference/data#a-idcarddataacard-item-data) and [`style`](https://developers.miro.com/reference/style#a-namecardstyleacard-item-style) objects, with some minor changes:

* `title` and `description` are unchanged between v1 and v2, and both continue to be a String resource for the card header and the card description, respectively.
* `date` has been renamed in v2 to `dueDate` and continues to be a date-time object, subject to the previously-mentioned format change.
* In v1, `assignee` was an object that contained a `userId`, while in v2, `assigneeId` is a String that directly references that user ID.
* In v1, the `style` object included a `backgroundColor` property that accepted a String of any valid hex color code. In v2, the `style` property has been renamed to `cardTheme`, but the value of the property continues to be a String of a valid hex color code.

### Lines/Connectors

[Connectors](https://developers.miro.com/reference/create-connector) are available as the equivalent to Lines in the Miro v2 REST API.

While the v1 line widget had a `type` of `line`, the v2 connector has a `type` of `connector`. In addition, the [line-specific widget properties](https://developers.miro.com/v1.0/reference/line) from v1 have changed in the following ways:

* The v1 `startWidget` and `endWidget` properties have been renamed in v2 to `startItem` and `endItem`.
* In v1, the `lineType` property was nested into the `style` object, but in v2, it has been replaced with a top-level `shape` property.
  * In v1, `lineType` supported the following values: `straight`, `orthogonal`, `bezier`, and `sketch`.
  * In v2, we simplified the options and renamed several to improve clarity. As a result, `shape` supports the following values: `straight`, `elbowed`, and `curved`.
* In the `style` object, the following changes have been made:
  * `borderColor` is now `strokeColor`, `borderStyle` is now `strokeStyle`, and `borderWidth` is now `strokeWidth`. These were renamed to improve clarity. The supported values of each property remain unchanged, although `strokeWidth` now supports any integer between 1 and 24.
  * `lineStartType` and `lineEndType` in v1 have been renamed to `startStrokeCap` and `endStrokeCap` in v2. This change was made to improve clarity, by noting the difference between the line of the connector, and the decorative cap at the end. In addition to this, the supported values have changed in v2, with `none` being the only value from v1 that is still available in v2. A full list of the v2 supported values can be found in the documentation.

Finally, the v2 REST API provides full CRUD support for connectors, including an endpoint to [get all of the connectors](https://developers.miro.com/reference/get-connectors) in a board, as well as an endpoint to get a specific connector. This is new in v2.

Please see the [Work with connectors](https://developers.miro.com/docs/work-with-connectors) guide for examples of how to create lines using the current v2 REST API capabilities.

### Shapes

For both the v1 shape widget and the v2 shape item, the `type` is `shape`. The [shape-specific widget properties](https://developers.miro.com/v1.0/reference/shape) are reflected in the shape item [`data`](https://developers.miro.com/reference/data#a-idshapedataashape-item-data) and [`style`](https://developers.miro.com/reference/style#a-nameshapestyleashape-item-style) objects, with some minor changes:

* `text` in the v1 shape widget is now `content` in the v2 shape item `data` object, but both accept a String with simple HTML tag support.
* `shapeType` was nested under `style` in the v1 shape widget, but has moved to the `data` object in the v2 shape item, and was renamed to `shape`. Both fields accepted 21 possible values, of which the following options have been renamed to improve clarity:
  * `rounded_rectangle` is now `round_rectangle`
  * `trapeze` is now `trapezoid`
  * `callout` is now `wedge_round_rectangle_callout`
  * `predefined_process` is now `flow_chart_predefined_process`
  * `barrel` is now `can`
  * `arrow` is now `right_arrow`
  * `arrow_left` is now `left_arrow`
  * `arrow_left_right` is now `left_right_arrow`
  * `brace_left` is now `left_brace`
  * `brace_right` is now `right_brace`
* The `style` object is largely unchanged between the v1 shape widget and the v2 shape item, save for the following:
  * Two properties were renamed for improved clarity
    * `backgroundColor` is now `fillColor`
    * `backgroundOpacity` is now `fillOpacity`
  * `textVerticalAlign` and `textColor` are not currently available in the v2 REST API

### Stickers / Sticky Notes

One major change for sticky notes in v2 is that the item/widget has been renamed. The v1 REST API and Web SDK both referred to sticky notes as "stickers". Since the v1 platform was built, Miro has added support for the more commonly known reaction/emoji stickers. To prevent any confusion, the v2 platform has updated all references to sticky notes to only use the phrase "sticky note".

As a result, the v1 sticky widget had a `type` of `sticker`, while the v2 sticky note item has a `type` of `sticky_note`. Beyond that, the [sticky-note-specific widget properties](https://developers.miro.com/v1.0/reference/sticker) are reflected in the [`data`](https://developers.miro.com/reference/data#a-idstickynotedataasticky-note-item-data) and [`style`](https://developers.miro.com/reference/style#a-namestickynotestyleasticky-note-item-style) objects, with the following changes:

* `text` in the v1 sticker widget is now `content` in the v2 sticky note item `data` object, but both accept a String with simple HTML tag support.
* The v1 sticker `style` object provided support for the following fields:
  * `backgroundColor`, which accepted a String containing one of 12 approved hex color codes, has been renamed to `fillColor` in v2 and now accepts a String containing  one of 16 approved color names.
  * `fontFamily` and `fontSize` are not available in the v2 sticky note item.
  * `textAlign` and `textAlignVertical` are unchanged between v1 and v2.

### Texts

For both the v1 text widget and the v2 text item, the `type` is `text`. The [text-specific widget properties](https://developers.miro.com/v1.0/reference/text) are reflected in the shape item [`data`](https://developers.miro.com/reference/data#a-idtextdataatext-item-data) and [`style`](https://developers.miro.com/reference/style#a-nametextstyleatext-item-style) objects, with some minor changes:

* `text` in the v1 text widget is now `content` in the v2 text item `data` object, but both accept a String with simple HTML tag support.
* The v1 text `style` object supported the following fields:
  * `backgroundColor` and `backgroundOpacity`, which have been renamed to `fillColor` and `fillOpacity`, respectively. The possible values are unchanged between v1 and v2.
  * `fontFamily`, `fontSize`, and `textAlign`, all of which are unchanged between v1 and v2.
  * `borderColor`, `borderOpacity`, `borderWidth`, `textColor`, and `padding`, none of which are currently available for the v2 text item.

### New items in v2

There are several item types that are available in the v2 REST API, which were not supported in the v1 REST API. These may be interesting to you, so we’ve listed them below.

* [App Cards](https://developers.miro.com/reference/data#a-idappcarddataaapp-card-item-data)
* [Documents](https://developers.miro.com/reference/data#a-idimagedataadocument-item-data)
* [Embeds](https://developers.miro.com/reference/data#a-idembeddataaembed-item-data)
* [Frames](https://developers.miro.com/reference/data#a-idframedataaframe-item-data)
* [Images](https://developers.miro.com/reference/data#a-idimagedataaimage-item-data)
* [Previews](https://developers.miro.com/reference/data#a-idpreviewdataapreview-item-data)

In addition, [Tags](https://developers.miro.com/reference/rest-api-tag-data-model) are not considered an Item, but are supported in the v2 REST API.

## Webhooks

The V2 platform introduces Webhooks to complement the existing capabilities in the V2 REST API. Webhooks were not offered in our v1 capabilities.

You can now subscribe to webhooks for various board and item notifications. See [Webhooks](https://developers.miro.com/reference/webhooks-overview) for more details.

## Teams

Team objects and endpoints have undergone several significant changes between the Miro REST API v1 and v2. Most notably, the teams endpoints are now [only available to Enterprise plans](https://developers.miro.com/reference/api-reference#enterprise-plan), meaning that in order to install applications that use the Enterprise APIs, they must be installed into a team with an Enterprise plan.

For developers working with Enterprise applications, the following information is intended to help you migrate your app from v1 to v2. In addition, you might be interested in checking out the new v2 support for [Team Settings](https://developers.miro.com/reference/getteamsettings), [Organizations](https://developers.miro.com/reference/enterprise-get-organization-member), and [Data Classification](https://developers.miro.com/reference/enterprise-dataclassification-team-settings-get).

### Team Object

The information contained in a team object has been simplified for the v2 REST API. There are now only three properties for a v2 team object, although they are each unchanged from their v1 counterpart.

* `type` continues to be `team`
* `name` continues to be a String object of the team name
* `id` continues to be the unique identifier for this team

The following properties of a v1 team object have changed in v2:

* `picture` - App pictures, Board pictures, and Team pictures can no longer be set or changed programmatically. However, a team picture, if set, can still be returned in a team object. Similarly, a Board picture can be retrieved via the [GET Specific Board](https://developers.miro.com/reference/get-specific-board) endpoint in v2.
* `createdAt`, `createdBy`, `modifiedAt`, and `modifiedBy` are no longer included in a team object in the v2 REST API.

### Team User Connection / Team Member

With the larger initiative to [remove Connections as objects](https://developers.miro.com/docs/rest-api-comparison-guide#connections), the Team User Connection object is now represented by a Team Member object. The objects themselves are intentionally similar, and should be familiar to work with. However, the Team User Connection endpoints are not available in v2, and have been replaced with more intuitive endpoints and interactions. To see the recommended replacement endpoints, please refer to the [REST API Reference Guide](https://developers.miro.com/docs/rest-api-reference-guide#get-team-current-user-connection).

For a side-by-side comparison of the Team User Connection and Team Member objects, refer to the table below.

<table>
<tr>
<th style="width:50%">Team User Connection object</th>
<th>Team Member object</th>
</tr>
<tr>
<td>

`type` was set to `team-user-connection`

</td>
<td>

`type` is now set to `team-member`

</td>
<tr>
</tr>
<td>

`id` returned the unique identifier of the connection

</td>
<td>

`memberId` now returns the unique identifier of the team member  
`teamId` returns the unique identifier of the team

</td>
<tr>
</tr>
<td>

`user` returned a nested User object

</td>
<td>This field is not included in the Team Member object.</td>
<tr>
</tr>
<td>

`role` could be `non_team`, `member`, or `admin`

</td>
<td>

`role` was renamed to `userRole` and can be `non_team`, `member`, `admin`, or `team_guest`

</td>
<tr>
</tr>
<td>

`createdAt` and `modifiedAt` returned date-time objects

</td>
<td>These fields are unchanged in v2</td>
<tr>
</tr>
<td>

`createdBy` and `modifiedBy` returned user objects

</td>
<td>

These have been replaced with `createdByUserId` and `modifiedByUserId`, which each return the unique identifier of the user

</td>
</tr>
</table>

## Users

While [User objects](https://developers.miro.com/v1.0/reference/user-object) remain unchanged between the v1 REST API and v2, there are no longer specific endpoints for retrieving those User objects. Instead, user objects can be found nested in the relevant API responses (such as in the `createdBy` and `modifiedBy` fields).

The v2 user object continues to contain the same three fields used by the v1 REST API:

* `type` continues to be `user`
* `name` continues to be a String object of the user’s name
* `id` continues to be the unique identifier for this user

## Authorization Objects

The [Authorization object](https://developers.miro.com/reference/authorization-model) and endpoints remain unchanged between v1 and v2. However, we do plan to stop offering [non-expiring tokens](https://developers.miro.com/reference/authorization-flow-for-expiring-access-tokens) in the near future, and move to the more-secure [expiring access tokens](https://developers.miro.com/reference/oauth-20-authorization-v2) for every app. This change, when finalized, will be backwards-compatible.

For more information on using the OAuth 2.0 authorization code flow, check out the [Getting Started](https://developers.miro.com/docs/getting-started-with-oauth) guide.

## Audit Logs

The [Audit Logs API](https://developers.miro.com/reference/audit-logs) has some minor changes in V2, as described in the following sections.

### Request parameters

* Instead of offset-based pagination, this endpoint now supports cursor-based pagination. Therefore the `offset` parameter is removed and replaced with the `cursor` parameter.
* A new `sorting` parameter has been introduced, which allows you to sort the audit logs in ascending (`ASC`) or descending (`DESC`) order.

### Response body

* The `type` parameter value is now `cursor-list` instead of `list`.
* The `offset` parameter is updated to `cursor`. To retrieve the next set of results of the collection, set the `cursor` parameter in your next request to the appropriate `cursor` value returned in the response.
* The `nextLink` and `prevLink` parameters have been removed.

# Sibling pages

* [Web SDK comparison guide](https://developers.miro.com/miro-ea/docs/web-sdk-comparison-guide.md)
* [Web SDK reference guide](https://developers.miro.com/miro-ea/docs/web-sdk-reference-guide.md)
* [REST API reference guide](https://developers.miro.com/miro-ea/docs/rest-api-reference-guide.md)