🚧

We are working on known issues with the Metadata feature.
We do not recommend using this feature in a production environment at the moment.

Application metadata provides a way for you to store your own custom data on widgets. This can be used to keep track of a custom state alongside a widget, hold a link to a related item in another system, and various other things.

You can write metadata only for the app id which is bounded to your token.

Metadata is available via REST API and SDK as well.
Please note that metadata was designed to store a small amount of data. It is limited by 6KB of data per widget for all applications.

🚧

The metadata field is shared in read mode across all apps that can access board widgets.

Read

Application metadata is the optional field which will be always returned with widget data, for example:

GET https://api.miro.com/v1/boards/{boardKey}/widgets/{widgetId}
Content-Type: application/json
Authorization: Bearer *****
HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8

{
  "type": "card",
  "id": "{widgetId}",
  "title": "",
  
  "metadata": {
    "3074457345618258744": {
      "issue": "JA-12323"
    },
    "{your_app_id}": {
      "someData": "value as string or number, or object"
    }
  }
}

Create / Update

For creating or updating metadata you should add JSON object into your_app_id field of the metadata field of the widget data and simply create or update a widget with these data.

PATCH https://api.miro.com/v1/boards/{boardKey}/widgets/{widgetId}
Content-Type: application/json
Authorization: Bearer *****

{
  "title": "",
  "metadata": {
    "{your_app_id}": {
      "changed": "data"
    }
  }
}
HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8

{
  "type": "card",
  "id": "{widgetId}",
  "title": "",
  
  "metadata": {
    "3074457345618258744": {
      "issue": "JA-12323"
    },
    "{your_app_id}": {
      "changed": "data"
    }
  }
}

Delete

PATCH https://api.miro.com/v1/boards/{boardKey}/widgets/{widgetId}
Content-Type: application/json
Authorization: Bearer *****

{
  "metadata": {
    "{your_app_id}": null
  }
}
HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8

{
  "type": "card",
  "id": "{widgetId}",
  "title": "",
  
  "metadata": {
    "3074457345618258744": {
      "issue": "JA-12323"
    }
  }
}