DocumentationResourcesMarketplaceCommunity
API Reference
Build your app

Board export job

📘

Discovery APIs are available as a Beta release to all customers on the Enterprise plan.

Overview

Discovery APIs allow customers on the Enterprise Plan to export board data from Miro to be reviewed manually or ingested into purpose-built tools for legal, compliance, and security purposes. The first Discovery API, Board export API, is now in beta.

The Board export API provides a ZIP file with a snapshot of the board data at the time the job runs, including export of the board content in a specified format SVG, PDF or HTML, a JSON file with a record of all comments, a JSON file with a list of all users who viewed or modified the board, video recordings of TalkTrack webcam footage associated with the board, if applicable, and a JSON with Board matadata. For large boards, the export in PDF format produces multiple PDF files depicting the complete board.
The asynchronous API design includes endpoints for retrieving information about a board export job, such as the status.

📘

If you are on the Enterprise private beta for Discovery APIs, you can only have one board export job running at a time. If you are an Enterprise Guard customer, you can run up to five board export jobs at the same time. The rate limit is set to level 4.

Use cases

Some of the common discovery use cases include:

  • eDiscovery (electronic discovery): the process of identifying, collecting, preserving, and reviewing electronically stored information for use in a legal matter.
  • Information archive: a practice in which organizations maintain data outside the original system for long-term storage and record-keeping purposes. The content and metadata help customers index and search the archive and proactively monitor for compliance concerns.

Enabling eDiscovery in your Miro environment

Get the Discovery access token from the Enterprise integrations admin console:

  1. Log in to Miro as a Company Admin.
  2. Go to Settings > Enterprise Integrations.
  3. To enable eDiscovery, click the toggle.
  4. Copy the access token.
Settings image

Figure 1. Enable eDiscovery in the Enterprise Integrations Settings page.

Workflow

📘

The beta version of this API has limitations. The beta cohort will receive incremental data enrichment and API endpoints to solve their use cases as we work to productize a generally available offering.

  1. Creating an export job for boards

    1. Identify the set of Miro board IDs that meet your discovery criteria.

      📘

      • Identification of boards may come from custodians who share a URL, by querying the Get boards API or by analyzing Audit logs.
      • The board ID can be derived from the last part of a board url. For example, If the URL is https://miro.com/app/board/uXjVOD50NUI=/, then the board ID is uXjVOD50NUI=.
    2. Make a request to create a board export job, where the boardIds body parameter is an array of the boards to export and the request_id parameter is a unique UUID created within your code.

      📘

      • A single board export job can have a maximum of 50 boards.
      • The UUID acts as an idempotency key. Subsequent requests using the same UUID will return the same jobId.
    3. Store the returned jobId for use in future steps.

      📘

      The UUID you provide is strictly for idempotency purposes and subsequent calls rely solely on the returned jobId from this step.

  2. Check the status of an export job

    📘

    We suggest you utilize an exponential back-off retry strategy.

    1. Make a request to get the board export job status, where the jobId parameter is the value returned from Step 1.
    2. If the jobStatus returns CREATED, the job has been created but not yet started. Retry the status call after some time.
    3. If the jobStatus returns IN_PROGRESS, the job is in progress, and the results are not ready yet. Retry the status call after some time.
    4. If the jobStatus returns FINISHED, the job is finished. You can now get results for the board export job.

  3. Retrieving the board export job results

    1. Make a request to get results for the board export job, where the jobId parameter is the value returned from Step 1.
    2. A successful call returns a results array for each board export requested.
    3. The exportLink parameter returns the URL to the ZIP archive containing exported files.
    4. You can now utilize the downloaded board export results for manual review locally, or chain another job to ingest it into the compliance solution of choice.

Export content and structure

An individual zip file package is provided for each board.

  • The extracted zip file will use the boardKey as the naming standard.
    For example, if you request to export boardId _uXjVPzN27sM=, the corresponding export zip file name is _uXjVPzN27sM=.zip.
  • Based on the selected board Format:
    • SVG or HTML file and a folder with resources.
    • One or more PDF files with visual representations of the board canvas. Large boards are split into multiple PDF files.
  • Comments: JSON file with comments on the board.
  • Collaborators: JSON file with lists of board viewers and contributors.
  • Metadata: JSON file with board metadata, including title, description, creator, etc.
  • If applicable, one or more MP4 or Webm video files with the webcam footage and a JSON metadata file containing information about the TalkTrack associated with the board, if applicable.

📘

Results of the export job are available to download for 7 days.