> ## Documentation Index
> Fetch the complete documentation index at: https://cloudinary.com/documentation/llms.txt
> Use this file to discover all available pages before exploring further.

# Media Optimizer API reference


Cloudinary's Media Optimizer is for targeted Enterprise organizations and simplifies the process to optimize and deliver high-quality media with high performance, low latency and massive scalability. 
> **The Media Optimizer documentation includes:**:
>
> **Guides**

> * [Quick starts](media_optimizer_quickstart)

> * [Configuration](media_optimizer_configuration)

> * [Dashboard](media_optimizer_dashboard)

> * [Reports](media_optimizer_reports)

> * [Transformations](media_optimizer_transformations)
> **References**

> * [Media Optimizer API](media_optimizer_api)

> * [Transformation reference](media_optimizer_transformation_reference)
This page covers the Media Optimizer API, which is a **rate-limited** API that lets you manage your Media Optimizer configuration components, such as media sources and optimization profiles, manage your Media Optimizer cache and other administration functionality.

For a complete overview of Media Optimizer and how it can help you to optimize the media on your site, see the [Media Optimizer Guide](media_optimizer). 

## API overview

The Media Optimizer API endpoints are accessed using HTTPs. By default, the API endpoints use the following format:

`https://mo-api.cloudinary.com/v1/:cloud_name/:action`

The API uses **Basic Authentication** over secure HTTP. Your Cloudinary **API Key** and **API Secret** are used for the authentication. You can find them in your Media Optimizer Console under **Settings > Security > API Keys**.

Try pinging the Media Optimizer servers by replacing `<API_KEY>`, `<API_SECRET>`, and `<CLOUD_NAME>` in the cURL command below:

```
curl https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/ping
```

You should see the response:

```
{
    "status": "ok"
}
```

For most actions, request parameters are appended to the URL. In a few cases, they are passed as JSON objects. The response is in a JSON snippet and includes information about the action that was performed. 

## Cache invalidation

Invalidates media that is cached internally and on the CDN. Use this if you have updated your source media and want to ensure that your Media Optimizer URLs deliver the latest versions of the media.

Method | Description
---|---
POST<code class="code-method">/invalidate | [Invalidate all caches](#invalidate_all_caches)

---

### Invalidate all caches

Invalidate all derived media that is cached internally and on the CDN.

#### Syntax

`POST /invalidate`

#### Required parameters

Parameter | Type | Description
---|---|---
urls | Array | An array of up to 20 Media Optimizer URLs to invalidate. These URLs, and any derived media from the specified assets, are invalidated. Transformation parameters can be given in the URLs, but all derived assets are invalidated, regardless.

#### Examples

Specifying two URLs to invalidate:

```curl
curl \
  -H "Content-Type: application/json" \
  -d '{          
        "urls": ["https://mycloud.mo.cloudinary.net/rest/of/the/path1.mp4", 
                 "https://mycloud.mo.cloudinary.net/rest/of/the/path2.jpg"]
  }' \ 
  -X POST \
  https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/invalidate
```

#### Sample response

The following is a sample response received:

```json
{
    "message": "ok"
}
```

## Cache warm up

Populates the cache with optimized media, ready for delivery right from the first request.

Method | Description
---|---
POST<code class="code-method">/cache_warm_up | [Warm up the cache](#warm_up_the_cache)

---

### Warm up the cache

Fetch media from its source to make it available on the CDN cache with required optimizations. This is most useful for [large images and videos](media_optimizer_transformations#transforming_large_assets) that cannot be transformed on the fly. It can also be used for transformations that take time to complete, so the derived version of the media is ready in the cache for the first request.

#### Syntax

`POST /cache_warm_up`

#### Required parameters

Parameter | Type | Description
---|---|---
url | String | The Media Optimizer URL to cache. Any default (base) transformations specified in the relevant optimization profile are applied to the cached media. You can also specify other transformations, which are handled by your mapping function, as part of the URL.

#### Optional parameters

Parameter | Type | Description
---|---|---
notification_url | String | An HTTP or HTTPS URL to receive the response (a webhook) when the derived media is available on the cache. If not specified, the response is sent to the global **Notification URL** (if defined) in the **Delivery** [Settings](media_optimizer#account_settings) of your Cloudinary Console.

#### Examples

Not including a notification URL:

```curl
curl https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/cache_warm_up -X POST --data 'url=https://mycloud.mo.cloudinary.net/rest/of/the/path.mp4?tx=t_complex'
```

#### Sample response

The following is a sample response received:

```json
{
    "url": "https://mycloud.mo.cloudinary.net/rest/of/the/path.mp4?tx=t_complex",
    "status": "processing",
    "batch_id": "6ebf1479dd8b71eb4e632620520f7347978a37ee7e30595a119c0efb957fb8c3ff96"
}
```

Including a notification URL:

```curl
curl https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/cache_warm_up -X POST --data 'url=https://mycloud.mo.cloudinary.net/rest/of/the/path.mp4?tx=t_complex&notification_url=https://mysite.example.com/my_notification_endpoint'
```

#### Sample response

The following is a sample response received at the notification URL:

```json
{
    "notification_type": "cache_warm_up",
    "timestamp": "2021-03-15T13:54:05+00:00",
    "request_id": "d113e60a52325296dbaa435b743a434b",
    "batch_id": "cff48cde900b17b00d0c52c83057ee5626e6c1806beec8d48784b4b006c54149",
    "url": "https://mycloud.mo.cloudinary.net/rest/of/the/path.mp4?tx=t_complex"
}
```

## Optimization profiles

Enables you to manage optimization profiles (formerly called delivery profiles).

Method | Description
---|---
GET <code class="code-method">/delivery_profiles | [Get all optimization profiles](#get_delivery_profiles) 
GET <code class="code-method">/delivery_profiles/:id | [Get details of an optimization profile](#get_delivery_profile_details)
POST<code class="code-method">/delivery_profiles | [Create an optimization profile](#create_a_delivery_profile)
PUT<code class="code-method">/delivery_profiles/:id | [Update an optimization profile](#update_a_delivery_profile)
DELETE<code class="code-method">/delivery_profiles/:id | [Delete an optimization profile](#delete_a_delivery_profile)

---
### Get optimization profiles

List all optimization profiles.

#### Syntax

`GET /delivery_profiles`

#### Example

```curl
curl https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/delivery_profiles
```

#### Sample response

The response contains an array of optimization profiles.

```json
[
    {
        "id": "6713839a04e70c88a9a23a0fa82b90d5",
        "display_name": "Default",
        "path_prefix": null,
        "domain_id": "b72c3a9a0ed8ad931387689b516fbccb",
        "mapping_function_id": "4d890086dd2160609ad3a7f1a2546468",
        "default_transformation": "default(auto_format_auto_quality_responsive_width)",
        "media_source_ids": [
            "5f6b45699e0104beb639934a78028f4b"
        ],
        "is_enabled": false,
        "is_default": true
    },
    {
        "id": "dd98e5785e57d7d6849f7c6678595609",
        "display_name": "my optimization profile",
        "path_prefix": "videos",
        "domain_id": "644d354ba531aba65e28af4908e8ea36",
        "mapping_function_id": "a0a4c0a642519e78f93b7480a2e13304",
        "default_transformation": "video_tx",
        "media_source_ids": [
            "2ad29ead5e268e23003fd35003566b8b"
        ],
        "is_enabled": true,
        "is_default": false
    }
]
```

---
### Get optimization profile details

Get details of a single optimization profile.

#### Syntax

`GET /delivery_profiles/:id`

#### Required parameters

| Parameter | Type | Description |
|---|---|---|---|
| id | String | The ID of the optimization profile. |

#### Examples

Get optimization profile by ID:

```curl 
curl https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/delivery_profiles/6713839a04e70c88a9a23a0fa82b90d5
```

#### Sample response 

```json
{
    "id": "6713839a04e70c88a9a23a0fa82b90d5",
    "display_name": "Default",
    "path_prefix": null,
    "domain_id": "b72c3a9a0ed8ad931387689b516fbccb",
    "mapping_function_id": "4d890086dd2160609ad3a7f1a2546468",
    "default_transformation": "default(auto_format_auto_quality_responsive_width)",
    "media_source_ids": [
        "5f6b45699e0104beb639934a78028f4b"
    ],
    "is_enabled": false,
    "is_default": true
}

```

---
### Create an optimization profile

Create a new optimization profile. Newly created optimization profiles are disabled by default.

#### Syntax

`POST /delivery_profiles`

#### Required parameters

| Parameter | Type | Description |
|---|---|---|
| display_name | String | The display name of the optimization profile. |
| domain_id | String | The ID of the domain name. |
| mapping_function_id | String | The ID of the mapping function. |
| media_source_ids | Array | An array of media source IDs. |

#### Optional parameters
| Parameter | Type | Description |
|---|---|---|
| path_prefix| String | Part of the base URL that identifies media belonging to the optimization profile.
| default_transformation | String | The name of the transformation to apply to all media in the profile.

#### Example

Create a new optimization profile:

```curl
curl \
  -H "Content-Type: application/json" \
  -d '{          
        "display_name": "new optimization profile", 
        "path_prefix": "images",
        "domain_id": "b72c3a9a0ed8ad931387689b516fbccb",
        "default_transformation": "small_image",
        "mapping_function_id": "4d890086dd2160609ad3a7f1a2546468",
        "media_source_ids": [
            "5f6b45699e0104beb639934a78028f4b"
        ]
  }' \ 
  -X POST \
  https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/delivery_profiles
```

#### Sample response

```json
{
    "id": "f5d8b763126204f0141533ba9d9facc3",
    "display_name": "new optimization profile",
    "path_prefix": "images",
    "domain_id": "b72c3a9a0ed8ad931387689b516fbccb",
    "mapping_function_id": "4d890086dd2160609ad3a7f1a2546468",
    "default_transformation": "small_image",
    "media_source_ids": [
        "5f6b45699e0104beb639934a78028f4b"
    ],
    "is_enabled": false,
    "is_default": false
}
```

---
### Update an optimization profile

Update an optimization profile.

#### Syntax

`PUT /delivery_profiles/:id`

#### Required parameters

| Parameter | Type | Description |
|---|---|---|
| id | String | The ID of the optimization profile. |

#### Optional parameters

| Parameter | Type | Description |
|---|---|---|
| display_name | String | The new display name of the optimization profile. |
| domain_id | String | The ID of the domain name. |
| mapping_function_id | String | The ID of the mapping function. |
| media_source_ids | Array | An array of media source IDs. |
| path_prefix| String | Part of the base URL that identifies media belonging to the optimization profile. |
| default_transformation | String | The name of the transformation to apply to all media in the profile. |
| is_enabled | Boolean | The enabled status of the optimization profile. |

#### Example

Update the display name of an optimization profile:

```curl
curl \
  -H "Content-Type: application/json" \
  -d '{          
        "display_name": "my new optimization profile",
        "is_enabled": true
  }' \ 
  -X PUT \
  https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/delivery_profiles/f5d8b763126204f0141533ba9d9facc3
```

#### Sample response

```json
{
    "id": "f5d8b763126204f0141533ba9d9facc3",
    "display_name": "my new optimization profile",
    "path_prefix": "images",
    "domain_id": "b72c3a9a0ed8ad931387689b516fbccb",
    "mapping_function_id": "4d890086dd2160609ad3a7f1a2546468",
    "default_transformation": "small_image",
    "media_source_ids": [
        "5f6b45699e0104beb639934a78028f4b"
    ],
    "is_enabled": true,
    "is_default": false
}
```

---

### Delete an optimization profile

Delete a single optimization profile.

> **NOTE**: You cannot delete the default optimization profile (the one that returns `"is_default": true`).

#### Syntax

`DELETE /delivery_profiles/:id`

#### Required parameters

| Parameter | Type | Description |
|---|---|---|---|
| id | String | The ID of the optimization profile to delete. |

#### Examples

Delete an optimization profile by ID:

```curl
curl  \
  -X DELETE \
  https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/delivery_profiles/f5d8b763126204f0141533ba9d9facc3
```

#### Sample response 

```json
{
    "message": "ok"
}
```

## Domains

Enables you to view your domains. You need to [create a support request](https://support.cloudinary.com/hc/en-us/requests/new) to set up a custom domain. 

Method | Description
---|---
GET <code class="code-method">/domains | [Get all domains](#get_domains) 

---
### Get domains

List all domains.

#### Syntax

`GET /domains`

#### Example

```curl
curl https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/domains
```

#### Sample response

The response contains an array of domains.

```json
[
    {
        "id": "b72c3a9a0ed8ad931387689b516fbccb",
        "domain": "mycloud.mo.cloudinary.net"
    },
    {
        "id": "d0a4c0a642519e78f93b7480a2e13304",
        "domain": "me.mydomain.com"
    }
]
```

## Mapping functions

Enables you to manage mapping functions.
Media Optimizer provides two built-in mapping functions that allow you to specify [Media Optimizer transformations](media_optimizer_transformations#supported_transformations) as part of the delivery URL (applied in addition to those defined in the optimization profile):

* **Media Optimizer**: This mapping function caters for 
  * Transformation parameters added as a query string to the delivery URL, for example: `https://mycloud.mo.cloudinary.net/rest/of/the/path.jpg?tx=c_fit,h_500,w_500` 
  * The resource type specified as a query string, overriding any determining of `resource_type` in the mapping function due to the extension given. This is particularly useful if no extension is given, for example:`https://mycloud.mo.cloudinary.net/rest/of/the/path?resource_type=image`where `resource_type` can be set to `image`, `video` or `raw`. 
* **Programmable Media**: This mapping function caters for transformation parameters within a URL, as they would be if your media source was **Cloudinary**, for example: `https://mycloud.mo.cloudinary.net/image/upload/c_fit,h_500,w_500/v1/sample.jpg`

The `template_type` values for these built-in types are `media_optimizer` and `programmable_media` respectively. When you [create your own mapping functions](#create_a_mapping_function), they get a `template_type` of `custom`. 

You can update and delete only the mapping functions that have a `template_type` of `custom`.

Method | Description
---|---
GET <code class="code-method">/mapping_functions | [Get all mapping functions](#get_mapping_functions) 
GET <code class="code-method">/mapping_functions/:id | [Get details of a mapping function](#get_mapping_function_details)
POST<code class="code-method">/mapping_functions | [Create a mapping function](#create_a_mapping_function)
PUT<code class="code-method">/mapping_functions/:id | [Update a mapping function](#update_a_mapping_function)
DELETE<code class="code-method">/mapping_functions/:id | [Delete a mapping function](#delete_a_mapping_function)

---
### Get mapping functions

List all mapping functions.

#### Syntax

`GET /mapping_functions`

#### Example

```curl
curl https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/mapping_functions
```

#### Sample response

The response contains an array of mapping functions.

```json
[
    {
        "id": "9468a72d37440570233dd41eeacc0b04",
        "display_name": "Media Optimizer",
        "template_type": "media_optimizer"
    },
    {
        "id": "63b432465f829b7fe342851bd1138447",
        "display_name": "Programmable Media",
        "template_type": "programmable_media"
    }
]
```

---
### Get mapping function details

Get details of a single mapping function.

#### Syntax

`GET /mapping_functions/:id`

#### Required parameters

| Parameter | Type | Description |
|---|---|---|---|
| id | String | The ID of the mapping function. |

#### Examples

Get mapping function by ID:

```curl 
curl https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/mapping_functions/9468a72d37440570233dd41eeacc0b04
```

#### Sample response 

```json
{
    "id": "9468a72d37440570233dd41eeacc0b04",
    "display_name": "Media Optimizer",
    "template_type": "media_optimizer"
}

```

---
### Create a mapping function

Create a new custom mapping function. 

#### Syntax

`POST /mapping_functions`

#### Required parameters

| Parameter | Type | Description |
|---|---|---|
| display_name | String | The display name of the mapping function. |
| code | String | Custom code for the mapping function.|

#### Example

Create a new mapping function:

```curl
curl \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "my new mapping function",
    "code": "function map(request, environment) {
        let transformation = environment.defaultTransformation + '\''/'\'';
        if (request.query.width && request.query.height) {
            transformation+=`w_${request.query.width},h_${request.query.height},c_limit/`;
        } 
        else if (request.query.size) {
            switch(request.query.size) {
                case '\''small'\'':transformation += '\''c_fit,h_100,w_150/'\'';
                break;
                case '\''medium'\'':transformation += '\''c_fit,h_240,w_360/'\'';
                break;
                case '\''large'\'':transformation += '\''c_fit,h_480,w_720/'\'';
                break;
            }
        }
        let path = request.path;
        if (environment.pathPrefix.length > 0) {
            path = path.slice(`/${environment.pathPrefix}/`.length);
        }
        return {
            fwd_key: path,media_key: request.path,transformation,resource_type: '\''image'\'',
        }
    }"
  }' \
  -X POST https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/mapping_functions
```

#### Sample response

```json
{
    "id": "b3f0c6094a17cf2a93e73689ae7d5830",
    "display_name": "my new mapping function",
    "code": "function map(request, environment) {\n        let transformation = environment.defaultTransformation + '/';\n        if (request.query.width && request.query.height) {\n            transformation+=`w_${request.query.width},h_${request.query.height},c_limit/`;\n        } \n        else if (request.query.size) {\n            switch(request.query.size) {\n                case 'small':transformation += 'c_fit,h_100,w_150/';\n                break;\n                case 'medium':transformation += 'c_fit,h_240,w_360/';\n                break;\n                case 'large':transformation += 'c_fit,h_480,w_720/';\n                break;\n            }\n        }\n        let path = request.path;\n        if (environment.pathPrefix.length > 0) {\n            path = path.slice(`/${environment.pathPrefix}/`.length);\n        }\n        return {\n            fwd_key: path,media_key: request.path,transformation,resource_type: 'image',\n        }\n    }",
    "template_type": "custom"
}
```

---
### Update a mapping function

Update a mapping function.

#### Syntax

`PUT /mapping_functions/:id`

#### Required parameters

| Parameter | Type | Description |
|---|---|---|
| id | String | The ID of the mapping function. |

#### Optional parameters

| Parameter | Type | Description |
|---|---|---|
| display_name | String | The new display name of the mapping function. |
| code | String | The new custom code for the mapping function.|

#### Example

Update the display name of a mapping function:

```curl
curl \
  -H "Content-Type: application/json" \
  -d '{          
        "display_name": "renamed mapping function"
  }' \ 
  -X PUT \
  https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/mapping_functions/b3f0c6094a17cf2a93e73689ae7d5830
```

#### Sample response

```json
{
    "id": "b3f0c6094a17cf2a93e73689ae7d5830",
    "display_name": "renamed mapping function",
    "code": "function map(request, environment) {\n        let transformation = environment.defaultTransformation + '/';\n        if (request.query.width && request.query.height) {\n            transformation+=`w_${request.query.width},h_${request.query.height},c_limit/`;\n        } \n        else if (request.query.size) {\n            switch(request.query.size) {\n                case 'small':transformation += 'c_fit,h_100,w_150/';\n                break;\n                case 'medium':transformation += 'c_fit,h_240,w_360/';\n                break;\n                case 'large':transformation += 'c_fit,h_480,w_720/';\n                break;\n            }\n        }\n        let path = request.path;\n        if (environment.pathPrefix.length > 0) {\n            path = path.slice(`/${environment.pathPrefix}/`.length);\n        }\n        return {\n            fwd_key: path,media_key: request.path,transformation,resource_type: 'image',\n        }\n    }",
    "template_type": "custom"
}
```

---

### Delete a mapping function

Delete a single mapping function.

#### Syntax

`DELETE /mapping_functions/:id`

#### Required parameters

| Parameter | Type | Description |
|---|---|---|---|
| id | String | The ID of the mapping function to delete. |

#### Examples

Delete a mapping function by ID:

```curl
curl  \
  -X DELETE \
  https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/mapping_functions/b3f0c6094a17cf2a93e73689ae7d5830
```

#### Sample response 

```json
{
    "message": "ok"
}
```

## Media sources

Enables you to manage media sources.

Method | Description
---|---
GET <code class="code-method">/media_sources | [Get all media sources](#get_media_sources) 
GET <code class="code-method">/media_sources/:id | [Get details of a media source](#get_media_source_details)
POST<code class="code-method">/media_sources | [Create a media source](#create_a_media_source)
PUT<code class="code-method">/media_sources/:id | [Update a media source](#update_a_media_source)
DELETE<code class="code-method">/media_sources/:id | [Delete a media source](#delete_a_media_source)

---
### Get media sources

List all media sources.

#### Syntax

`GET /media_sources`

#### Example

```curl
curl https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/media_sources
```

#### Sample response

The response contains an array of media sources.

```json
[
    {
        "id": "5f6b45699e0104beb639934a78028f4b",
        "display_name": "my first web media source",
        "uri_type": "web",
        "config": {
            "web_uri_base": "https://mysite.com",
            "web_headers": {},
            "web_uri_template": "{{fwd_key}}"
        }
    },
    {
        "id": "9ee6d5cace98b0e261e44d7ddeffcd76",
        "display_name": "my s3 media source",
        "uri_type": "s3",
        "config": {
            "s3_bucket_name": "my s3 bucket name",
            "s3_bucket_folder": "my s3 bucket folder",
            "s3_uri_template": "s3://mybucket/images/{{vars.signature}}/{{fwd_key}}"
        }
    },
    {
        "id": "cad29ead5e268e23003fd35003566b8b",
        "display_name": "http media source",
        "uri_type": "http",
        "config": {}
    }
]
```

---
### Get media source details

Get details of a single media source.

#### Syntax

`GET /media_sources/:id`

#### Required parameters

| Parameter | Type | Description |
|---|---|---|---|
| id | String | The ID of the media source. |

#### Examples

Get media source by ID:

```curl 
curl https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/media_sources/5f6b45699e0104beb639934a78028f4b
```

#### Sample response 

```json
{
    "id": "5f6b45699e0104beb639934a78028f4b",
    "display_name": "my first web media source",
    "uri_type": "web",
    "config": {
        "web_uri_base": "https://mysite.com",
        "web_headers": {},
        "web_uri_template": "{{fwd_key}}"
    }
}

```

---
### Create a media source

Create a new media source configuration, allowing Media Optimizer to connect to a media source.

#### Syntax

`POST /media_sources`

#### Required parameters

| Parameter | Type | Description |
|---|---|---|---|
| display_name | String | The display name of the media source configuration. |
| uri_type | String | The [type of media source](media_optimizer_configuration#types_of_media_sources).**Possible values**: `http`, `s3`, `gs`, `web`, `cloudinary` |
| config | JSON | Configuration parameters required for the type of media source.**http**: Not applicable.**s3** - see [AWS S3 settings](media_optimizer_configuration#aws_s3_settings) for details of each parameter:`s3_bucket_name``s3_bucket_folder``s3_access_key``s3_secret_key``s3_uri_template`**gs** - see [Google storage settings](media_optimizer_configuration#google_storage_settings) for details of each parameter:`gs_bucket_name``gs_bucket_folder``gs_service_account_key``gs_uri_template`**web** - see [Web address settings](media_optimizer_configuration#web_address_settings) for details of each parameter:`web_uri_base``web_headers``web_uri_template`**cloudinary** - see [Cloudinary settings](media_optimizer_configuration#cloudinary_settings) for details of the parameter:`cld_cloud_name`

#### Example

Create an S3 media source configuration:

```curl
curl \
  -H "Content-Type: application/json" \
  -d '{          
        "display_name": "new s3 ms", 
        "uri_type": "s3",
        "config": {
            "s3_bucket_name": "my_bucket_name",
            "s3_bucket_folder":"my_bucket_folder",
            "s3_access_key":"123123",
            "s3_uri_template": "my.uri.template.com"
        }
  }' \ 
  -X POST \
  https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/media_sources
```

#### Sample response

```json
{
    "id": "ad4adf9b9c3e560831228d2b53e4952d",
    "display_name": "new s3 ms",
    "uri_type": "s3",
    "config": {
        "s3_bucket_name": "my_bucket_name",
        "s3_bucket_folder":"my_bucket_folder",
        "s3_access_key":"encrypted",
        "s3_uri_template": "my.uri.template.com"
    }
}
```

---
### Update a media source

Update a single media source configuration.

#### Syntax

`PUT /media_sources/:id`

#### Required parameters

| Parameter | Type | Description |
|---|---|---|---|
| id | String | The ID of the media source configuration. |

#### Optional parameters

You only need to specify parameters that you want to update, however, if updating one of the `config` parameters, you must supply all those required for the `uri_type`.

| Parameter | Type | Description |
|---|---|---|---|
| display_name | String | The new display name of the media source. |
| uri_type | String | The [type of media source](media_optimizer_configuration#types_of_media_sources).**Possible values**: `http`, `s3`, `gs`, `web`, `cloudinary` |
| config | JSON | Configuration parameters required for the type of media source.**http**: Not applicable.**s3** - see [AWS S3 settings](media_optimizer_configuration#aws_s3_settings) for details of each parameter:`s3_bucket_name``s3_bucket_folder``s3_access_key``s3_secret_key``s3_uri_template`**gs** - see [Google storage settings](media_optimizer_configuration#google_storage_settings) for details of each parameter:`gs_bucket_name``gs_bucket_folder``gs_service_account_key``gs_uri_template`**web** - see [Web address settings](media_optimizer_configuration#web_address_settings) for details of each parameter:`web_uri_base``web_headers``web_uri_template`**cloudinary** - see [Cloudinary settings](media_optimizer_configuration#cloudinary_settings) for details of the parameter:`cld_cloud_name`

#### Examples

Update the display name of a media source configuration:

```curl
curl \
  -H "Content-Type: application/json" \
  -d '{          
        "display_name": "new s3 media source"
  }' \ 
  -X PUT \
  https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/media_sources/ad4adf9b9c3e560831228d2b53e4952d
```

#### Sample response

```json
{
    "id": "a54ff9e93ddb98bb3291ab6538b229d1",
    "display_name": "new s3 media source",
    "uri_type": "s3",
    "config": {
        "s3_bucket_name": "my_bucket_name",
        "s3_bucket_folder":"my_bucket_folder",
        "s3_access_key":"encrypted",
        "s3_uri_template": "my.uri.template.com"
    }
}
```

Update one of the configuration parameters of a media source configuration:

```curl
curl \
  -H "Content-Type: application/json" \
  -d '{          
        "config": {
            "s3_bucket_name": "my_bucket_name",
            "s3_bucket_folder":"my_new_bucket_folder",
            "s3_access_key":"123123",
            "s3_uri_template": "my.uri.template.com"
        }
  }' \ 
  -X PUT \
  https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/media_sources/ad4adf9b9c3e560831228d2b53e4952d
```

#### Sample response

```json
{
    "id": "a54ff9e93ddb98bb3291ab6538b229d1",
    "display_name": "new s3 media source",
    "uri_type": "s3",
    "config": {
        "s3_bucket_name": "my_bucket_name",
        "s3_bucket_folder":"my_new_bucket_folder",
        "s3_access_key":"encrypted",
        "s3_uri_template": "my.uri.template.com"
    }
}
```

---

### Delete a media source

Delete a single media source configuration.

#### Syntax

`DELETE /media_sources/:id`

#### Required parameters

| Parameter | Type | Description |
|---|---|---|---|
| id | String | The ID of the media source to delete. |

#### Examples

Delete a media source configuration by ID:

```curl
curl  \
  -X DELETE \
  https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/media_sources/a54ff9e93ddb98bb3291ab6538b229d1
```

#### Sample response 

```json
{
    "message": "ok"
}
```

## Ping

Tests the reachability of the Media Optimizer API.

Method | Description
---|---
GET<code class="code-method">/ping | [Ping Media Optimizer servers](#ping_media_optimizer_servers)

---
### Ping Media Optimizer servers

Check that the Media Optimizer API is reachable and accepting requests.

#### Syntax

`GET /ping`

#### Example

```curl
curl https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/ping
```

#### Sample response

The response contains the current status of the Media Optimizer servers.

```json
{
    "status": "ok"
}

```

## Transformations

Enables you to manage named [transformations](media_optimizer_transformations).

Method | Description
---|---
GET <code class="code-method">/transformations | [Get all transformations](#get_transformations) 
GET <code class="code-method">/transformations/:transformation_name | [Get details of a transformation](#get_transformation_details)
POST<code class="code-method">/transformations/:transformation_name | [Create a named transformation](#create_a_named_transformation)
PUT<code class="code-method">/transformations/:transformation_name | [Update a transformation](#update_a_transformation)
DELETE<code class="code-method">/transformations/:transformation_name | [Delete a transformation](#delete_a_transformation)

---

### Get transformations

List all transformations.

#### Syntax

`GET /transformations`

#### Optional parameters

| Parameter | Type | Description |
|---|---|---|---|
| max\_results | Integer | Maximum number of transformations to return (up to 500). Default: `10`.  |
| next\_cursor | String | When a request has more results to return than `max_results`, the `next_cursor` value is returned as part of the response. You can then specify this value as the `next_cursor` parameter of a following request. |

#### Examples

List all transformations, returning two at a time:

```curl
curl https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/transformations?max_results=2
```

#### Sample response

The response contains an array of transformations. If the number of transformations exceeds the `max_results` value, the `next_cursor` parameter is also returned. You can specify this value as the `next_cursor` parameter of the following listing request.

```json
{
    "transformations": [
        {
            "name": "t_auto_format_auto_quality_responsive_width",
            "transformation": "f_auto,q_auto,w_responsive"
        },
        {
            "name": "t_media_lib_thumb",
            "transformation": "c_limit,h_100,w_150"
        }
    ],
    "next_cursor": "8edbc61040178db60b0973ca9494bf3a"
}
```

---
### Get transformation details

Get details of a single transformation.

#### Syntax

`GET /transformations/:transformation_name`

#### Required parameters

| Parameter | Type | Description |
|---|---|---|---|
| transformation_name | String | The name of the transformation. |

#### Examples

Get transformation by name:

```curl 
curl https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/transformations/media_lib_thumb
```

#### Sample response 

```json
{
    "name": "t_media_lib_thumb",
    "transformation": "c_limit,h_100,w_150",
    "info": [
        {
            "height": 100,
            "width": 150,
            "crop": "limit"
        }
    ]
}

```

---
### Create a named transformation

Create a new named transformation.

#### Syntax

`POST /transformations/:transformation_name`

#### Required parameters

| Parameter | Type | Description |
|---|---|---|---|
| transformation_name | String | The name of the transformation. |
| transformation | String | The transformation parameters. |

#### Examples

Create a named transformation:

```curl
curl \
  -d 'transformation=c_fill,h_100,w_150' \
  -X POST \
  https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/transformations/small_fill
```

#### Sample response

```json
{
    "message": "created"
}
```

---
### Update a transformation

Update a single transformation.

#### Syntax

`PUT /transformations/:transformation_name`

#### Required parameters

| Parameter | Type | Description |
|---|---|---|---|
| transformation_name | String | The name of the transformation. |
| transformation | String | The new transformation parameters. |

#### Examples

Update the `small_fill` transformation to a specify a different height:

```curl
curl \
  -d 'transformation=c_fill,h_150,w_150' \
  -X PUT \
  https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/transformations/small_fill
```

#### Sample response

```json
{
    "message": "updated"
}
```

---

### Delete a transformation

Delete a single transformation.

> **NOTE**: Deleting a transformation also deletes all the derived images based on this transformation (up to 1000). The method returns an error if there are more than 1000 derived images based on this transformation.

#### Syntax

`DELETE /transformations/:transformation_name`

#### Required parameters

| Parameter | Type | Description |
|---|---|---|---|
| transformation_name | String | The name of the transformation or the transformation parameters. |

#### Examples

Delete transformation by name:

```curl
curl  \
  -X DELETE \
  https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/transformations/small_fill
```

#### Sample response 

```json
{
    "message": "deleted"
}
```

## Usage

Enables you to get a report on the status of your Media Optimizer account usage details. 

Method | Description
---|---
GET<code class="code-method">/usage | [Get account usage details](#get_account_usage_details)

---
### Get account usage details

Get your Media Optimizer account usage details.

#### Syntax

`GET /usage`

#### Optional parameters

Parameter | Type | Description 
---|---|---
date | String |  The date for the usage report. Must be within the last three months and given in the format: `dd-mm-yyyy`. **Default**: the current date.

#### Examples

Return a usage report for the 21st of February, 2021 (21-02-2021):

```curl
curl https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/usage?date=21-02-2021
```

#### Sample response

The response contains your Media Optimizer usage.

```json
{
    "plan": "Plus PAYG",
    "last_updated": "2021-02-21",
    "transformations": {
        "usage": 0,
        "credits_usage": 0.0
    },
    "bandwidth": {
        "usage": 0,
        "credits_usage": 0.0
    },
    "credits": {
        "usage": 0.0,
        "limit": 225.0,
        "used_percent": 0.0
    },
    "requests": 0,
    "media_limits": {
        "image_max_size_bytes": 20971520,
        "video_max_size_bytes": 524288000,
        "raw_max_size_bytes": 20971520,
        "image_max_px": 25000000,
        "asset_max_total_px": 100000000
    }
}

```