---
title: Manage media using the REST API
slug: cms-saas/docs/manage-media-using-the-rest-api
docTags: 
createdAt: 2026-07-30T20:18:09.000Z
---

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

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

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

```json
{
  "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"
    }
  }
}
```

:::hint{type="warning"}
**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 content](docId\:p9XgSvFtr8nSot5JGYOq0) 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.

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

```shell
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 version](docId\:qSPcUK4nE2-noWWANl-yH) 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.

```http
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`).

```shell
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](https://docs.developers.optimizely.com/digital-asset-management/docs) 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:

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

See [Create content type](docId\:WFhEMMql5Y0x5-zT_t6df) API reference.