oEmbed support

Miro boards support the oEmbed standard. It enables programmatically discovering and embedding Miro boards into third-party sites by fetching the board's URL.

oEmbed discovery in a nutshell

The /oembed API endpoint enables programmatically fetching a Miro board that can then be embedded into an external document or tool.

Miro boards support the recommended oEmbed discovery mechanism. Consumers need to comply with the oEmbed standard to retrieve the content, and parse it accordingly:

  1. Parse the HTML, and detect the <link> elements that identify the board as oEmbed-compliant content.
  2. Send a request to the oEmbed API endpoint: this is the value of the href attribute in the <link> elements.
  3. Extract and embed the iframe that the API returns: this is the value of the html field in the JSON or XML response.

📘

When you implement oEmbed, the embedded board is rendered in Live Embed view-only mode.

📣 If you embed a board in view-only mode, we'd like to hear from you: share your thoughts about and your use cases for Miro Live Embed.

oEmbed discovery on Miro pages

Consumers that send a request to the URL of a board that supports the oEmbed standard can expect to find a <link> element in the <head> section of the HTML document.

This is the recommended way to enable consumers to discover oEmbed support for a resource.

📘

Follow redirects

To implement an oEmbed consumer that works with Miro, your code needs to support following HTTP 3xx redirects with cookies.

oEmbed discovery for public boards

To enable embedding a public board (a board that is publicly available and accessible by sharing its link), the <link> element is in the <head> section of the /board/ page.
In this way, when consumers unfurl the URL, they are redirected to the public board URL:

https://miro.com/app/board/<board_ID>/

oEmbed discovery for private boards

To enable embedding a private board (a board that hasn't been shared, and therefore isn't publicly available by sharing its link), the <link> element is in the <head> section of the /signup/ page.
In this way, when consumers unfurl the URL, they are redirected to the page where they can sign up to create a Miro account:

https://miro.com/signup/

Example

<!-- oEmbed support for the Miro board: consumers detect the 'link' element in the 'head' section (Response: JSON) -->

<link
  rel="alternate"
  type="application/json+oembed"
  title="Miro board"
  href="https://miro.com/api/v1/oembed?url=https://miro.com/app/board/uXjVPZH3NrA=&format=json">

<!-- oEmbed support for the Miro board: consumers detect the 'link' element in the 'head' section (Response: XML) -->

<link
  rel="alternate"
  type="text/xml+oembed"
  title="Miro board"
  href="https://miro.com/api/v1/oembed?url=https://miro.com/app/board/uXjVPZH3NrA=&format=xml">

Attribute

Value

Description

rel

alternate

alternate is the value defining the type of relationship between the linked document (in this case, a Miro board), and the current document (in this case, the document the board is embedded into.)

For more information, see the alternate link type.

type

Allowed values:

  • application/json+oembed
  • text/xml+oembed

The format of the resource that is returned.
Allowed formats:

  • JSON
  • XML

title

Example:
Miro board

The title of the board, as displayed in the embed in the third-party tool.

href

Example:
https://miro.com/api/v1/oembed?url=https://miro.com/app/board/uXjVPZH3NrA=&format=json

The URL pointing to the target resource to embed.
It consists of:

  • https://miro.com/api/v1/oembed: Miro's oEmbed endpoint.
  • ?url=https://miro.com/app/board/uXjVPZH3NrA=: the URL pointing to the resource to return as oEmbed data.
    Currently, it supports only Miro live embed boards.
  • &format=json: the format of the resource that is returned.
    The format specified in this URL parameter must match the format specified in the type attribute.
    Allowed values:
    • json
    • xml

See also


What's next

Try the oEmbed endpoint in the REST API playground.