GuidesWeb SDK 2.0REST API 2.0Live EmbedSCIM APIChangelogRoadmapCommunity
Build your app

Update document item using file from device

📘

Note

You cannot try out this API from the developer portal at the moment. We are working on fixing the known limitations. Feel free to try out the API in a tool of your choice. The API request and response information are provided in this document.

Resource URL

HTTP Method: PATCH

URL: https://api.miro.com/v2/boards/{board_id}/documents/{document_item_id}

Content-Type header: multipart/form-data

Request

Request Type: Form-data

Key nameValue
resource
(required)		The document file from the device. For example, foo.pdf. The maximum file size supported is 6 MB.
data
(optional)		Text file containing JSON object data.

Here is the sample JSON object data content. All parameters are optional in the JSON data file.

{
    "title": "title for the document",
    "position": {
        "x": 100,
        "y": 200
    },
    "geometry": {
        "width": 100,
        "height": 100,
        "rotation": 0
    },
    "parent": {
        "id": "3458764559676855849"
    }
}
Parameter Description
titleThe the title for the document.
xThe X-axis coordinate of the location of the center of the item on the board. By default, all items have absolute positioning to the board, not the current viewport. The center point of the board has x: 0 and y: 0
coordinates.
Default: 0
yThe Y-axis coordinate of the location of the center of the item on the board. By default, all items have absolute positioning to the board, not the current viewport. The center point of the board has x: 0 and y: 0
coordinates.
Default: 0
widthThe width of the item, in pixels.
heightThe height of the item, in pixels.
rotationThe rotation angle of an item, in degrees, relative to the board. You can rotate items clockwise (right) and counterclockwise (left) by specifying positive and negative values, respectively.
parent.idThe parent object contains information about the parent this item must be attached to. A maximum of 1000 items can be attached to a frame. Passing null for parent.id directly attaches an item to the canvas.

parent.id is the unique identifier (ID) of the parent frame for the item.

Response

HTTP 200 OK

{
    "id": "3458764513820647931",
    "type": "document",
    "createdAt": "2022-01-26T10:21:16Z",
    "createdBy": {
        "id": "3458764513820541929",
        "type": "user"
    },
    "data": {
        "title": "title for the document"
    },
    "position": {
        "x": 100,
        "y": 200,
        "origin": "center"
    },
    "geometry": {
        "width": 100,
        "height": 100,
        "rotation": 0
    },
    "parent": {
        "id": "3458764559676855849"
    },
    "modifiedAt": "2022-01-26T10:21:16Z",
    "modifiedBy": {
        "id": "3458764513820541929",
        "type": "user"
    }
}

Returns

Required scope

Rate limiting

Examples

Node.js API client

Use the update method on the document object: https://miroapp.github.io/api-clients/classes/index.DocumentItem.html#update

Node.js example using node-fetch library

import { basename } from "path";
import fetch, { blobFrom } from "node-fetch";

const boardId = "";
const oAuthToken = "";
const documentId = ""

const fileName = "./file.pdf";

const form = new FormData();
form.append("resource", await blobFrom(fileName), basename(fileName));
form.append(
  "data",
  new Blob(
    [
      JSON.stringify({
        title: "title for the document",
        position: {
          x: 100,
          y: 200,
        },
        geometry: {
          width: 100,
          rotation: 0,
        },
        parent: {
          id: "3458764559676855849",
        },
      }),
    ],
    { type: "application/json" }
  )
);

const res = await fetch(`https://api.miro.com/v2/boards/${boardId}/documents/${documentId}`, {
  method: "PATCH",
  body: form,
  headers: {
    Authorization: `Bearer ${oAuthToken}`,
  },
});

console.log(res.status);
console.log(await res.json());

Python example using requests library

import json
from os import path

import requests

boardId = ""
oAuthToken = ""
documentId = ""

fileName = "./file.pdf"

files = [
    (
        "resource",
        (path.basename(fileName), open(fileName, "rb"), "application/pdf"),
    ),
    (
        "data",
        (
            None,
            json.dumps(
                {
                    "title": "title for the document",
                    "position": {
                        "x": 100,
                        "y": 200,
                    },
                    "geometry": {
                        "width": 100,
                        "rotation": 0,
                    },
                    "parent": {
                        "id": "3458764559676855849",
                    },
                }
            ),
            "application/json",
        ),
    ),
]
headers = {
    "Authorization": f"Bearer {oAuthToken}",
}
url = f"https://api.miro.com/v2/boards/{boardId}/documents/{documentId}"

response = requests.patch(url, headers=headers, data={}, files=files)
print(response.text)