# Media Delivery API

The Media Delivery API allows for accessing the Umbraco media items in a headless manner. This API applies many of the same concepts as its content counterpart, although with fewer options. If you haven't already, familiarize yourself with the [Content Delivery API](https://docs.umbraco.com/umbraco-cms/reference/content-delivery-api) before reading this article.

{% hint style="info" %}
The Media Delivery API specification is created to mimic that of the Content Delivery API. However, the default implementation of this specification is limited and does not support the entire specification.

Unlike the Content Delivery API, the Media Delivery API does not feature an extension model for querying.

The reasoning behind is that third-party media systems might support a complete implementation of the specification. If the demand rises, the default implementation might eventually cover the entire specification.
{% endhint %}

## Getting Started

To use the Media Delivery API you must first enable it. Even if the Content Delivery API is enabled, the Media Delivery API remains disabled by default.

The Media Delivery API is enabled by adding the `Media` section to the `DeliveryApi` configuration in `appsettings.json`:

{% code title="appsettings.json" %}

```json
{
    "Umbraco": {
        "CMS": {
            "DeliveryApi": {
                "Enabled": true,
                "PublicAccess": true,
                "Media": {
                    "Enabled": true,
                    "PublicAccess": false
                }
            }
        }
    }
}
```

{% endcode %}

As this configuration sample illustrates, it is possible to restrict public access to media independently from content. As with the Content Delivery API, media is publicly accessible by default when the Media Delivery API is enabled.

{% hint style="info" %}
The `Media` configuration can only become more restrictive than the `DeliveryApi` configuration:

* If `DeliveryApi:Enabled` is `false`, the `DeliveryApi:Media:Enabled` configuration option has no effect. The Media Delivery API cannot be enabled on its own.
* If `DeliveryApi:PublicAccess` is `false`, the `DeliveryApi:Media:PublicAccess` configuration option has no effect. The Media Delivery API cannot be publicly available if the Content Delivery API is not.
  {% endhint %}

## Endpoints

The Media Delivery API can either be queried for a specific media item or a paged list of multiple items.

{% hint style="info" %}
In the Media Delivery API, `id` parameters always refer to media item keys (`Guid`), not node ids (`integer`).
{% endhint %}

## Gets a media item by id

<mark style="color:blue;">`GET`</mark> `/umbraco/delivery/api/v2/media/item/{id}`

Returns a single item.

#### Path Parameters

| Name                                 | Type   | Description            |
| ------------------------------------ | ------ | ---------------------- |
| id<mark style="color:red;">\*</mark> | String | GUID of the media item |

#### Query Parameters

| Name   | Type   | Description                                                                            |
| ------ | ------ | -------------------------------------------------------------------------------------- |
| expand | String | Which properties to expand in the response                                             |
| fields | String | Which properties to include in the response (*by default all properties are included*) |

#### Headers

| Name    | Type   | Description  |
| ------- | ------ | ------------ |
| Api-Key | String | Access token |

{% tabs %}
{% tab title="200: OK Media item" %}

{% endtab %}

{% tab title="401: Unauthorized Missing permissions after protection is set up" %}

{% endtab %}

{% tab title="404: Not Found Media item not found" %}

{% endtab %}
{% endtabs %}

## Gets a media item by path

<mark style="color:blue;">`GET`</mark> `/umbraco/delivery/api/v2/media/item/{path}`

Returns a single item.

#### Path Parameters

| Name                                   | Type   | Description                                                                                                                                                               |
| -------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| path<mark style="color:red;">\*</mark> | String | <p>Path of the media item. The path is composed by the names of any ancestor folders and the name of the media item itself, separated by</p><p><code>/</code></p><p>.</p> |

#### Query Parameters

| Name   | Type   | Description                                                                            |
| ------ | ------ | -------------------------------------------------------------------------------------- |
| expand | String | Which properties to expand in the response                                             |
| fields | String | Which properties to include in the response (*by default all properties are included*) |

#### Headers

| Name    | Type   | Description  |
| ------- | ------ | ------------ |
| Api-Key | String | Access token |

{% tabs %}
{% tab title="200: OK Media item" %}

{% endtab %}

{% tab title="401: Unauthorized Missing permissions after protection is set up" %}

{% endtab %}

{% tab title="404: Not Found Media item not found" %}

{% endtab %}
{% endtabs %}

## Gets media item(s) by id

<mark style="color:blue;">`GET`</mark> `/umbraco/delivery/api/v2/media/items`

Returns single or multiple items by id.

#### Query Parameters

| Name                                 | Type         | Description                                                                            |
| ------------------------------------ | ------------ | -------------------------------------------------------------------------------------- |
| id<mark style="color:red;">\*</mark> | String Array | GUIDs of the media items                                                               |
| expand                               | String       | Which properties to expand in the response                                             |
| fields                               | String       | Which properties to include in the response (*by default all properties are included*) |

#### Headers

| Name    | Type   | Description  |
| ------- | ------ | ------------ |
| Api-Key | String | Access token |

{% tabs %}
{% tab title="200: OK List of media items" %}

{% endtab %}

{% tab title="401: Unauthorized Missing permissions after protection is set up" %}

{% endtab %}
{% endtabs %}

## Gets media item(s) from a query

<mark style="color:blue;">`GET`</mark> `/umbraco/delivery/api/v2/media`

Returns single or multiple items.

#### Query Parameters

| Name                                    | Type         | Description                                                                                                                                                                                                            |
| --------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| fetch<mark style="color:red;">\*</mark> | String       | <p>Structural query string option (e.g. <code>ancestors</code>, <code>children</code>, <code>descendants</code>).</p><p><strong>Note:</strong> The default API implementation only supports <code>children</code>.</p> |
| filter                                  | String Array | Filtering query string options (e.g. `mediaType`, `name`)                                                                                                                                                              |
| sort                                    | String Array | Sorting query string options (e.g. `createDate`, `name`, `sortOrder`, `updateDate`)                                                                                                                                    |
| skip                                    | Integer      | Amount of items to skip                                                                                                                                                                                                |
| take                                    | Integer      | Amount of items to take                                                                                                                                                                                                |
| expand                                  | String       | Which properties to expand in the response                                                                                                                                                                             |
| fields                                  | String       | Which properties to include in the response (*by default all properties are included*)                                                                                                                                 |

#### Headers

| Name    | Type   | Description  |
| ------- | ------ | ------------ |
| Api-Key | String | Access token |

{% tabs %}
{% tab title="200: OK Paginated list of media items" %}

{% endtab %}

{% tab title="400: Bad Request Invalid request" %}

{% endtab %}
{% endtabs %}

### Request samples

Fetch a media item by its ID:

```http
GET /umbraco/delivery/api/v2/media/item/3fa85f64-5717-4562-b3fc-2c963f66afa6
```

Fetch a media item inside a folder structure by its full path, and expand its `author` property:

```http
GET /umbraco/delivery/api/v2/media/item/root level folder/child folder/media item name/&expand=property:author
```

Fetch two media items by their ids:

```http
GET /umbraco/delivery/api/v2/media/item?id=11178b4f-f8e2-4686-9697-6d990851a081&id=7cd00706-de93-4db8-8fc2-4b20e8419c30
```

Fetch the first 10 media items of type `Image` at root level. Return the found items sorted by name ascending:

```http
GET /umbraco/delivery/api/v2/media?fetch=children:/&filter=mediaType:Image&sort=name:asc&skip=0&take=10
```

Fetch the first 5 media items inside a folder structure. Return only items of type `Image` whose item names contain "size".

```http
GET /umbraco/delivery/api/v2/media?fetch=children:/root level folder/child folder/&filter=mediaType:Image&filter=name:size&skip=0&take=5
```

## Media item JSON structure

The Media Delivery API outputs the JSON structure outlined below to represent media items:

* Item `path`, `createDate`, `updateDate`, `id`, `name`, and `mediaType` are always included in the response.
* `url`, `extension` and the size in `bytes` are included for all files (not for folders).
* `width` and `height` (in pixels) are included for most images.
* Depending on Umbraco Data Type configuration, `focalPoint` and `crops` are included for most images.
* Additional editorial properties from the media type can be found in the `properties` collection.

```json
{
    "path": "string",
    "createDate": "2023-08-22T08:13:57.510Z",
    "updateDate": "2023-08-22T08:13:57.510Z",
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "string",
    "mediaType": "string",
    "url": "string",
    "extension": "string",
    "width": 0,
    "height": 0,
    "bytes": 0,
    "properties": {
        "property1Alias": "string",
        "property2Alias": 0,
        "property3Alias": true,
        "property4Alias": [],
        "property5Alias": {},
        "property6Alias": null
    },
    "focalPoint": {
        "left": 0,
        "top": 0
    },
    "crops": [
        {
            "alias": "string",
            "width": 0,
            "height": 0,
            "coordinates": {
                "x1": 0,
                "y1": 0,
                "x2": 0,
                "y2": 0
            }
        }
    ]
}
```