How to Integrate Retool with Miro

Miro's REST API requires creating a developer app in the Miro dashboard to obtain credentials. Navigate to miro.com/app/settings/user-profile/apps and click Create new app. Enter an app name (e.g., 'Retool Integration'), select the team this app will have access to, and click Create app. In the app settings, you will see two authentication options: Option 1 — Static App Token (simplest for development): In the app settings page, scroll to the 'App token' section and copy the token. This is a long-lived token that grants access to boards in the team the app is installed on. It's the fastest option for getting started but is less secure than OAuth 2.0 because it doesn't expire automatically. Option 2 — OAuth 2.0 (recommended for production): Configure the OAuth 2.0 redirect URL in the app settings (e.g., https://retool.com as a placeholder for initial setup). Miro will provide a client_id and client_secret. Implement the authorization code flow to get an access_token and refresh_token. The access_token expires after 1 hour, so production setups need token refresh handling. For initial development, use the static App Token — it works immediately without going through the OAuth flow. Note your app token; you will use it as the Bearer token in the Retool resource configuration. Also find the Board IDs for boards you want to query: open a Miro board and copy the ID from the URL (the part after /board/ and before any query parameters, which looks like uXjVN8Xxxxxxxx=). Store these in a Retool Configuration Variable or as selectable constants in your app.

Navigate to the Resources tab in Retool and click Add Resource. Select REST API from the resource type list. Configure the resource: - Name: 'Miro API' - Base URL: https://api.miro.com/v2 For authentication, select Bearer Token from the Auth dropdown and enter your Miro app token (or OAuth access token). Add a default header for all requests: - Key: Accept - Value: application/json Click Save Changes. Verify the resource by creating a test query: - Method: GET - Path: /boards - URL Parameters: limit: 10 Run the query. A successful response returns a list of Miro boards accessible to the token, including each board's id, name, description, and team_id. If you see a 401 error, the token is incorrect or has insufficient permissions. If the boards array is empty, the token's associated team has no boards or the app has not been installed on any team. Note the format of board IDs in the response — they contain URL-unsafe characters (= signs) that need to be URL-encoded as %3D when used in URL path segments. When using a board ID in a path (e.g., /boards/{board_id}/items), ensure the ID is properly encoded.

The Miro API's /boards/{board_id}/items endpoint returns all items on a board, with optional filtering by item type. For retrospective and brainstorming boards, sticky notes are the primary content type. Create a new query using the Miro API resource: - Method: GET - Path: /boards/{{ encodeURIComponent(boardIdInput.value) }}/items - URL Parameters: - type: sticky_note (filter to only sticky notes) - limit: 50 - cursor: {{ pageState.cursor || '' }} (for pagination) The response returns an items array where each sticky_note object has: id, type, data (containing content as HTML string), style (fillColor, textColor, fontSize), geometry (x, y, width, height relative positions), and createdAt/modifiedAt timestamps. Note that Miro's item content is returned as an HTML string (e.g., '<p>Action item: Fix login bug</p>'). Your transformer needs to strip HTML tags to extract the plain text. Write a JavaScript transformer that strips HTML from content, extracts the plain text, formats the position data (x, y coordinates normalized to the board), and returns an array of cleaned sticky note objects. This cleaned array is what you bind to the Retool Table.

1// JavaScript transformer for Miro sticky note items
2const items = data?.data || [];
3
4// Helper to strip HTML tags from Miro item content
5function stripHtml(html) {
6  if (!html) return '';
7  return html
8    .replace(/<br\s*\/?>/gi, '\n')
9    .replace(/<\/p>/gi, '\n')
10    .replace(/<[^>]+>/g, '')
11    .replace(/&amp;/g, '&')
12    .replace(/&lt;/g, '<')
13    .replace(/&gt;/g, '>')
14    .replace(/&quot;/g, '"')
15    .replace(/&#39;/g, "'")
16    .trim();
17}
18
19return items.map(item => ({
20  id: item.id,
21  type: item.type,
22  content: stripHtml(item.data?.content || ''),
23  color: item.style?.fillColor || '#fff9b1', // default Miro yellow
24  x_position: Math.round(item.position?.x || 0),
25  y_position: Math.round(item.position?.y || 0),
26  width: Math.round(item.geometry?.width || 200),
27  height: Math.round(item.geometry?.height || 200),
28  created_at: item.createdAt
29    ? new Date(item.createdAt).toLocaleDateString()
30    : '',
31  modified_at: item.modifiedAt
32    ? new Date(item.modifiedAt).toLocaleDateString()
33    : ''
34}));

For retrospective boards where columns are implicit (defined by position rather than explicit frames), use the x-coordinate of each sticky note to determine which column it belongs to. Miro coordinates use a center-origin system where items to the left of center have negative x values and items to the right have positive x values. Create a second transformer (or extend the first) that analyzes the position of sticky notes and assigns category labels. You need to know the approximate x-coordinate boundaries of each column — open the Miro board, select items in each column, and note their x-coordinates from the selection panel or URL parameters. Alternatively, query for frame items (type: frame) first to get the named frames on the board, then determine which sticky notes fall within each frame's bounding box based on coordinates. Frames in Miro represent sections, swimlanes, or columns — they have x, y, width, and height in the geometry object. Write a JavaScript query (no resource required) that combines the frame positions from the frames query and the sticky note positions from the items query, assigns each sticky note to the frame it falls within, and outputs the categorized list. Bind this combined output to the Retool Table with a category column showing the frame name (column label). Add a Chart component showing a count of sticky notes per category. This gives a quick visual summary of retro sentiment — how many items in each column — before drilling into the full list.

1// JavaScript query to join sticky notes with frame categories
2// Assumes framesQuery and stickyNotesQuery are both resolved
3
4const frames = framesQuery.data || [];
5const stickyNotes = stickyNotesQuery.data || [];
6
7// Each frame has: id, content (name), x_position, y_position, width, height
8// Determine if a sticky note's center falls within a frame's bounding box
9function getCategory(note, frames) {
10  const noteCenterX = note.x_position;
11  const noteCenterY = note.y_position;
12
13  for (const frame of frames) {
14    const frameLeft = frame.x_position - frame.width / 2;
15    const frameRight = frame.x_position + frame.width / 2;
16    const frameTop = frame.y_position - frame.height / 2;
17    const frameBottom = frame.y_position + frame.height / 2;
18
19    if (noteCenterX >= frameLeft && noteCenterX <= frameRight &&
20        noteCenterY >= frameTop && noteCenterY <= frameBottom) {
21      return frame.content || 'Unnamed Section';
22    }
23  }
24  return 'Uncategorized';
25}
26
27return stickyNotes.map(note => ({
28  ...note,
29  category: getCategory(note, frames)
30}));

For a more comprehensive board analysis tool, query all item types simultaneously and build a content summary that categorizes the board by item type, total count, and content statistics. This is useful for boards used in user research synthesis or competitive analysis where teams mix sticky notes, text blocks, images, and cards. Create queries for each relevant item type using the Miro API resource: - One query for sticky_note items - One query for text items (type: text) - One query for card items (type: card) — cards have structured data with title, description, and optional assignee Set all three queries to run in parallel when the board ID is entered. Use a JavaScript query that combines the results: count items by type, extract text content from each type, and build a summary object. Display the summary as a set of Stat components (total sticky notes, total text items, total cards) and a comprehensive Table showing all extractable text content across item types. For card items specifically, extract the title and description separately since Miro cards have structured fields unlike the HTML-content sticky notes. This combined view gives teams a searchable archive of all whiteboard content from a specific board — useful for finding specific keywords or themes across mixed-format boards.

1// JavaScript transformer for Miro card items (different structure from sticky notes)
2const cards = data?.data || [];
3
4function stripHtml(html) {
5  if (!html) return '';
6  return html.replace(/<[^>]+>/g, '').replace(/&amp;/g, '&').trim();
7}
8
9return cards.map(card => ({
10  id: card.id,
11  type: 'card',
12  title: stripHtml(card.data?.title || ''),
13  description: stripHtml(card.data?.description || ''),
14  content: [stripHtml(card.data?.title || ''), stripHtml(card.data?.description || '')]
15    .filter(Boolean).join(' — '),
16  assignee_id: card.data?.assigneeId || null,
17  due_date: card.data?.dueDate
18    ? new Date(card.data.dueDate).toLocaleDateString()
19    : '',
20  tags: (card.tagIds || []).join(', '),
21  x_position: Math.round(card.position?.x || 0),
22  y_position: Math.round(card.position?.y || 0)
23}));