Media CRUD operations

Get a collection of media items

To get all media items, you must execute a GET request to the following endpoint:

{baseurl}/api/default/{media}

Where media is the media item’s entity set, for example – images or videos.

Sample request

GET http://localhost:1337/api/default/images

Sample response

Status code: 200 OK

JSON

{
    "@odata.context": "http://localhost:1337/api/default/$metadata#images(Id,LastModified,PublicationDate,Title,Description,DateCreated,IncludeInSitemap,Ordinal,UrlName,Author,Extension,MimeType,TotalSize,Width,Height,AlternativeText,FolderId,ParentId,Url,ThumbnailUrl)",
    "value": [
        {
            "Id": "a825ffe9-dc41-4ed0-963b-6089d6f82be9",
            "LastModified": "2021-04-21T08:36:21Z",
            "PublicationDate": "2021-04-21T08:36:21Z",
            "Title": "test's",
            "Description": "test's",
            "DateCreated": "2021-04-21T08:36:21Z",
            "IncludeInSitemap": true,
            "Ordinal": 1,
            "UrlName": "test-s",
            "Author": null,
            "Extension": ".jpg",
            "MimeType": "image/jpeg",
            "TotalSize": 46005,
            "Width": 495,
            "Height": 328,
            "AlternativeText": "test's",
            "FolderId": null,
            "ParentId": "80c3b126-cd64-4044-abc3-227043c8be20",
            "Url": "http://localhost:1337/images/default-source/animals-library/test-s.jpg?sfvrsn=1464b1d0_2",
            "ThumbnailUrl": "http://localhost:1337/images/default-source/animals-library/test-s.tmb-thumbnail.jpg?sfvrsn=1464b1d0_1"
        },
        {
            "Id": "3c671940-3e9f-415d-9c76-8563b08410d4",
            "LastModified": "2021-04-19T13:40:10Z",
            "PublicationDate": "2021-04-19T13:40:10Z",
            "Title": "audi",
            "Description": "",
            "DateCreated": "2021-04-19T13:40:10Z",
            "IncludeInSitemap": true,
            "Ordinal": -1,
            "UrlName": "audi",
            "Author": "",
            "Extension": ".jpg",
            "MimeType": "image/jpeg",
            "TotalSize": 1256020,
            "Width": 2133,
            "Height": 3327,
            "AlternativeText": "",
            "FolderId": null,
            "ParentId": "b0d92da1-6317-4876-a470-a172b2808696",
            "Url": "http://localhost:1337/images/default-source/cars/audi.jpg?sfvrsn=87f858c9_1",
            "ThumbnailUrl": "http://localhost:1337/images/default-source/cars/audi.tmb-thumbnail.jpg?sfvrsn=87f858c9_1"
        },
        {
            "Id": "084ff0fa-2a4c-4be9-827b-69ef34c0a95c",
            "LastModified": "2021-04-19T13:33:50Z",
            "PublicationDate": "2021-04-19T13:33:50Z",
            "Title": "squirrel",
            "Description": "",
            "DateCreated": "2021-04-19T13:33:50Z",
            "IncludeInSitemap": true,
            "Ordinal": -2,
            "UrlName": "squirrel",
            "Author": "",
            "Extension": ".jpg",
            "MimeType": "image/jpeg",
            "TotalSize": 931207,
            "Width": 2939,
            "Height": 2583,
            "AlternativeText": "",
            "FolderId": null,
            "ParentId": "80c3b126-cd64-4044-abc3-227043c8be20",
            "Url": "http://localhost:1337/images/default-source/animals-library/squirrel.jpg?sfvrsn=4b03bb4f_1",
            "ThumbnailUrl": "http://localhost:1337/images/default-source/animals-library/squirrel.tmb-thumbnail.jpg?sfvrsn=4b03bb4f_1"
        },
        {
            "Id": "dd66dab3-c7e7-4753-931e-7ff47046fa6f",
            "LastModified": "2021-04-19T13:33:50Z",
            "PublicationDate": "2021-04-19T13:33:50Z",
            "Title": "parot",
            "Description": "",
            "DateCreated": "2021-04-19T13:33:50Z",
            "IncludeInSitemap": true,
            "Ordinal": -1,
            "UrlName": "parot",
            "Author": "",
            "Extension": ".jpg",
            "MimeType": "image/jpeg",
            "TotalSize": 830156,
            "Width": 2634,
            "Height": 3951,
            "AlternativeText": "",
            "FolderId": null,
            "ParentId": "80c3b126-cd64-4044-abc3-227043c8be20",
            "Url": "http://localhost:1337/images/default-source/animals-library/parot.jpg?sfvrsn=65819d8f_1",
            "ThumbnailUrl": "http://localhost:1337/images/default-source/animals-library/parot.tmb-thumbnail.jpg?sfvrsn=65819d8f_1"
        },
        {
            "Id": "04995fa1-0cb1-4247-ae10-0bade5d75d0e",
            "LastModified": "2021-04-19T13:34:31Z",
            "PublicationDate": "2021-04-19T13:34:31Z",
            "Title": "cat",
            "Description": "",
            "DateCreated": "2021-04-19T13:34:31Z",
            "IncludeInSitemap": true,
            "Ordinal": -2,
            "UrlName": "cat",
            "Author": "",
            "Extension": ".jpg",
            "MimeType": "image/jpeg",
            "TotalSize": 2068006,
            "Width": 4928,
            "Height": 3264,
            "AlternativeText": "",
            "FolderId": "43d06f6a-513f-4014-a707-f2da1b10844f",
            "ParentId": "80c3b126-cd64-4044-abc3-227043c8be20",
            "Url": "http://localhost:1337/images/default-source/animals-library/cats-library/cat.jpg?sfvrsn=3281de8_1",
            "ThumbnailUrl": "http://localhost:1337/images/default-source/animals-library/cats-library/cat.tmb-thumbnail.jpg?sfvrsn=3281de8_1"
        },
        {
            "Id": "cd2f181e-f357-449d-bc2a-5530aa1ebb9c",
            "LastModified": "2021-04-19T13:34:30Z",
            "PublicationDate": "2021-04-19T13:34:30Z",
            "Title": "kitten",
            "Description": "",
            "DateCreated": "2021-04-19T13:34:30Z",
            "IncludeInSitemap": true,
            "Ordinal": -1,
            "UrlName": "kitten",
            "Author": "",
            "Extension": ".jpg",
            "MimeType": "image/jpeg",
            "TotalSize": 635933,
            "Width": 2392,
            "Height": 2500,
            "AlternativeText": "",
            "FolderId": "43d06f6a-513f-4014-a707-f2da1b10844f",
            "ParentId": "80c3b126-cd64-4044-abc3-227043c8be20",
            "Url": "http://localhost:1337/images/default-source/animals-library/cats-library/kitten.jpg?sfvrsn=6b785c1f_1",
            "ThumbnailUrl": "http://localhost:1337/images/default-source/animals-library/cats-library/kitten.tmb-thumbnail.jpg?sfvrsn=6b785c1f_1"
        }
    ]
}

NOTE: This endpoint returns all media items. In the above case, it returns all images in the default data provider, for the default site, in default culture, because none of these parameters are specified. Regardless of whether the media items are in one library, in this case, in the response all the media items are flattened.
In the JSON of the response above, you can see that there are two libraries on the root level – Animals and Cars. The Animals library has two images at its root level and another library called Cats, which has two more images inside; the Cars library has only one image at its root level. All of these five are present in this response. The libraries are not present in this response. However, each item has a reference to its library and folder – the ParentId of the library and the FolderId of the folder.

Get a media item

To get a single media item, you must execute a GET request to the following endpoint:

{baseurl}/api/default/{media}({id})

Where:

media is the media item’s entity set, for example – images or videos
id is the ID of the media item that you want to get, for example – 04995fa1-0cb1-4247-ae10-0bade5d75d0e

Sample request

GET http://localhost:1337/api/default/images(04995fa1-0cb1-4247-ae10-0bade5d75d0e)

Sample response

Status code: 200 OK

JSON

{
    "@odata.context": "http://localhost:1337/api/default/$metadata#images/$entity",
    "Id": "04995fa1-0cb1-4247-ae10-0bade5d75d0e",
    "LastModified": "2021-04-19T13:34:31Z",
    "PublicationDate": "2021-04-19T13:34:31Z",
    "Title": "cat",
    "Description": "",
    "DateCreated": "2021-04-19T13:34:31Z",
    "IncludeInSitemap": true,
    "Ordinal": -2,
    "UrlName": "cat",
    "Author": "",
    "Extension": ".jpg",
    "MimeType": "image/jpeg",
    "TotalSize": 2068006,
    "Category": [],
    "Tags": [],
    "Width": 4928,
    "Height": 3264,
    "AlternativeText": "",
    "FolderId": "43d06f6a-513f-4014-a707-f2da1b10844f",
    "ParentId": "80c3b126-cd64-4044-abc3-227043c8be20",
    "Provider": "OpenAccessDataProvider",
    "Url": "http://localhost:1337/images/default-source/animals-library/cats-library/cat.jpg?sfvrsn=3281de8_1",
    "ThumbnailUrl": "http://localhost:1337/images/default-source/animals-library/cats-library/cat.tmb-thumbnail.jpg?sfvrsn=3281de8_1",
    "Thumbnails": [
        {
            "Title": "0",
            "Url": "http://localhost:1337/images/default-source/animals-library/cats-library/cat.tmb-0.jpg?sfvrsn=3281de8_1",
            "Width": 241
        }
    ]
}

Upload a media item

To upload a media item, you must execute a POST request to the following endpoint:

{baseurl}/api/default/{media}

Where media is the media item’s entity set, for example – images or videos.

Sample request

POST http://localhost:1337/api/default/images

Request headers

Text

X-Sf-Properties: {"ParentId":"80c3b126-cd64-4044-abc3-227043c8be20", "FolderId":"43d06f6a-513f-4014-a707-f2da1b10844f", "Title":"Pomeranian"}
Content-Type: image/jpeg
X-File-Name: image-name.jpg

The content type is the respective MIME type of the currently uploaded image.

Request body

The binary data of the currently uploaded file in base64 string.

Sample response

Status code: 201 Created

JSON

{
    "@odata.context": "http://localhost:1337/api/default/$metadata#images/$entity",
    "Id": "04995fa1-0cb1-4247-ae10-0bade5d75d0e",
    "LastModified": "2021-04-19T13:34:31Z",
    "PublicationDate": "2021-04-19T13:34:31Z",
    "Title": "cat",
    "Description": "",
    "DateCreated": "2021-04-19T13:34:31Z",
    "IncludeInSitemap": true,
    "Ordinal": -2,
    "UrlName": "cat",
    "Author": "",
    "Extension": ".jpg",
    "MimeType": "image/jpeg",
    "TotalSize": 2068006,
    "Category": [],
    "Tags": [],
    "Width": 4928,
    "Height": 3264,
    "AlternativeText": "",
    "FolderId": "43d06f6a-513f-4014-a707-f2da1b10844f",
    "ParentId": "80c3b126-cd64-4044-abc3-227043c8be20",
    "Provider": "OpenAccessDataProvider",
    "Url": "http://localhost:1337/images/default-source/animals-library/cats-library/cat.jpg?sfvrsn=3281de8_1",
    "ThumbnailUrl": "http://localhost:1337/images/default-source/animals-library/cats-library/cat.tmb-thumbnail.jpg?sfvrsn=3281de8_1",
    "Thumbnails": [
        {
            "Title": "0",
            "Url": "http://localhost:1337/images/default-source/animals-library/cats-library/cat.tmb-0.jpg?sfvrsn=3281de8_1",
            "Width": 241
        }
    ]
}

Updating a media item can be done in two ways – with a PATCH or with a PUT request. The difference between the two verbs is that PATCH allows for a partial update, whereas PUT requires all fields to be present in the request’s body. To partially update a media item, you must execute a PATCH request to the following endpoint:

{baseurl}/api/default/{media}({id})

Where:

media is the media item’s entity set, for example – images or videos
id is the ID of the media item that you want to update, for example – 04995fa1-0cb1-4247-ae10-0bade5d75d0e

For example, the following request updates only the AlternativeText property of the Image media type:

Sample request

PATCH http://localhost:1337/api/default/images(04995fa1-0cb1-4247-ae10-0bade5d75d0e)

Request body

JSON

{
    "AlternativeText":"Meaningful alternative text"
}

Sample response

Status code: 204 No Content

No response body

Status code: 400 Bad Request

If you make the same request as above, but you change the verb to PUT, the server responds with the following error:

JSON

{
    "error": {
        "code": "BadRequest",
        "message": "Missing properties: Title,Description,IncludeInSitemap,Ordinal,UrlName,Author,Category,Tags,ParentId",
        "target": "Telerik.Sitefinity.Web.Api"
    }
}

NOTE: This error is specific to the Images media type.

Fully update a media item

Updating a media item can be done in two ways – with a PATCH or with a PUT request. The difference between the two verbs is that PATCH allows for a partial update, whereas PUT requires all fields to be present in the request’s body. To fully update a media item, you must execute a PUT request to the following endpoint:

{baseurl}/api/default/{media}({id})

Where:

media is the media item’s entity set, for example – images or videos
id is the ID of the media item that you want to update, for example – 04995fa1-0cb1-4247-ae10-0bade5d75d0e

Sample request

PUT http://localhost:1337/api/default/images(04995fa1-0cb1-4247-ae10-0bade5d75d0e)

Request body

JSON

{
    "AlternativeText":"Meaningful alternative text",
    "Title":"Update title",
    "Description":"",
    "IncludeInSitemap": "False",
    "Ordinal": 0,
    "UrlName":"some-url-name",
    "ParentId":"80c3b126-cd64-4044-abc3-227043c8be20",
    "Category": [],
    "Tags": [],
    "Author": "Some photographer"
}

Sample response

Status code: 204 No Content

No response body

Delete a media item

To delete a media item, you must execute a DELETE request to the following endpoint:

{baseurl}/api/default/{media}({id})

Where:

media is the media item’s entity set, for example – images or videos
id is the ID of the media item that you want to update, for example – 04995fa1-0cb1-4247-ae10-0bade5d75d0e

Sample request

DELETE http://localhost:1337/api/default/images(04995fa1-0cb1-4247-ae10-0bade5d75d0e)

Sample response

Status code: 204 No Content

No response body

NOTE: If you have enabled the Recycle bin module of Sitefinity CMS the media item will be moved to the Recycle bin. If the module is disabled - the media item will be deleted permanently.

Want to learn more?

Enhance your Sitefinity skills by enrolling in free training sessions. Become Sitefinity certified through Progress Education Community to strengthen your professional credentials.

Get started with Integration Hub | Sitefinity Cloud

This free lesson teaches administrators, marketers, and other business professionals how to use Sitefinity Integration Hub to create automated workflows between Sitefinity and other business systems.

Web Security for Sitefinity Administrators

This free lesson teaches administrators the basics about protecting your Sitefinity instance and your sites from external threats. Configure HTTPS, SSL, allow lists for trusted sites, and cookie security, among others.

Foundations of Sitefinity ASP.NET Core Development

The free on-demand video course teaches developers how to use Sitefinity ASP.NET Core and take advantage of its decoupled architecture and modern development model.

Media CRUD operations

Get a collection of media items

Get a media item

Upload a media item

Partially update a media item

Fully update a media item

Delete a media item