How to upload an image to a mural

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

  1. Create an asset URL.
  2. Upload an image to the storage.
  3. 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:

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 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.