Experimental

Experimental

experimental is the namespace that groups and exposes experimental features.
Through miro.board.experimental, apps can access functionality, properties, and methods that are in active development, and therefore subject to change without notice.

⚠️ Warning:

The features exposed through miro.board.experimental are suitable for testing purposes.
Don't deploy these features to a production environment.

Properties

action

readonly CustomActionManagement

Experimental

The action namespace groups a set of methods that enable apps to use custom actions.
The action namespace is currently under the experimental namespace, and it exposes a single method: register():
miro.board.experimental.action.register

You use this method to register a custom action with an app.
The method takes a single argument: an object that defines the custom action.

Methods

get(...)

(filter?: GetFilter) => Promise<Array<Unsupported | Connector | AppCard | Card | Embed | '...'>>

🔒 Requires scope: boards:read

🚦 Rate limit: Level 3

Fetches one or more items, tags or groups from the board.
If you don't pass any arguments, the method returns an array with all the items, groups and tags on the board.

Optionally, you can filter items by id, type, and tags:

Filter by id: pass an item or a tag id to fetch the corresponding item or tag.
If the ID doesn't exist on the board, the method throws an error.
Pass an array of IDs to fetch an array with all the items or tags matching one of the specified IDs.
Filter by type: pass an item type to fetch an array with the items matching the requested type.
Pass an array of types to fetch an array with the items matching one of the specified types.
Filter by tags: pass one or more tags to fetch all the items with the specified tags.
If the tags don't exist on the board, the method returns an empty array.
Pass an array of tags to fetch an array with the items matching one of the specified tags.

ℹ️ Note:

The method cannot return child items inside unsupported parent items, such as User Story Mapping (USM) and Kanban.
If you filter by passing an array of item IDs, item types, or tags, the logical operator between the array members is OR.
The method doesn't have an upper limit as to the maximum amount of items that it can return.
To avoid performance degradation on the board UI, we recommend to not exceed 10000 items per board.

Example:

// Create a tag
const todo = await miro.board.createTag({
  title: 'todo',
  color: 'yellow',
});

// Create another tag
const urgent = await miro.board.createTag({
  title: 'urgent',
  color: 'magenta',
});

// Create a card and attach the tags to it
const card = await miro.board.createCard({
  title: 'card with tags: "todo", "urgent"',
  tagIds: [todo.id, urgent.id],
});

// Create a sticky note and attach the tags to it
const stickyNote = await miro.board.createStickyNote({
  content: 'sticky note with tags: "todo", "urgent"',
  tagIds: [todo.id, urgent.id],
});

// Get the sticky note by passing its ID
await miro.board.get({
  id: stickyNote.id,
});

// Get all items with type: 'card' OR 'sticky_note'
await miro.board.get({
  type: ['card', 'sticky_note'],
});

// Get all 'card' OR 'sticky_note' items with tags: 'todo' OR 'urgent'
await miro.board.get({
  type: ['sticky_note', 'card'],
  tags: ['todo', 'urgent'],
});

select(...)

(filter?: GetFilter) => Promise<Array<Unsupported | Connector | AppCard | Card | Embed | '...'>>

🔒 Requires scope: boards:write

🚦 Rate limit: Level 1

Selects one or more items from the board and returns the list of selected items.
If you don't pass any arguments, the method selects all items and returns them.

Optionally, you can select items by id, type, and tags:

Select by id: pass an item id to select the corresponding item. If the ID doesn't exist on the board, the method throws an error.
Pass an array of IDs to select items with one of the specified IDs.
Select by type: pass an item type to select items matching the requested type.
Pass an array of types to select items matching one of the specified types. If you pass type group, all the elements within the groups will be deselected.
Select by tags: pass one or more tags to select items with the specified tags.
If the tags don't exist on the board, the method returns an empty array.
Pass an array of tags to select items matching one of the specified tags.

ℹ️ Note:

The method cannot return child items inside unsupported parent items, such as User Story Mapping (USM) and Kanban.
If you filter by passing an array of item IDs, item types, or tags, the logical operator between the array members is OR.
The method doesn't have an upper limit as to the maximum amount of items that it can return.
To avoid performance degradation on the board UI, we recommend to not exceed 10000 items per board.

Example:

// Create a tag
const todo = await miro.board.createTag({
  title: 'todo',
  color: 'yellow',
});

// Create another tag
const urgent = await miro.board.createTag({
  title: 'urgent',
  color: 'magenta',
});

// Create a card and attach the tags to it
const card = await miro.board.createCard({
  title: 'card with tags: "todo", "urgent"',
  tagIds: [todo.id, urgent.id],
});

// Create a sticky note and attach the tags to it
const stickyNote = await miro.board.createStickyNote({
  content: 'sticky note with tags: "todo", "urgent"',
  tagIds: [todo.id, urgent.id],
});

// Select the sticky note by passing its ID
await miro.board.select({
  id: stickyNote.id,
});

// Select all items with 'card' OR 'sticky_note' type
await miro.board.select({
  type: ['card', 'sticky_note'],
});

// Select all 'card' OR 'sticky_note' items with 'todo' OR 'urgent' tags
await miro.board.select({
  type: ['sticky_note', 'card'],
  tags: ['todo', 'urgent'],
});

// Select all grouped items in the board
await miro.board.select({
  type: 'group',
});

deselect(...)

(filter?: GetFilter) => Promise<Array<Unsupported | Connector | AppCard | Card | Embed | '...'>>

🔒 Requires scope: boards:write

🚦 Rate limit: Level 1

Deselects one or more items from the board and returns the list of deselected items.
If you don't pass any arguments, the method deselects all items and returns them.

Optionally, you can deselect items by id, type, and tags:

Deselect by id: pass an item id to deselect the corresponding item. If the ID doesn't exist on the board, the method throws an error.
Pass an array of IDs to deselect items with one of the specified IDs.
Deselect by type: pass an item type to deselect items matching the requested type.
Pass an array of types to deselect items matching one of the specified types. If you pass type group, all the elements within the groups will be deselected.
Deselect by tags: pass one or more tags to deselect items with the specified tags.
If the tags don't exist on the board, the method returns an empty array.
Pass an array of tags to deselect items matching one of the specified tags.

ℹ️ Note:

The method cannot return child items inside unsupported parent items, such as User Story Mapping (USM) and Kanban.
If you filter by passing an array of item IDs, item types, or tags, the logical operator between the array members is OR.
The method doesn't have an upper limit as to the maximum amount of items that it can return.
To avoid performance degradation on the board UI, we recommend to not exceed 10000 items per board.

Example:

// Create a tag
const todo = await miro.board.createTag({
  title: 'todo',
  color: 'yellow',
});

// Create another tag
const urgent = await miro.board.createTag({
  title: 'urgent',
  color: 'magenta',
});

// Create a card and attach the tags to it
const card = await miro.board.createCard({
  title: 'card with tags: "todo", "urgent"',
  tagIds: [todo.id, urgent.id],
});

// Create a sticky note and attach the tags to it
const stickyNote = await miro.board.createStickyNote({
  content: 'sticky note with tags: "todo", "urgent"',
  tagIds: [todo.id, urgent.id],
});

// Select all
await miro.board.select();

// Deselect the sticky note by passing its ID
await miro.board.deselect({
  id: stickyNote.id,
});

// Deselect all items with 'card' OR 'sticky_note' type
await miro.board.deselect({
  type: ['card', 'sticky_note'],
});

// Deselect all 'card' OR 'sticky_note' items with 'todo' OR 'urgent' tags
await miro.board.deselect({
  type: ['sticky_note', 'card'],
  tags: ['todo', 'urgent'],
});

// Deselect all grouped items in the board
await miro.board.deselect({
  type: 'group',
});

getSelection(...)

() => Promise<Array<Unsupported | Connector | AppCard | Card | Embed | '...'>>

🔒 Requires scope: boards:read

🚦 Rate limit: Level 3

Fetches the selected items from the board, and it returns them in an array.
If no items are selected on the board, the method returns an empty array.

If the grouped items are selected, the group entity for those items will also be returned.
When individual items within a group are selected with a double-click, the group entity will not be returned as part of this method.

Example:

// Get an array with the selected item(s) and their properties
const selection = await miro.board.getSelection();

console.log(selection);

getVotingResults(...)

() => Promise<Array<VotingResult>>

🔒 Requires scope: boards:read

🚦 Rate limit: Level 1

This method retrieves the results of voting sessions conducted on a specific board. The method does not accept any arguments.

The results of a voting session include:

createdBy: The username and user ID of the user who initiated the voting session.
createdAt: The start date and time of the voting session in UTC, formatted according to ISO 8601 with a trailing Z offset. For example, 2021-05-18T07:59:01Z.
title: The title of the voting session.
results: An array of objects containing:
- itemId: The ID of the item that was voted on.
- count: The total number of votes the item received.

📘
Note

All timestamps are in UTC, regardless of the app's local machine or execution environment settings.

This method is available only on paid plans with access to the voting feature. If the app is installed on a team without access to voting, the method will return an error.

Ensure the app is installed for a team on a paid plan.

Verify that the voting plugin is installed for the team.

Example:

// Retrieve voting session results.
const votingResults = await miro.board.experimental.getVotingResults();

console.log(votingResults);
// Example output:
//
// [
//    {
//        "createdBy": {
//            "userId": "3458764112826546974",
//            "userName": "Ellen Ripley"
//        },
//        "createdAt": "2023-05-23T10:16:10.464Z",
//        "title": "Which option? Save the LV-426 site or nuke it from orbit?",
//        "results": [
//            {
//                "itemId": "3458764513811016840",
//                "count": 2
//            }
//        ]
//    }
// ]

sync(...)

(item: BaseItem) => Promise<void>

🔒 Requires scope: boards:write

sync propagates to the board any changes to item and tag properties.
After updating the properties of an item or a tag, sync it with the board to:

Propagate to the board the changes applied to the item or to the tag.
Make the changes visible on the board.

All board items and tags require sync to make any changes to their properties visible on the board.

For more information and examples, see Update and sync item properties.

createMindmapNode(...)

(props?: MindmapCreateNodeProps) => Promise<MindmapNode>

🔒 Requires scope: boards:write

🚦 Rate limit: 50 * (1 + number_of_children), where `number_of_children` is the number of mindmap children given as input.

Experimental

Creates a mind map item on a board.

There are no required properties to pass while creating a mind map item.
When you create a mind map item without passing any property, the content of the root item is an empty string of type text. You can update the values later.

Example:

// Create mind map root node
const root = await miro.board.experimental.createMindmapNode({
  nodeView: {
    content: '<p>Mind map root node.</p>',
  }
});

console.log(root)

Mind map item:

Mindmap item
Figure 1. Mind map item.

You can also create a mind map tree by passing the children property:

const mindmap = await miro.board.experimental.createMindmapNode({
  nodeView: {
    content: 'Root',
  },
  children: [
    {
      direction: 'start',
      nodeView: {content: 'Child 1'},
    },
    {
      nodeView: {content: 'Child 2'},
      // You can nest as many children as you want
      children: [
        {
          nodeView: {content: 'Child 2 - 1'},
        },
        {
          nodeView: {content: 'Child 2 - 2'},
          children: [
            {
              nodeView: {content: 'Child 2 - 2 - 1'},
            },
          ],
        },
      ],
    },
  ],
});

console.log(mindmap);

Note on default values during creation:

By default, the root node always has node view type of shape
By default, the child nodes always have node view types of text

Properties

action

Methods

get(...)

🔒 Requires scope: boards:read

🚦 Rate limit: Level 3

select(...)

🔒 Requires scope: boards:write

🚦 Rate limit: Level 1

deselect(...)

🔒 Requires scope: boards:write

🚦 Rate limit: Level 1

getSelection(...)

🔒 Requires scope: boards:read

🚦 Rate limit: Level 3

getVotingResults(...)

🔒 Requires scope: boards:read

🚦 Rate limit: Level 1

📘Note

sync(...)

🔒 Requires scope: boards:write

createMindmapNode(...)

🔒 Requires scope: boards:write

🚦 Rate limit: 50 * (1 + number_of_children), where number_of_children is the number of mindmap children given as input.

📘
Note

🚦 Rate limit: 50 * (1 + number_of_children), where `number_of_children` is the number of mindmap children given as input.