Media items
A media item is an uploaded asset, plus the description and metadata associated with it. It aligns with the data model. You can use query attributes to control the set of items returned. Before you start working with media items, you must authenticate.
Note
The base URL for uploading media assets is https://mms-upload.sitecorecloud.io and the base URL for retrieving media assets is https://mms-delivery.sitecorecloud.io.
Important
Search and filter attributes are applicable when working with the Delivery API only.
Get a list of media items
Use this method to retrieve a list of media items. If you don't specify any filtering attributes, you will retrieve all available media items.
RequestResponse
curl --location '<BASE_URL>/api/content/v1/media' \
--header 'Authorization: <BEARER_TOKEN> ' \
RequestResponse
{
"totalCount": 20,
"pageSize": 1,
"pageNumber": 1,
"data": [
{
"id": "GGp18w-IlkuCtj7A3G0i3g",
"name": "ONEDERLUST logo",
"description": "",
"file": {
"name": null,
"type": "image/png",
"size": 4984,
"link": {
"type": "Link",
"relatedType": "File",
"id": "eae2e642ab564a53a58b0a1df4f8468a",
"uri": " <BASE_URL> /api/media/v2/delivery/2646a967-f206-420a-a26d-08db60f70205/eae2e642ab564a53a58b0a1df4f8468a"
},
"dimensions": {
"width": 512,
"height": 54
}
},
"system": {
"lastPublishProgress": {
"type": "Publish",
"status": "Completed",
"triggeredBy": {
"type": "Link",
"relatedType": "User",
"id": "[email protected]",
"uri": " <BASE_URL> /api/content/v1/users/[email protected]"
},
"triggeredAt": "2023-06-12T18:32:07.5326643Z"
},
"type": "Media",
"version": "qecHTVZ1bh6BBcS7lrNzN06ZIgui6zLhx4pUd9VppaQ=",
"status": "Published",
"createdBy": {
"type": "Link",
"relatedType": "User",
"id": "[email protected]",
"uri": " <BASE_URL> /api/content/v1/users/[email protected]"
},
"createdAt": "2023-06-12T18:31:21.0978878Z",
"updatedBy": {
"type": "Link",
"relatedType": "User",
"id": "[email protected]",
"uri": " <BASE_URL> /api/content/v1/users/[email protected]"
},
"updatedAt": "2023-06-12T18:33:10.0717148Z",
"publishedBy": {
"type": "Link",
"relatedType": "User",
"id": "[email protected]",
"uri": " <BASE_URL>/api/content/v1/users/[email protected]"
},
"publishedAt": "2023-06-12T18:33:10.0710026Z"
}
}
]
}
Other request examples
You can include query parameters to control the set of items returned as shown in the following examples.
Example of an ID query for a single item
RequestResponse
curl --location '<BASE_URL>/api/content/v1/media/1hMfKvVIcE2yBcKuN3_8vg' \
--header 'Authorization: <BEARER_TOKEN>' \
--data ''Example of an ID query for multiple items
RequestResponse
curl --location '<BASE_URL>/api/content/v1/media?italy%7Cireland%7Cvietnam=null' \
--header 'Authorization: <BEARER_TOKEN>' \
--data ''Example of a search query
RequestResponse
curl --location '<BASE_URL>/api/content/v1/media?search=italy' \
--header 'Authorization: <BEARER_TOKEN>' \
--data ''Example of a sortBy query:
RequestResponse
curl --location '<BASE_URL>/api/content/v1/media?sortBy=system.updatedAt' \
--header 'Authorization: <BEARER_TOKEN>'Get all references to a media item
Use this method to get a list of all content items that reference a specific media item. This request uses the linkedTo query attribute and retrieves all the items that reference the media item with the ID travelLuxuryInn.
RequestResponse
curl --location '<BASE_URL>/api/content/v1/media/?linkedTo=1hMfKvVIcE2yBcKuN3_8vg' \
--header 'Authorization: <BEARER_TOKEN>
--data ''--data
RequestResponse
{
"totalCount": 1,
"pageSize": 20,
"pageNumber": 1,
"data": [
{
"system": {
"updatedAt": "2023-09-15T17:36:53.8382887Z",
"contentType": {
"type": "Link",
"relatedType": "ContentType",
"id": "hotels",
"uri": "<BASE_URL>/api/content/v1/types/hotels"
},
"lastPublishProgress": {
"type": "Publish",
"status": "Completed",
"triggeredBy": {
"type": "Link",
"relatedType": "User",
"id": "[email protected]",
"uri": "<BASE_URL>/api/content/v1/users/[email protected]"
},
"triggeredAt": "2023-09-15T17:37:06.0646689Z"
},
"type": "Content",
"version": "Vfn2miqzk6NkMPjBL64+MXDt2hQWUUoVf485WKwMijI=",
"status": "Published",
"createdBy": {
"type": "Link",
"relatedType": "User",
"id": "",
"uri": "<BASE_URL>/api/content/v1/users/"
},
"createdAt": "2023-06-08T13:15:03.6540984Z",
"updatedBy": {
"type": "Link",
"relatedType": "User",
"id": "[email protected]",
"uri": "<BASE_URL>/api/content/v1/users/[email protected]"
},
"publishedBy": {
"type": "Link",
"relatedType": "User",
"id": "[email protected]",
"uri": "<BASE_URL>/api/content/v1/users/[email protected]"
},
"publishedAt": "2023-09-15T17:38:06.9267629Z"
},
"id": "luxuryInn",
"name": "Luxury-Inn",
"fields": {
"industry": {
"value": "travel",
"type": "ShortText"
},
"shortDescription": {
"value": "Luxury-Inn is a highly esteemed hotel with a long history and impressive design. It first opened in 1913 and has since undergone modern updates while still maintaining its grand and elegant style. The hotel offers top-notch amenities, including a spa with an infinity pool, a tea room, and a sauna. With 42 suites to choose from, the Royal Suite stands out as the most lavish option, spanning 320 square meters. ",
"type": "LongText"
},
"description": {
"value": {
"type": "doc",
"content": [
{
"type": "paragraph",
"content": [
{
"type": "text",
"text": "As a strong contender for the grandest hotel, Luxury-Inn boasts a rich history and stunning décor combined with first rate amenities. This establishment originally opened its doors in 1913 and although the amenities have been modernised over the years, much of the imposing and regal style has been preserved. The spa is the perfect place to unwind in style as it comes complete with an infinity edged swimming pool, a team room and a sauna. There are 42 different suites to choose from, which the 320 square metre Royal Suite being the grandest of them all. "
}
]
}
]
},
"type": "RichText"
},
"pricePerNight": {
"value": 100,
"type": "Integer"
},
"ratingstars": {
"value": 4,
"type": "Integer"
},
"amenities": {
"value": [
{
"id": "airConditioning"
},
{
"id": "wifi"
},
{
"id": "wheelchairAccessible"
}
],
"type": "Select"
},
"roomType": {
"value": [],
"type": "Select"
},
"relatedItems": {
"value": [
{
"type": "Link",
"relatedType": "Content",
"id": "japan",
"uri": " <BASE_URL> /api/content/v1/items/japan"
}
],
"type": "Reference"
},
"heroImage": {
"value": [
{
"type": "Link",
"relatedType": "Media",
"id": "travelLuxuryInn",
"uri": " <BASE_URL>/api/content/v1/media/travelLuxuryInn"
}
],
"type": "Media"
}
}
}
]
}
Get a media item using the ID
Use this method to retrieve a media item with a specific ID. For a list of media item IDs, run the GET api/content/v1/types method or open the media item details page. This request returns a media item with the ID of travelJapan2Weeks.
RequestResponse
curl --location '<BASE_URL>/api/content/v1/media/travelJapan2Weeks'RequestResponse
{
"id": "travelJapan2Weeks",
"name": "Japan for 2 weeks ",
"description": "Enjoy a beautiful two-week tour of Japan.",
"file": {
"name": null,
"type": "image/jpeg",
"size": 415462,
"link": {
"type": "Link",
"relatedType": "File",
"id": "f2f232e53743492e8101f1e30e0795a7",
"uri": " <BASE_URL> /api/media/v2/delivery/2646a967-f206-420a-a26d-08db60f70205/f2f232e53743492e8101f1e30e0795a7"
},
"dimensions": {
"width": 1360,
"height": 910
}
},
"system": {
"lastPublishProgress": {
"type": "Publish",
"status": "Completed",
"triggeredBy": {
"type": "Link",
"relatedType": "User",
"id": "[email protected]",
"uri": " <BASE_URL>/api/content/v1/users/[email protected]"
},
"triggeredAt": "2023-06-09T18:50:45.3227325Z"
},
"type": "Media",
"version": "W/mdEuGAAHFZ8hfm6R8srrOdg8HV+1EShopdVoVJQ48=",
"status": "Published",
"createdBy": null,
"createdAt": "2023-06-08T13:14:56.2041932Z",
"updatedBy": {
"type": "Link",
"relatedType": "User",
"id": "[email protected]",
"uri": " <BASE_URL>/api/content/v1/users/[email protected]"
},
"updatedAt": "2023-06-09T18:51:46.6998798Z",
"publishedBy": {
"type": "Link",
"relatedType": "User",
"id": "[email protected]",
"uri": " <BASE_URL>/api/content/v1/users/[email protected]"
},
"publishedAt": "2023-06-09T18:51:46.69835Z"
}
}Create a media item
Use this method to create a media item.
Before you begin
RequestResponse
curl --location ' <BASE_URL>/api/content/v1/media' \
--header 'Content-Type: application/json' \
--header 'Authorization: <BEARER_TOKEN>' \
--data '{
"name": "Istanbul",
"description": "Enjoy the beauty and colors of Istanbul.",
"fileId": "b6c45c02f0e942f898898b9f5de2e04c"
}'
Note
The fileId is auto-generated for a media item when you generate the upload link. You cannot change this identifier.
RequestResponse
{
"id": "b6c45c02f0e942f898898b9f5de2e04c",
"name": "Istanbul",
"description": "Enjoy the beauty and colors of Istanbul.",
"file": null,
"system": {
"lastPublishProgress": null,
"type": "Media",
"version": "Wc6p9e1Oe/X3ehNerdJELRw0KJ9lJTM2puck/oO6tCY=",
"status": "Draft",
"createdBy": {
"type": "Link",
"relatedType": "User",
"id": "[email protected]",
"uri": " <BASE_URL>/api/content/v1/users/[email protected]"
},
"createdAt": "2023-06-13T10:51:48.9901577Z",
"updatedBy": {
"type": "Link",
"relatedType": "User",
"id": "[email protected]",
"uri": " <BASE_URL>/api/content/v1/users/[email protected]"
},
"updatedAt": "2023-06-13T10:51:48.9901577Z",
"publishedBy": null,
"publishedAt": null
}
}
Update a media item
Use this method to update the description for a media item with a specific ID. This request updates the description of the media item with the ID 1hMfKvVIcE2yBcKuN3_8vg.
RequestResponse
curl --location --request PUT '<BASE_URL>/api/content/v1/media/1hMfKvVIcE2yBcKuN3_8vg' \
--header 'Content-Type: application/json' \
--header 'Authorization: <BEARER_TOKEN>' \
--data '{
"name": "demo-image.png6f0ba7a3a0534d5d85de536796838be66f0ba7a3a0534d5d85de536796838be66f0ba7a3a0534d5d85de536796838be66f0ba7a3a0534d5d85de536796838be66f0ba7a3a0534d5d85de536796838be66f0ba7a3a0534d5d85de536796838be67a3a0534d5d85de53679683d5d85de536796838be66f0ba7a3a0534d5d85de536796838be66f0ba7a3a0534d5d85de536796838be66f0ba7a3a0534d5d85de536796838be66f0ba7a3a0534d5d85de536796838be66f0ba7a3a0534d5d85de536796838be6demo-image.png6f0ba7a3a0534d5d85de536796838be666838be66f0ba7a3a0534d5d85de536796838be66f0ba7a3a0534d5d85de536796838be66f0ba7a3a0534d5d85de536796838be66f0ba7a3a0534d5d85de536796838be67a3a0534d5d85de53679683d5d85de536796838be66f0ba7a3a0534d5d85de536796838be66f0ba7a3a0534d5d85de536796838be66f0ba7a3a0534d5d85de536796838be66f0ba7a3a0534d5d85de536796838be66f0ba7a3a0534d5d85de536796838be6",
"description": "This is a beautiful photo of your travels in Ireland",
"id": "",
"fileId": "58caa289ac254dc0a565d26fa47f7cf1"
}'Delete a media item
Use this method to delete a media item with a specific ID. If the media item is published, you must unpublish it first. This request deletes a media item with the ID MR60hv5QGkupyb2NNRJRmA.
RequestResponse
curl --location --request DELETE '<BASE_URL>/api/content/v1/media/rZ0Yu33fsUWn2YpBuUZVYQ' \
--header 'Content-Type: application/json' \
--header 'Authorization: <BEARER_TOKEN>' \
--data '{
"name": "Ireland",
"description": "The Irish coast.",
"fileId": "E8MIqe0dJUWYPvlknIiHoQ1213"
}' Note
You can use query attributes with media items.
Publish a media item
Use this method to publish a specific media item. This request publishes a media item with the ID 1hMfKvVIcE2yBcKuN3_8vg.
RequestResponse
curl --location --request POST '<BASE_URL>/api/content/v1/media/1hMfKvVIcE2yBcKuN3_8vg/publish' \
--header 'Accept: text/plain' \
--header 'Authorization: <BEARER_TOKEN>'Unpublish a media item
Use this method to unpublish a specific media item. This request unpublishes a media item with the ID 1hMfKvVIcE2yBcKuN3_8vg.
RequestResponse
curl --location --request DELETE '<BASE_URL>/api/content/v1/media/1hMfKvVIcE2yBcKuN3_8vg/publish' \
--header 'Accept: text/plain' \
--header 'Authorization: <BEARER_TOKEN>'