Manage media using the REST API

8 min

Media content represents binary files such as images, videos, and documents stored in Optimizely Content Management System (SaaS). Unlike regular content items that use JSON for creation, media content requires a multipart form-data request to upload the binary file along with its metadata.

Create media content

To create media content, send a POST request to the content endpoint using multipart/form-data content type. The request must include two parts:

content – JSON containing the content definition

file – The binary file to upload

POST https://api.cms.optimizely.com/v1/content
Content-Type: multipart/form-data

The content part must include the content type, the container, and the initial version details. Use a content type with a media base type such as _image, _video, or _media. CMS (SaaS) includes the built-in ImageMedia content type for images.

curl -X POST https://api.cms.optimizely.com/v1/content \
  -H "Authorization: Bearer {access_token}" \
  -F 'content={"contentType": "ImageMedia", "container": "e56f85d0e8334e02976a2d11fe4d598c", "initialVersion": {"displayName": "My Image"}};type=application/json' \
  -F 'file=@/path/to/image.jpg;type=image/jpeg'

The response includes the created content with a media.key in the initialVersion that identifies the uploaded file.

{
  "key": "6946107a8ad6414f8f1786364dab1ec2",
  "container": "e56f85d0e8334e02976a2d11fe4d598c",
  "contentType": "ImageMedia",
  "locales": [""],
  "created": "2024-01-15T10:30:00+00:00",
  "createdBy": "api-client",
  "initialVersion": {
    "key": "6946107a8ad6414f8f1786364dab1ec2",
    "version": "1",
    "contentType": "ImageMedia",
    "displayName": "My Image",
    "status": "draft",
    "media": {
      "key": "a1b2c3d4e5f6.jpg"
    }
  }
}

🚧 File required Media content cannot be created without providing a binary file. Attempting to create media content with only JSON (without the file part) returns an error.

See Create contentCreate content API reference.

Create a new version of media content

To upload a new file for an existing media content item, use the versions endpoint with multipart form-data.

POST https://api.cms.optimizely.com/v1/content/6946107a8ad6414f8f1786364dab1ec2/versions
Content-Type: multipart/form-data

curl -X POST https://api.cms.optimizely.com/v1/content/6946107a8ad6414f8f1786364dab1ec2/versions \
  -H "Authorization: Bearer {access_token}" \
  -F 'content={"displayName": "Updated Image"};type=application/json' \
  -F 'file=@/path/to/new-image.jpg;type=image/jpeg'

See Create versionCreate version API reference.

Download media content

To download the binary file of a media content item, use the media endpoint with the content key and version identifier.

GET https://api.cms.optimizely.com/v1/content/6946107a8ad6414f8f1786364dab1ec2/versions/1/media

The response returns the binary file with the appropriate Content-Type header matching the file type (for example, image/jpeg, image/png, or application/pdf).

curl -X GET https://api.cms.optimizely.com/v1/content/6946107a8ad6414f8f1786364dab1ec2/versions/1/media \
  -H "Authorization: Bearer {access_token}" \
  -o downloaded-image.jpg

File size limits

Even though the API has a maximum request size of 500 MB, bandwidth and timeout considerations (100 second limit) make it best suited for smaller website assets, typically under 100 MB. For large assets such as videos and high-resolution images, use Optimizely DAM instead, which supports chunked uploads for reliable transfer of large files.

File extension validation

Each media content type defines which file extensions it supports through the mediaFileExtensions property. When uploading a file, the API validates the file extension against the content type's allowed extensions.

For example, the built-in ImageMedia content type only accepts common image formats like .jpg, .png, .gif, .webp, and .svg. Attempting to upload a .pdf file using ImageMedia returns a validation error.

You can create custom media content types with specific file extension restrictions:

{
  "key": "heroImage",
  "baseType": "_image",
  "displayName": "Hero Image",
  "mediaFileExtensions": ["jpg", "png", "webp"]
}

See Create content typeCreate content type API reference.