Miro REST API Comparison Guide: v1 -> v2

If your app currently uses the Miro REST API v1, it’s time to plan your migration to v2. The Miro Developer Platform 2.0 has completely revamped the REST API, focusing on performance and reliability, as well as the developer experience. This document will outline 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, be sure to check out the reference guide.

Authorization

Note: This migration does not apply to Miro's OAuth2.0 endpoint (/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 and Team User Connection objects no longer exist. Their endpoints have been replaced in v2 with more intuitive API calls, such as Share Board. For a full list of the v2 equivalent for these endpoints, please see the reference guide.

Date and Time

In the v2 REST API, timestamps have changed from the RFC 3339 format (used in the v1 REST API) to the broader 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 set or updated programmatically.

createdAt and modifiedAt are mostly unchanged, with the caveat noted above.

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.

Board User Connection / Board Member

With the larger initiative to remove Connections as objects, the Board User Connection object is now represented by a Board Member object. 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.

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.

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 has been expanded in v2. See the table below for a side-by-side comparison of the sharingPolicy field across v1 and v2.

In addition to the expanded Sharing Policy, a v2 board object also contains a Permissions Policy and a Policy 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. 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. 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
• 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 that contains properties specific to the item type
• a style object that contains properties specific to the item type
• a geometry object that contains a width, a height, and a rotation for the item
• a position object 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 are reflected in the card item data and 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 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 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 in a board, as well as an endpoint to get a specific connector. This is new in v2.

Please see the 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 are reflected in the shape item data and 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 are reflected in the data and 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 are reflected in the shape item data and 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
• Documents
• Embeds
• Frames
• Images
• Previews

In addition, Tags 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 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, 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, Organizations, and Data Classification.

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.
• 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, 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.

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

Users

While User objects 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 and endpoints remain unchanged between v1 and v2. However, we do plan to stop offering non-expiring tokens in the near future, and move to the more-secure expiring access tokens 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 guide.

Audit Logs

The Audit Logs API 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 data parameter has been renamed to content.
• The nextLink and prevLink parameters have been removed.