1. Content Management API

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.

curl --location '<BASE_URL>/api/content/v1/media' \
--header 'Authorization: <BEARER_TOKEN> ' \
{
  "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

curl --location '<BASE_URL>/api/content/v1/media/1hMfKvVIcE2yBcKuN3_8vg' \
--header 'Authorization: <BEARER_TOKEN>' \
--data ''

Example of an ID query for multiple items

curl --location '<BASE_URL>/api/content/v1/media?italy%7Cireland%7Cvietnam=null' \
--header 'Authorization: <BEARER_TOKEN>' \
--data ''

Example of a search query

curl --location '<BASE_URL>/api/content/v1/media?search=italy' \
--header 'Authorization: <BEARER_TOKEN>' \
--data ''

Example of a sortBy query:

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.

curl --location '<BASE_URL>/api/content/v1/media/?linkedTo=1hMfKvVIcE2yBcKuN3_8vg' \
--header 'Authorization: <BEARER_TOKEN>
--data ''--data
{
  "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.

curl --location '<BASE_URL>/api/content/v1/media/travelJapan2Weeks'
{
  "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
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.

{
  "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.

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.

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.

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.

curl --location --request DELETE '<BASE_URL>/api/content/v1/media/1hMfKvVIcE2yBcKuN3_8vg/publish' \
--header 'Accept: text/plain' \
--header 'Authorization: <BEARER_TOKEN>'
If you have suggestions for improving this article, let us know!