Overview

• Boards page by offset, items by cursor. boards.list takes limit and offset and reports total; items.list and connectors.list take a cursor and return the next one. Members, tags and tags.items page by offset. tags.ofItem returns every tag on the item in one response.
• List rows arrive as data. Miro names every list array data whatever the resource, so each operation renames it after the resource: boards, items, tags, members, connectors. tags.ofItem is the exception and keys them tags.
• Item writes are nested. Miro expects a sticky note’s content and shape under data, its colour under style, and its frame under parent.id. This plugin takes them flat and groups them for you.
• Connectors need two existing items. Both startItemId and endItemId are required and must already be on the board; a connector cannot be created against a loose point.
• Tags on items travel in the query. tags.attach and tags.removeFromItem both address /v2/boards/{boardId}/items/{itemId} with tag_id as a query parameter. Each call handles one tag, so attach several by calling it once per tag; an earlier tag stays attached.
• boards.copy is a PUT on the collection with copy_from as a required query parameter, not a body field.
• Scopes. Reads need boards:read, writes need boards:write. A token without the write scope gets 403.
• Rate limits are per minute by tier, and a 429 carries Retry-After; retries are capped at three.
• A 5xx is retried on reads only. A write that answers 5xx may still have been applied, so it is not sent again; check the board before repeating it.

• 40 typed API operations

​

Setup

npm install corsair @corsair-dev/miro better-sqlite3
npm install --save-dev @types/better-sqlite3

yarn add corsair @corsair-dev/miro better-sqlite3
yarn add --dev @types/better-sqlite3

pnpm install corsair @corsair-dev/miro better-sqlite3
pnpm install --save-dev @types/better-sqlite3

bun add corsair @corsair-dev/miro better-sqlite3
bun add --dev @types/better-sqlite3

import Database from 'better-sqlite3';
import { createCorsair } from 'corsair';
import { miro } from '@corsair-dev/miro';

export const corsair = createCorsair({
	plugins: [
		miro(),
	],
	database: new Database('corsair.db'),
	kek: process.env.CORSAIR_KEK!,
	multiTenancy: true,
	hub: {
		projectApiKey: process.env.CORSAIR_API_KEY!,
		signingSecret: process.env.CORSAIR_SIGNING_SECRET!,
	},
});

miro()

const { connectUrl } = await corsair.manage.connect.createLink({
	plugin: 'miro',
	tenantId: 'acme',
});
// redirect the user's browser to connectUrl

​

Example API calls

const tenant = corsair.withTenant('acme');
await tenant.miro.api.boards.list({ limit: 10 });

const tenant = corsair.withTenant('acme');
await tenant.miro.api.stickyNotes.create({ boardId: 'uXjVK1abcd=', content: 'Ship the roadmap' });

​

What’s next