We have moved!

You are currently looking at documentation for Umbraco 8 and older versions.
Go to docs.umbraco.com for documentation for Umbraco 9 and newer versions.

    Content Management API for Media

    BASE URL: https://api.umbraco.io

    Table of Contents

    Common Headers

    Api-Version: 2
Umb-Project-Alias: {project-alias}

    Authentication

    Auth is required for this API meaning that you must supply a Bearer Token via an Authorization header or an API Key via an Authorization or Api-Key header.

    Errors

    If an error occours you will receive a HTTP status code along with an API error code and an error message in the response body.

    Status Code Error Code Message
    400 BadRequest Body cannot be empty.
    401 Unauthorized Authorization has been denied for this request.
    403 Forbidden You are not authorized to access the given resource.
    404 NotFound Media with id '{id}' could not be found.
    422 ValidationFailed Validation error occured when trying to save or update the media item.
    500 InternalServerError Internal server error.

    JSON example:

    {
  "error": {
    "code": "Unauthorized",
    "message": "Authorization has been denied for this request."
  }
}

    Get root media

    Get all media at the root of the tree, which the authorized user has access to according to the 'Start node'-permissions.

    URL: /media

    Method: GET

    Permissions required : Access to Media section of the Umbraco Backoffice

    Success Response

    Code: 200

    Content Example:

    {
    "_links": {
        "self": {
            "href": "https://api.umbraco.io/media"
        },
        "media": [
            {
                "href": "https://api.umbraco.io/media/{id}",
                "templated": true
            },
            {
                "href": "https://api.umbraco.io/media/7bfa2332-cf7f-4c97-941d-50f43f085b06"
            },
            {
                "href": "https://api.umbraco.io/media/bff96d2a-18a7-4d72-b788-72e2034a5514"
            },
            {
                "href": "https://api.umbraco.io/media/9924b6e9-51fd-4686-ad9a-cb59dbe9b4b1"
            }
        ],
        "children": {
            "href": "https://api.umbraco.io/media/{id}/children{?page,pageSize}",
            "templated": true
        },
        "mediatype": {
            "href": "https://api.umbraco.io/media/type/{alias}",
            "templated": true
        }
    },
    "_embedded": {
        "media": [
            {
                "_hasChildren": true,
                "_level": 1,
                "_createDate": "2019-10-04T11:46:06.653Z",
                "_id": "7bfa2332-cf7f-4c97-941d-50f43f085b06",
                "_updateDate": "2019-10-04T11:46:06.653Z",
                "_links": {
                    "self": {
                        "href": "https://api.umbraco.io/media/7bfa2332-cf7f-4c97-941d-50f43f085b06"
                    },
                    "root": {
                        "href": "https://api.umbraco.io/media"
                    },
                    "children": {
                        "href": "https://api.umbraco.io/media/7bfa2332-cf7f-4c97-941d-50f43f085b06/children"
                    },
                    "mediatype": {
                        "href": "https://api.umbraco.io/media/type/Folder"
                    }
                },
                "mediaTypeAlias": "Folder",
                "name": "Design",
                "sortOrder": 1
            },
            {
                "_hasChildren": true,
                "_level": 1,
                "_createDate": "2019-10-04T11:46:14.32Z",
                "_id": "bff96d2a-18a7-4d72-b788-72e2034a5514",
                "_updateDate": "2019-10-04T11:46:14.32Z",
                "_links": {
                    "self": {
                        "href": "https://api.umbraco.io/media/bff96d2a-18a7-4d72-b788-72e2034a5514"
                    },
                    "root": {
                        "href": "https://api.umbraco.io/media"
                    },
                    "children": {
                        "href": "https://api.umbraco.io/media/bff96d2a-18a7-4d72-b788-72e2034a5514/children"
                    },
                    "mediatype": {
                        "href": "https://api.umbraco.io/media/type/Folder"
                    }
                },
                "mediaTypeAlias": "Folder",
                "name": "People",
                "sortOrder": 2
            },
            {
                "_hasChildren": true,
                "_level": 1,
                "_createDate": "2019-10-04T11:46:21.433Z",
                "_id": "9924b6e9-51fd-4686-ad9a-cb59dbe9b4b1",
                "_updateDate": "2019-10-04T11:46:21.433Z",
                "_links": {
                    "self": {
                        "href": "https://api.umbraco.io/media/9924b6e9-51fd-4686-ad9a-cb59dbe9b4b1"
                    },
                    "root": {
                        "href": "https://api.umbraco.io/media"
                    },
                    "children": {
                        "href": "https://api.umbraco.io/media/9924b6e9-51fd-4686-ad9a-cb59dbe9b4b1/children"
                    },
                    "mediatype": {
                        "href": "https://api.umbraco.io/media/type/Folder"
                    }
                },
                "mediaTypeAlias": "Folder",
                "name": "Products",
                "sortOrder": 3
            }
        ]
    }
}

    Get by id

    Get specific media item by its GUID ID.

    URL: /media/{id}

    Method: GET

    Permissions required : Access to Media section of the Umbraco Backoffice

    Success Response

    Code: 200

    Content Example:

    {
    "_hasChildren": false,
    "_level": 2,
    "_createDate": "2019-10-04T13:08:52.203Z",
    "_id": "f2311d74-bc19-465b-8028-4af79f47f155",
    "_updateDate": "2019-10-04T13:08:52.203Z",
    "_links": {
        "self": {
            "href": "https://api.umbraco.io/media/f2311d74-bc19-465b-8028-4af79f47f155"
        },
        "root": {
            "href": "https://api.umbraco.io/media"
        },
        "children": {
            "href": "https://api.umbraco.io/media/f2311d74-bc19-465b-8028-4af79f47f155/children"
        },
        "mediatype": {
            "href": "https://api.umbraco.io/media/type/Image"
        }
    },
    "mediaTypeAlias": "Image",
    "name": "Banjo",
    "parentId": "9924b6e9-51fd-4686-ad9a-cb59dbe9b4b1",
    "sortOrder": 4,
    "umbracoFile": {
        "src": "/media/oiodd2qz/7373036290_5e8420bf36_b.jpg",
        "focalPoint": {
            "left": 0.5,
            "top": 0.5
        },
        "crops": null
    },
    "umbracoWidth": "1024",
    "umbracoHeight": "683",
    "umbracoBytes": "299546",
    "umbracoExtension": "jpg"
}

    Get children

    Get a list of children (media items) by their parent GUID ID.

    URL: /media/{id}/children

    Method: GET

    Query Strings

    ?page={integer=1}
?pageSize={integer=10}

    Permissions required : Access to Media section of the Umbraco Backoffice

    Success Response

    Code: 200

    Content Example:

    {
    "_totalItems": 5,
    "_totalPages": 1,
    "_page": 1,
    "_pageSize": 10,
    "_links": {
        "self": {
            "href": "https://api.umbraco.io/media/bff96d2a-18a7-4d72-b788-72e2034a5514/children?page=1"
        },
        "media": [
            {
                "href": "https://api.umbraco.io/media/b0d9704a-8c1a-498f-8892-d3a18acc6f01"
            },
            {
                "href": "https://api.umbraco.io/media/3bc8bf5c-5f39-4a49-b8f3-a09c265aa739"
            },
            {
                "href": "https://api.umbraco.io/media/9b4a8092-a157-4a0e-9626-1f320a7a5f79"
            },
            {
                "href": "https://api.umbraco.io/media/9012c147-90dc-4c7e-8249-4b4092aff340"
            },
            {
                "href": "https://api.umbraco.io/media/313bf02d-bfba-4d61-a12c-1fbdbe0fee1c"
            }
        ]
    },
    "_embedded": {
        "media": [
            {
                "_hasChildren": false,
                "_level": 2,
                "_createDate": "2019-10-04T11:49:57.863Z",
                "_id": "b0d9704a-8c1a-498f-8892-d3a18acc6f01",
                "_updateDate": "2019-10-04T11:49:57.863Z",
                "_links": {
                    "self": {
                        "href": "https://api.umbraco.io/media/b0d9704a-8c1a-498f-8892-d3a18acc6f01"
                    },
                    "root": {
                        "href": "https://api.umbraco.io/media"
                    },
                    "children": {
                        "href": "https://api.umbraco.io/media/b0d9704a-8c1a-498f-8892-d3a18acc6f01/children"
                    },
                    "mediatype": {
                        "href": "https://api.umbraco.io/media/type/Image"
                    }
                },
                "mediaTypeAlias": "Image",
                "name": "Jan Skovgaard",
                "parentId": "bff96d2a-18a7-4d72-b788-72e2034a5514",
                "sortOrder": 0,
                "umbracoFile": {
                    "src": "/media/jryntma0/18720470241_ff77768544_h.jpg",
                    "focalPoint": {
                        "left": 0.5,
                        "top": 0.5
                    },
                    "crops": null
                },
                "umbracoWidth": "1600",
                "umbracoHeight": "1067",
                "umbracoBytes": "240126",
                "umbracoExtension": "jpg"
            },
            {
                "_hasChildren": false,
                "_level": 2,
                "_createDate": "2019-10-04T11:50:12.933Z",
                "_id": "3bc8bf5c-5f39-4a49-b8f3-a09c265aa739",
                "_updateDate": "2019-10-04T11:50:12.933Z",
                "_links": {
                    "self": {
                        "href": "https://api.umbraco.io/media/3bc8bf5c-5f39-4a49-b8f3-a09c265aa739"
                    },
                    "root": {
                        "href": "https://api.umbraco.io/media"
                    },
                    "children": {
                        "href": "https://api.umbraco.io/media/3bc8bf5c-5f39-4a49-b8f3-a09c265aa739/children"
                    },
                    "mediatype": {
                        "href": "https://api.umbraco.io/media/type/Image"
                    }
                },
                "mediaTypeAlias": "Image",
                "name": "Matt Brailsford",
                "parentId": "bff96d2a-18a7-4d72-b788-72e2034a5514",
                "sortOrder": 1,
                "umbracoFile": {
                    "src": "/media/lk5nqozz/18531852339_981b067419_h.jpg",
                    "focalPoint": {
                        "left": 0.5,
                        "top": 0.5
                    },
                    "crops": null
                },
                "umbracoWidth": "1600",
                "umbracoHeight": "1067",
                "umbracoBytes": "438249",
                "umbracoExtension": "jpg"
            },
            {
                "_hasChildren": false,
                "_level": 2,
                "_createDate": "2019-10-04T11:57:36.863Z",
                "_id": "9b4a8092-a157-4a0e-9626-1f320a7a5f79",
                "_updateDate": "2019-10-04T11:57:36.863Z",
                "_links": {
                    "self": {
                        "href": "https://api.umbraco.io/media/9b4a8092-a157-4a0e-9626-1f320a7a5f79"
                    },
                    "root": {
                        "href": "https://api.umbraco.io/media"
                    },
                    "children": {
                        "href": "https://api.umbraco.io/media/9b4a8092-a157-4a0e-9626-1f320a7a5f79/children"
                    },
                    "mediatype": {
                        "href": "https://api.umbraco.io/media/type/Image"
                    }
                },
                "mediaTypeAlias": "Image",
                "name": "Lee Kelleher",
                "parentId": "bff96d2a-18a7-4d72-b788-72e2034a5514",
                "sortOrder": 2,
                "umbracoFile": {
                    "src": "/media/ssaevg0x/18531854019_351c579559_h.jpg",
                    "focalPoint": {
                        "left": 0.5,
                        "top": 0.5
                    },
                    "crops": null
                },
                "umbracoWidth": "1600",
                "umbracoHeight": "1067",
                "umbracoBytes": "324821",
                "umbracoExtension": "jpg"
            },
            {
                "_hasChildren": false,
                "_level": 2,
                "_createDate": "2019-10-04T11:57:56.267Z",
                "_id": "9012c147-90dc-4c7e-8249-4b4092aff340",
                "_updateDate": "2019-10-04T11:57:56.267Z",
                "_links": {
                    "self": {
                        "href": "https://api.umbraco.io/media/9012c147-90dc-4c7e-8249-4b4092aff340"
                    },
                    "root": {
                        "href": "https://api.umbraco.io/media"
                    },
                    "children": {
                        "href": "https://api.umbraco.io/media/9012c147-90dc-4c7e-8249-4b4092aff340/children"
                    },
                    "mediatype": {
                        "href": "https://api.umbraco.io/media/type/Image"
                    }
                },
                "mediaTypeAlias": "Image",
                "name": "Jeavon Leopold",
                "parentId": "bff96d2a-18a7-4d72-b788-72e2034a5514",
                "sortOrder": 3,
                "umbracoFile": {
                    "src": "/media/ihabfeg2/18095416144_44a566a5f4_h.jpg",
                    "focalPoint": {
                        "left": 0.5,
                        "top": 0.5
                    },
                    "crops": null
                },
                "umbracoWidth": "1600",
                "umbracoHeight": "1067",
                "umbracoBytes": "348162",
                "umbracoExtension": "jpg"
            },
            {
                "_hasChildren": false,
                "_level": 2,
                "_createDate": "2019-10-04T11:58:15.54Z",
                "_id": "313bf02d-bfba-4d61-a12c-1fbdbe0fee1c",
                "_updateDate": "2019-10-04T11:58:15.54Z",
                "_links": {
                    "self": {
                        "href": "https://api.umbraco.io/media/313bf02d-bfba-4d61-a12c-1fbdbe0fee1c"
                    },
                    "root": {
                        "href": "https://api.umbraco.io/media"
                    },
                    "children": {
                        "href": "https://api.umbraco.io/media/313bf02d-bfba-4d61-a12c-1fbdbe0fee1c/children"
                    },
                    "mediatype": {
                        "href": "https://api.umbraco.io/media/type/Image"
                    }
                },
                "mediaTypeAlias": "Image",
                "name": "Jeroen Breuer",
                "parentId": "bff96d2a-18a7-4d72-b788-72e2034a5514",
                "sortOrder": 4,
                "umbracoFile": {
                    "src": "/media/fpydwmn0/18530280048_459b8b61b2_h.jpg",
                    "focalPoint": {
                        "left": 0.5,
                        "top": 0.5
                    },
                    "crops": null
                },
                "umbracoWidth": "1600",
                "umbracoHeight": "1067",
                "umbracoBytes": "240519",
                "umbracoExtension": "jpg"
            }
        ]
    }
}

    Create media

    Create a new media item and optionally upload a file to the created item.

    Media would typically contain an upload field (the Image and File media types has this by default), which means it is possible to send a file along with the request to create a new media item. This is done by sending a multi-part request with the JSON body and the file. If the media item does not contain a file you can send a regular JSON request to create the media.

    URL: /media

    Method: POST

    Header: Content-Type: multipart/form-data; boundary=MultipartBoundry

    Permissions required : Access to Media section of the Umbraco Backoffice

    Request

    --MultipartBoundry
Content-Disposition: form-data; name="content"
Content-Type: application/json

{
    "mediaTypeAlias": "Image",
    "name": "Han Solo",
    "parentId": "7bfa2332-cf7f-4c97-941d-50f43f085b06",
    "umbracoFile": { "src": "han-solo.png" }
}
--MultipartBoundry
Content-Disposition: form-data; name="umbracoFile"
Content-Type: image/png

BINARY DATA
--MultipartBoundry--

    Success Response

    Code: 201

    Content Example:

    {
    "_hasChildren": false,
    "_level": 2,
    "_createDate": "2019-10-10T12:24:58.76Z",
    "_id": "b60a1257-4bef-4d5a-aeb6-4af17b6233b2",
    "_updateDate": "2019-10-10T12:24:58.76Z",
    "_deleteDate": "2019-10-10T12:25:15.3860527Z",
    "_links": {
        "self": {
            "href": "https://api.umbraco.io/media/b60a1257-4bef-4d5a-aeb6-4af17b6233b2"
        },
        "root": {
            "href": "https://api.umbraco.io/media"
        },
        "children": {
            "href": "https://api.umbraco.io/media/b60a1257-4bef-4d5a-aeb6-4af17b6233b2/children"
        },
        "mediatype": {
            "href": "https://api.umbraco.io/media/type/Image"
        }
    },
    "mediaTypeAlias": "Image",
    "name": "Han Solo",
    "parentId": "7bfa2332-cf7f-4c97-941d-50f43f085b06",
    "sortOrder": 1,
    "umbracoFile": {
        "src": "/media/kejavnxp/han-solo.png",
        "focalPoint": {
            "left": 0.5,
            "top": 0.5
        },
        "crops": null
    },
    "umbracoWidth": "672",
    "umbracoHeight": "896",
    "umbracoBytes": "489855",
    "umbracoExtension": "png"
}

    Update media

    Updates an existing media item and optionally uploads a file to the updated item.

    Media would typically contain an upload field (the Image and File media types has this by default), which means it is possible to send a file along with the request to update an existing media item. This is done by sending a multi-part request with the JSON body and the file. If the media item does not contain a file you can send a regular JSON request to update the media.

    URL: /media/{id}

    Method: PUT

    Header: Content-Type: multipart/form-data; boundary=MultipartBoundry

    Permissions required : Access to Media section of the Umbraco Backoffice

    Request

    Content-Type: multipart/form-data; boundary=MultipartBoundry

--MultipartBoundry
Content-Disposition: form-data; name="content"
Content-Type: application/json

{
    "mediaTypeAlias": "Image",
    "name": "Han Solo",
    "parentId": "7bfa2332-cf7f-4c97-941d-50f43f085b06",
    "sortOrder": 1,
    "umbracoFile": { "src": "han-solo.png" }
}
--MultipartBoundry
Content-Disposition: form-data; name="umbracoFile"
Content-Type: image/png

BINARY DATA
--MultipartBoundry--

    Success Response

    Code: 200

    Content Example:

    {
    "_hasChildren": false,
    "_level": 2,
    "_createDate": "2019-10-10T12:24:58.76Z",
    "_id": "b60a1257-4bef-4d5a-aeb6-4af17b6233b2",
    "_updateDate": "2019-10-10T12:24:58.76Z",
    "_deleteDate": "2019-10-10T12:25:15.3860527Z",
    "_links": {
        "self": {
            "href": "https://api.umbraco.io/media/b60a1257-4bef-4d5a-aeb6-4af17b6233b2"
        },
        "root": {
            "href": "https://api.umbraco.io/media"
        },
        "children": {
            "href": "https://api.umbraco.io/media/b60a1257-4bef-4d5a-aeb6-4af17b6233b2/children"
        },
        "mediatype": {
            "href": "https://api.umbraco.io/media/type/Image"
        }
    },
    "mediaTypeAlias": "Image",
    "name": "Han Solo",
    "parentId": "7bfa2332-cf7f-4c97-941d-50f43f085b06",
    "sortOrder": 1,
    "umbracoFile": {
        "src": "/media/kejavnxp/han-solo.png",
        "focalPoint": {
            "left": 0.5,
            "top": 0.5
        },
        "crops": null
    },
    "umbracoWidth": "672",
    "umbracoHeight": "896",
    "umbracoBytes": "489855",
    "umbracoExtension": "png"
}

    Delete media

    Delete a media item. This will also delete any file that is attached to the media item.

    URL: /media/{id}

    Method: DELETE

    Permissions required : Access to Media section of the Umbraco Backoffice

    Success Response

    Code: 200

    Content Example:

    DELETE https://api.umbraco.io/media/b60a1257-4bef-4d5a-aeb6-4af17b6233b2

    {
    "_hasChildren": false,
    "_level": 2,
    "_createDate": "2019-10-10T12:24:58.76Z",
    "_id": "b60a1257-4bef-4d5a-aeb6-4af17b6233b2",
    "_updateDate": "2019-10-10T12:24:58.76Z",
    "_deleteDate": "2019-10-10T12:25:15.3860527Z",
    "_links": {
        "self": {
            "href": "https://api.umbraco.io/media/b60a1257-4bef-4d5a-aeb6-4af17b6233b2"
        },
        "root": {
            "href": "https://api.umbraco.io/media"
        },
        "children": {
            "href": "https://api.umbraco.io/media/b60a1257-4bef-4d5a-aeb6-4af17b6233b2/children"
        },
        "mediatype": {
            "href": "https://api.umbraco.io/media/type/Image"
        }
    },
    "mediaTypeAlias": "Image",
    "name": "Han Solo",
    "parentId": "7bfa2332-cf7f-4c97-941d-50f43f085b06",
    "sortOrder": 1,
    "umbracoFile": {
        "src": "/media/kejavnxp/han-solo.png",
        "focalPoint": {
            "left": 0.5,
            "top": 0.5
        },
        "crops": null
    },
    "umbracoWidth": "672",
    "umbracoHeight": "896",
    "umbracoBytes": "489855",
    "umbracoExtension": "png"
}