Media Delivery API
Using the 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, please familiarize yourself with the Content Delivery API before reading this article.
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.
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
Mediasection to the
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.
Mediaconfiguration can only become more restrictive than the
DeliveryApi:Media:Enabledconfiguration option has no effect. The Media Delivery API cannot be enabled on its own.
DeliveryApi:Media:PublicAccessconfiguration option has no effect. The Media Delivery API cannot be publicly available if the Content Delivery API is not.
The Media Delivery API can either be queried for a specific media item or a paged list of multiple items.
In the Media Delivery API,
idparameters always refer to media item keys (
Guid), not node ids (
Gets a media item by id
Gets a media item by path
Gets media item(s) by id
Gets media item(s) from a query
Fetch a media item by its ID:
Fetch a media item inside a folder structure by its full path, and expand its
GET /umbraco/delivery/api/v1/media/item/root level folder/child folder/media item name/&expand=property:author
Fetch two media items by their ids:
Fetch the first 10 media items of type
Imageat 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
Imagewhose item names contain "size".
GET /umbraco/delivery/api/v1/media?fetch=children:/root level folder/child folder/&filter=mediaType:Image&filter=name:size&skip=0&take=5
The Media Delivery API outputs the JSON structure outlined below to represent media items:
mediaTypeare always included in the response.
extensionand the size in
bytesare included for all files (not for folders).
height(in pixels) are included for most images.
- Depending on Umbraco Data Type configuration,
cropsare included for most images.
- Additional editorial properties from the media type can be found in the