How to upload a file to a mural

📘

You'll see the word "widgets" throughout this guide. Widgets are the same as objects in Mural. For more information on objects, see our Objects in Mural support article.

To upload a file to a mural, follow these steps in this specific order:

  1. Create an asset URL.
  2. Upload a file to the storage.
  3. Create a file widget on a mural.

1. Create an asset URL

To create an asset URL to upload a file to a mural, you need to visit the API Reference section and follow instructions for the Create an asset URL endpoint.

Or, you can use this cURL code:

curl --request POST \
     --url https://app.mural.co/api/public/v1/murals/<muralId>/assets \
     --header 'Authorization: Bearer <TOKEN>' \
     --header 'Content-Type: application/json' \
     --data '
      {
           "fileExtension": "pdf"
      }
      '

Response example:

{
  "value": {
    "url": "https://url:443/uploads/workspace1234/jD6Qzs6lSHy2bHAwFfCrjqU9RL3vCxFgYVl2nQrUYA.pdf?se=2057-04-01T19%3A27%3A52Z&sp=c&sv=2018-03-28&sr=b&sig=Jh...qYQ%3D",
    "name": "workspace1234/jD6Qzs6lSHy2bHAwFfCrjqU9RL3vCxFgYVl2nQrUYA.pdf",
    "headers": {
      "x-ms-blob-type": "BlockBlob"
    }
  }
}

As a response, you'll receive:

ResponseDescription
nameThe path of the workspace followed by the file name.
urlThe URL in the storage where the file will be uploaded.
headersThe headers required for uploading to the storage.

If the specified file extension isn't allowed, an error is returned:

{
   "code": "ASSET_TYPE_FORBIDDEN",
   "message": "The asset's file extension is invalid."
}

2. Upload a file to the storage

To upload a file to the storage, you need to make a PUT request to the received URL from the previous Create an asset URL step using other received fields.

curl --request PUT <url> \
     --header 'x-ms-blob-type: <headers["x-ms-blob-type"]>' \
     --data-binary <path to file to be uploaded>

Here is an cURL example based on the received response from the Create an asset url step:

curl --request PUT 'https://url:443/uploads/workspace1234/jD6Qzs6lSHy2bHAwFfCrjqU9RL3vCxFgYVl2nQrUYA.pdf?se=2057-04-01T19%3A27%3A52Z&sp=c&sv=2018-03-28&sr=b&sig=Jh...qYQ%3D' \
     --header 'x-ms-blob-type: BlockBlob' \
     --data-binary '@/Users/testuser/jD6Qzs6lSHy2bHAwFfCrjqU9RL3vCxFgYVl2nQrUYA.pdf'

❗️

Be aware that uploading a file multiple times to the same storage URL will lead to an error:

403 This request is not authorized to perform blob overwrites.

3. Create a file widget on a mural

To create a file widget with the previously uploaded file, call the Create a file widget on a mural endpoint. In the payload, use the file name that was generated and received in the Create an asset URL step.

Or, use this code:

curl --request POST 'https://app.mural.co/api/public/v1/murals/<muralId>/widgets/file' \
     --header 'Authorization: Bearer <TOKEN>' \
     --header 'Content-Type: application/json' \
     --data-raw '{
        "name": "<name>",
        "x":350,
        "y":370,
        "width": 600,
        "height": 600,
        "presentationIndex": 0,
        "rotation": 0
    }'

Payload example:

{
    "name": "workspace1234/jD6Qzs6lSHy2bHAwFfCrjqU9RL3vCxFgYVl2nQrUYA.pdf",
    "x":350,
    "y":370,
    "width": 600,
    "height": 600,
    "presentationIndex": 0,
    "rotation": 0
}

If the response has a 201 status, the file widget was successfully created on the mural.