Initiate upload of an image

Table Of Contents

Initiate upload of an image#

Deprecated

This endpoint is deprecated and may be removed in a future release.

This endpoint was deprecated on 2026-02-12.

It is scheduled for sunset on 2027-01-31.

Description#

Retrieves a URL that can be used to upload an image, and an operationId to track the image upload progress. Once uploaded, the image can be inserted in content.

Image uploads must conform to the following constraints:

An image must be uploaded once per usage in content.
Image uploads must complete within ten minutes.
The file size of the uploaded image must 75 MB or smaller.
The total number of pixels in the uploaded image must be 50 Megapixels or smaller.
The image must be inserted in content within 24 hours or it will be removed.

Responses include an uploadUrl which indicates where to upload the image. To upload the file, perform a PUT against the uploadUrl with the same authentication credentials and flow as the import request. For more details, see Authentication documentation. The response will also include a Location header, which indicates where to poll for results. For more details on long-running job polling, see Operations endpoint. When the upload completes, its status will be completed, and the response body includes a resourceURL.

POST /prototype/platform/content/images/upload

Required OAuth Scopes

file:write

Parameters#

Parameter	In	Type	Required	Description
X-Version	header	string	false	Version of the API (2022-01-01)
body	body	ImageUpload	false	Details about the image upload.

Body parameter example#

{
  "fileName": "example.png"
}

Code Samples#

curl

curl -X POST https://api.app.wdesk.com/prototype/platform/content/images/upload \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer {access-token}' \
    -H 'X-Version: 2022-01-01'

httpie

http POST https://api.app.wdesk.com/prototype/platform/content/images/upload \
    X-Version:2022-01-01 \
    Content-Type:application/json \
    Accept:application/json \
    Authorization:"Bearer {access-token}"

wget

wget --method=POST "https://api.app.wdesk.com/prototype/platform/content/images/upload" \
    --output-document -  \ 
    --header 'Content-Type: application/json' \ 
    --header 'Accept: application/json' \ 
    --header 'Authorization: Bearer {access-token}' \
    --header 'X-Version: 2022-01-01'

python

import requests

headers = {
  'X-Version': '2022-01-01',
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('https://api.app.wdesk.com/prototype/platform/content/images/upload', headers = headers)

print(r.headers['Location'])

Returns#

202 - Accepted#

Returns a ImageUploadResponse object containing details for uploading the image.

Header	Description
Location	The location to poll for the operation result.
Retry-After	The number of seconds to wait before polling for a result and between polling attempts.

400 - Bad Request#

Error response that indicates that the service is not able to process the incoming request. The reason is provided in the error message.

401 - Unauthorized#

Error response that indicates that the service is not able to process the incoming request. The reason is provided in the error message.

403 - Forbidden#

Error response that indicates that the service is not able to process the incoming request. The reason is provided in the error message.

404 - Not Found#

Error response that indicates that the service is not able to process the incoming request. The reason is provided in the error message.

409 - Conflict#

Error response that indicates that the service is not able to process the incoming request. The reason is provided in the error message.

429 - Too Many Requests#

Error response that indicates that the service is not able to process the incoming request. The reason is provided in the error message.

500 - Internal Server Error#

Error response that indicates that the service is not able to process the incoming request. The reason is provided in the error message.

503 - Service Unavailable#

Error response that indicates that the service is not able to process the incoming request. The reason is provided in the error message.

Example Responses#

202 Response

{
  "uploadUrl": "<opaque_url>"
}

Bad Request

{
  "code": "400BadRequest",
  "message": "The request was unacceptable, often due to a missing or invalid parameter"
}

Unauthorized

{
  "code": "401Unauthorized",
  "message": "No valid API token provided"
}

Forbidden

{
  "code": "403Forbidden",
  "message": "The API token does not have permissions to perform the request"
}

Not Found

{
  "code": "404NotFound",
  "message": "The requested resource could not be found"
}

Conflict

{
  "code": "409Conflict",
  "message": "The request conflicts with another request"
}

Too Many Requests

{
  "code": "429TooManyRequests",
  "message": "Too many requests have been made against the API in too short a time"
}

Internal Server Error

{
  "code": "500InternalServerError",
  "message": "The server encountered an unexpected condition that prevented it from fulfilling the request"
}

Service Unavailable

{
  "code": "503ServiceUnavailable",
  "message": "The server cannot handle the request due to a temporary overload or scheduled maintenance"
}