Ctrl+K

Introduction to Image Endpoints

Introduction to Image Endpoints#

Images can be uploaded to Workiva and then inserted into content.

In this guide, you’ll learn:

  • How do I insert an image into content?

  • How do I retrieve an image from content?

  • Can I delete uploaded images?

Example Use Cases#

How do I insert an image into content?#

In this exercise, you will insert an image into rich text. To follow these steps, you’ll need:

  • The richTextId, revision, and Caret values where the image is to be inserted. Refer to Introduction to rich text to learn about obtaining a richTextId and identifying locations in rich text.

  • An image you want to upload

Important

Each uploaded image may be inserted only once. If you want to insert an image in more than one place, you will need to upload the image and obtain a new image id for each insert.

Uploading an image#

Use a POST Initiate upload of an image call to request a URL to which you will upload the image.

Request#
curl -X POST -H "Authorization: Bearer ${token}" --data @body.json https://api.app.wdesk.com/prototype/platform/content/images/upload
Request Body#
{
  "fileName": "logo.jpg"
}

A 202 response has an uploadUrl in the body and also has the typical Operations pattern headers. Note the response’s Location header for later use.

Response#
{
  "uploadUrl": "https://h.app.wdesk.com/s/blob-storage/api/v1/blobs/QWNjb3VudB81NjM5NDQ1NjA0NzI4ODMy/YnMyOjA6MTg2ZWM5OWRkZjNlNDRhMjk2YzA3MjliMjUxYjU3ODc?action=upload&cid=69195229-8875-4091-b54b-aaa2daef9874&client=image-services&expire=12345&membership=TWVtYmVyc2hpcB81MTY5NzQ0NzYwMDEyODAw&organization=a25bc16f-fb62-4aff-a87e-1cca4b2113c0&requester=cerberus-service&scope=image-services&user=V0ZVc2VyHzU3NDg4MDk2OTkxNjQxNjA&sig=909abc909"
}

PUT your image to the provided URL.

Request#
curl -X PUT -H "Authorization: Bearer ${token}" --data-binary "@path/to/logo.jpg" https://h.app.wdesk.com/s/blob-storage/api/v1/blobs/QWNjb3VudB81NjM5NDQ1NjA0NzI4ODMy/YnMyOjA6MTg2ZWM5OWRkZjNlNDRhMjk2YzA3MjliMjUxYjU3ODc?action=upload&cid=69195229-8875-4091-b54b-aaa2daef9874&client=image-services&expire=12345&membership=TWVtYmVyc2hpcB81MTY5NzQ0NzYwMDEyODAw&organization=a25bc16f-fb62-4aff-a87e-1cca4b2113c0&requester=cerberus-service&scope=image-services&user=V0ZVc2VyHzU3NDg4MDk2OTkxNjQxNjA&sig=909abc909

An empty 200 response indicates that your upload has completed.

Workiva performs checks on uploaded files, including a virus scan. Follow the typical Operations pattern using the URL from the Location header noted after Initiate upload of an image. When the operation is complete, retrieve your image id from the operation’s specific resourceUrl endpoint. For example, suppose your operation response is below.

Response#
{
    "created": {
        "dateTime": "2025-07-07T14:47:00Z"
    },
    "id": "b21c3b3c-6156-4613-94e1-c1993014f173",
    "originalRequest": "4425a4c9-ebc6-4b15-8947-c4304fee696b",
    "resourceUrl": "https://api.app.wdesk.com/prototype/platform/operations/b21c3b3c-6156-4613-94e1-c1993014f173/imageUploadResults",
    "status": "completed",
    "updated": {
        "dateTime": "2025-07-07T14:48:19Z"
    }
}

You will retrieve your image id using the resourceUrl.

Request#
curl -X GET -H "Authorization: Bearer ${token}" https://api.app.wdesk.com/prototype/platform/operations/b21c3b3c-6156-4613-94e1-c1993014f173/imageUploadResults
Response#
{
    "data": [
        {
            "image": "bWFpbmxpbmUtdjE6WW5NeU9qQTZOamt5Wmpaa01tVTJPR0ptTkdObVlqaGtObU00WVRBNU1XUmtaakJpTjJV",
            "type": "image"
        }
    ]
}

Your image id is bWFpbmxpbmUtdjE6WW5NeU9qQTZOamt5Wmpaa01tVTJPR0ptTkdObVlqaGtObU00WVRBNU1XUmtaakJpTjJV.

Inserting an image#

Once you have uploaded an image, your upload operation is complete, and you have an image id, you are ready to insert your image.

Collect the richTextId, revision, and Caret values where the image is to be inserted. Refer to Introduction to rich text to learn about obtaining a richTextId and identifying locations in rich text.

To insert your image, use the InsertImage edit type in POST Initiate edits to rich text.

Request#
curl -X POST -H "Authorization: Bearer ${token}" --data @body.json https://api.app.wdesk.com/prototype/platform/content/richText/WA2NiYGJgm7cWr4W6Ka9BHScz56m2AT2FqTmBgekyk399M99I9Bb69BoEt3WHCag/edit
Request Body#
{
    "revision": "2c6438ab454ffa23",
    "data": [
        {
            "type": "insertImage",
            "insertImage": {
                "dimensions": {
                    "height": 240,
                    "width": 320
                },
                "image": "bWFpbmxpbmUtdjE6WW5NeU9qQTZOamt5Wmpaa01tVTJPR0ptTkdObVlqaGtObU00WVRBNU1XUmtaakJpTjJV",
                "insertAt": {
                    "offset": 0,
                    "paragraphIndex": 0
                }
            }
        }
    ]
}

After the request is accepted, the status of the request can be found through polling the Operations endpoint set in the location header of the batch edit’s response.

How do I retrieve an image from content?#

Within the Workiva platform, images are referred to by an identifier. You can resolve this identifier to the image’s content using GET Retrieve an image by id.

One common way to encounter image ids is through GET Retrieve rich text paragraphs. For example, suppose you wish to retrieve the bytes of the image included in a rich text response:

Image element#
{
    "image": {
        "dimensions": {
            "height": 240,
            "width": 320
        },
        "format": {},
        "image": {
            "image": "bWFpbmxpbmUtdjE6WW5NeU9qQTZOamt5Wmpaa01tVTJPR0ptTkdObVlqaGtObU00WVRBNU1XUmtaakJpTjJV",
            "location": "https://api.app.wdesk.com/prototype/platform/content/images/bWFpbmxpbmUtdjE6WW5NeU9qQTZOamt5Wmpaa01tVTJPR0ptTkdObVlqaGtObU00WVRBNU1XUmtaakJpTjJV"
        },
        "length": 1,
        "offset": 0
    },
    "type": "image"
}

Call GET Retrieve an image by id using the image id.

Request#
curl -X GET -H "Authorization: Bearer ${token}" https://api.app.wdesk.com/prototype/platform/images/bWFpbmxpbmUtdjE6WW5NeU9qQTZOamt5Wmpaa01tVTJPR0ptTkdObVlqaGtObU00WVRBNU1XUmtaakJpTjJV
Response#
{
    "downloadUrl": "https://h.app.wdesk.com/s/blob-storage/api/v1/blobs/QWNjb3VudB81NjM5NDQ1NjA0NzI4ODMy/YnMyOjA6NjkyZjZkMmU2OGJmNGNmYjhkNmM4YTA5MWRkZjBiN2U?action=download&cid=1cf0c5b3-5397-4a62-a43c-28b80576cee0&client=image-services&expire=1751921213&filename=iJdNIaKMgpu2bWD40JZ-mVPcgPoKsWGHdlBTqkuT9V8sGmYR&membership=TWVtYmVyc2hpcB81MTY5NzQ0NzYwMDEyODAw&organization=a25bc16f-fb62-4aff-a87e-1cca4b2113c0&requester=cerberus-service&response_content_length=10214&response_content_type=image%2Fpng&scope=image-services&user=V0ZVc2VyHzU3NDg4MDk2OTkxNjQxNjA&sig=64cd2e7441f6672065966bddfc3a5149599b2b97adc3b55de640ceb22e8b6a78",
    "fileName": "logo.png",
    "id": "bWFpbmxpbmUtdjE6WW5NeU9qQTZOamt5Wmpaa01tVTJPR0ptTkdObVlqaGtObU00WVRBNU1XUmtaakJpTjJV",
    "mimeType": "image/png"
}

Now, you can retrieve the downloadUrl to get the image bytes.

Request#
curl -X GET -H "Authorization: Bearer ${token}" https://h.app.wdesk.com/s/blob-storage/api/v1/blobs/QWNjb3VudB81NjM5NDQ1NjA0NzI4ODMy/YnMyOjA6NjkyZjZkMmU2OGJmNGNmYjhkNmM4YTA5MWRkZjBiN2U?action=download&cid=1cf0c5b3-5397-4a62-a43c-28b80576cee0&client=image-services&expire=1751921213&filename=iJdNIaKMgpu2bWD40JZ-mVPcgPoKsWGHdlBTqkuT9V8sGmYR&membership=TWVtYmVyc2hpcB81MTY5NzQ0NzYwMDEyODAw&organization=a25bc16f-fb62-4aff-a87e-1cca4b2113c0&requester=cerberus-service&response_content_length=10214&response_content_type=image%2Fpng&scope=image-services&user=V0ZVc2VyHzU3NDg4MDk2OTkxNjQxNjA&sig=64cd2e7441f6672065966bddfc3a5149599b2b97adc3b55de640ceb22e8b6a78

The response will be the bytes of your image.

Can I delete an uploaded image?#

Images may be removed from a document using the API, but it is not possible to remove the image’s data from the Workiva platform using the API.

If you upload but do not insert an image, Workiva may remove the unused image after a period of time. Once an image is inserted, the image’s data can no longer be removed from the Workiva platform due to the need to review document history.