How to upload an image to a mural

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

Create an asset URL.
Upload an image to the storage.
Create image widget on a mural.

1. Create an asset URL

To create an asset URL to upload an image to a mural, you need to visit the API Reference 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": "png"
      }
      '

Response example:

{
  "value": {
    "url": "https://url:443/uploads/workspace1234/jD6Qzs6lSHy2bHAwFfCrjqU9RL3vCxFgYVl2nQrUYA.png?se=2057-04-01T19%3A27%3A52Z&sp=c&sv=2018-03-28&sr=b&sig=Jh...qYQ%3D",
    "name": "workspace1234/jD6Qzs6lSHy2bHAwFfCrjqU9RL3vCxFgYVl2nQrUYA.png",
    "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 an image to storage

To upload an image to storage, you need to make a PUT request to the received URL from the previous Create an asset URL step using the 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.png?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.png'

❗️
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 an image widget on a mural

To create an image widget with the previously uploaded image, call the Create an image 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/image' \
     --header 'Authorization: Bearer <TOKEN>' \
     --header 'Content-Type: application/json' \
     --data-raw '{
        "name": "<name>",
        "x":350,
        "y":370,
        "width": 600,
        "height": 600,
        "border": true,
        "presentationIndex": 0,
        "rotation": 0,
        "showCaption": false
    }'

Payload example:

{
    "name": "workspace1234/jD6Qzs6lSHy2bHAwFfCrjqU9RL3vCxFgYVl2nQrUYA.png",
    "x":350,
    "y":370,
    "width": 600,
    "height": 600,
    "border": true,
    "presentationIndex": 0,
    "rotation": 0,
    "showCaption": false
}

Allowed image extensions list:

bmp
ico
gif
jpeg
jpg
png
webp

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