Introduction

πŸ“˜

Discovery APIs are available only to a closed private beta cohort of customers on the Enterprise plan. This functionality is being considered for monetization as a separate add-on product to the Enterprise plan, as this functionality is highly specific and only relevant to a subset of our customers. If you are an Enterprise customer with a use case for the beta, please contact your Customer Success Manager to join the waitlist for early access.

Overview

Discovery APIs allow customers on the Enterprise Plan to export board data from Miro so the board data can 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 that includes a PDF export of the board content and a JSON record of all open comments at the time when the job runs. For large boards, the export job produces multiple PDF files to depict the complete board.

The asynchronous API design includes endpoints for retrieving information about a board export job, such as the status.

πŸ“˜

Each organization can have only one board export job in the IN_PROGRESS status. 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 digitally-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 , 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 , 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.etry the status call after some time.
    4. If the jobStatus returns FINISHED, he job is finished. You can now get results for the board exportjob.
  3. Retrieving the board export job results

    1. Make a request to , 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 an , with an individual S3 download link tolocation for the export rResults for each that specific board found in the exportLink field. UDownload the zip file from the S3 location.
    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 has the file name uXjVPzN27sM=.zip.
  • One or more PDF files with visual representations of the board canvas.
    Large boards are split into multiple PDF files.
  • Comments: JSON file with current comments on the board.

Beta limitations

  • The API returns only the boards that the admin who sets up the Miro Discovery access token has permission to view.
    If that admin does not have access to a board, the API returns the following error:
    Board doesn’t exist or you don’t have access to it.
  • Boards that are password protected are not supported for download via the beta APIs.
  • The board export job does not include any board activity history or information, and acts as a snapshot of the current state of the board. As part of the Discovery APIs beta, we plan to release additional endpoints that make it possible to retrieve a content log that denotes all changes to a board and who made each change.
  • The board export job does not include any information about which users can access or have collaborated with the board. The content log will consist of recording the actions of individuals, and we are assessing the need to consolidate the information to support customer use cases as part of the beta.