Media Delivery API
Using the Media Delivery API.
Last updated
Using the Media Delivery API.
Last updated
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, please familiarize yourself with the before reading this article.
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:
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.
The Media Delivery API can either be queried for a specific media item or a paged list of multiple items.
GET /umbraco/delivery/api/v2/media/item/{id}
Returns a single item.
id*
String
GUID of the media item
expand
String
Which properties to expand in the response
fields
String
Which properties to include in the response (by default all properties are included)
Api-Key
String
Access token
GET /umbraco/delivery/api/v2/media/item/{path}
Returns a single item.
path*
String
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
/
.
expand
String
Which properties to expand in the response
fields
String
Which properties to include in the response (by default all properties are included)
Api-Key
String
Access token
GET /umbraco/delivery/api/v2/media/items
Returns single or multiple items by id.
id*
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)
Api-Key
String
Access token
GET /umbraco/delivery/api/v2/media
Returns single or multiple items.
fetch*
String
Structural query string option (e.g. ancestors, children, descendants).
Please note: The default API implementation only supports children.
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)
Api-Key
String
Access token
Fetch a media item by its ID:
Fetch a media item inside a folder structure by its full path, and expand its author property:
Fetch two media items by their ids:
Fetch the first 10 media items of type Image at root level. Return the found items sorted by name ascending:
Fetch the first 5 media items inside a folder structure. Return only items of type Image whose item names contain "size".
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.