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:

Create an asset URL.
Upload a file to the storage.
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:

Response	Description
`name`	The path of the workspace followed by the file name.
`url`	The URL in the storage where the file will be uploaded.
`headers`	The 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.