Manage digital assets with the Adobe Experience Manager Assets HTTP API assets-http-api
Get Started with the AEM Assets HTTP API overview
The AEM Assets HTTP API enables CRUD (create, read, update, and delete) operations on digital assets through a REST interface available at /api/assets
. These operations apply to asset metadata, renditions, and comments. It includes support for Content Fragments.
To access the API:
- Open the API service document at
https://[hostname]:[port]/api.json
. - Follow the Assets service link leading to
https://[hostname]:[server]/api/assets.json
.
The API response is a JSON file for some MIME types and a response code for all MIME types. The JSON response is optional and may not be available, for example, for PDF files. Rely on the response code for further analysis or actions.
Manage content fragments content-fragments
A Content Fragment is a structured asset that stores text, numbers, and dates. As there are several differences to standard
assets (such as images or documents), some additional rules apply to handling Content Fragments.
For more information, see Content Fragments support in the Experience Manager Assets HTTP API.
Examine the data model data-model
The Assets HTTP API primarily exposes two elements: folders and standard assets. It also provides detailed elements for custom data models used in Content Fragments. For more details, see Content Fragment data models. See Content Fragment data models for further information.
Manage folders folders
Folders are like directories as in the traditional file systems. Folders can contain assets, subfolders, or both. Folders have the following components:
Entities: The entities of a folder are its child elements, which can be folders and assets.
Properties:
name
: The folder’s name (the last segment of the URL path, without the extension).title
: An optional title displayed in place of the folder name.
jcr
prefix of jcr:title
, jcr:description
, and jcr:language
are replaced with dc
prefix. Hence in the returned JSON, dc:title
and dc:description
contain the values of jcr:title
and jcr:description
, respectively.Links Folders expose three links:
self
: A link to the folder itself.parent
: A link to the parent folder.thumbnail
(Optional): A link to a folder thumbnail image.
Manage assets assets
In Experience Manager an asset contains the following elements:
- Properties and metadata: Descriptive information about the asset.
- Binary file: The originally uploaded file.
- Renditions: Multiple configured renditions (such as, images in various sizes, different video encodings, or extracted pages from PDFs/Adobe InDesign files).
- Comments (optional): User-provided remarks.
For information about elements in Content Fragments see Content Fragments Support in Experience Manager Assets HTTP API.
In Experience Manager a folder has the following components:
- Entities: The children of assets are its renditions.
- Properties.
- Links.
Explore available API operations available-features
The Assets HTTP API includes the following features:
Retrieve a folder listing retrieve-a-folder-listing
Retrieves a Siren representation of an existing folder and of its child entities (subfolders or assets).
Request: GET /api/assets/myFolder.json
Response codes: The response codes are:
- 200 - OK - success.
- 404 - NOT FOUND - folder does not exist or is not accessible.
- 500 - INTERNAL SERVER ERROR - if something else goes wrong.
Response: The class of the entity returned is an asset or a folder. The properties of contained entities are a subset of the full set of properties of each entity. To obtain a full representation of the entity, clients should retrieve the contents of the URL pointed to by the link with a rel
of self
.
Create a folder create-a-folder
Creates a sling
: OrderedFolder
at the given path. If *
is provided instead of a node name, the servlet uses the parameter name as node name. The request accepts either of the following:
- A Siren representation of the new folder
- A set of name-value pairs, encoded as
application/www-form-urlencoded
ormultipart
/form
-data
. These are useful to create a folder directly from an HTML form.
Also, properties of the folder can be specified as URL query parameters.
An API call fails with a 500
response code if the parent node of the provided path does not exist. A call returns a response code 409
if the folder exists.
Parameters: name
is the folder name.
Request
POST /api/assets/myFolder -H"Content-Type: application/json" -d '{"class":"assetFolder","properties":{"title":"My Folder"}}'
POST /api/assets/* -F"name=myfolder" -F"title=My Folder"
Response codes: The response codes are:
- 201 - CREATED - on successful creation.
- 409 - CONFLICT - if folder exists.
- 412 - PRECONDITION FAILED - if root collection cannot be found or accessed.
- 500 - INTERNAL SERVER ERROR - if something else goes wrong.
Create an asset create-an-asset
Asset creation is not supported via this HTTP API. For asset creation, use the asset upload API.
Update an asset binary update-asset-binary
See asset upload for information on how to update asset binaries. You cannot update an asset binary using the HTTP API.
Update metadata of an asset update-asset-metadata
This operation updates the asset’s metadata. When updating properties in the dc:
namespace, the corresponding jcr:
property is updated. However, the API does not sync the properties under the two namespaces.
Request: PUT /api/assets/myfolder/myAsset.png -H"Content-Type: application/json" -d '{"class":"asset", "properties":{"dc:title":"My Asset"}}'
Response codes: The response codes are:
- 200 - OK - if Asset has been updated successfully.
- 404 - NOT FOUND - if Asset could not be found or accessed at the provided URI.
- 412 - PRECONDITION FAILED - if root collection cannot be found or accessed.
- 500 - INTERNAL SERVER ERROR - if something else goes wrong.
Create an asset rendition create-an-asset-rendition
Create a rendition for an asset. If request parameter name is not provided, the file name is used as rendition name.
Parameters: The parameters are:
name
: for the rendition name.file
: The binary file for the rendition as a reference.
Request
POST /api/assets/myfolder/myasset.png/renditions/web-rendition -H"Content-Type: image/png" --data-binary "@myRendition.png"
POST /api/assets/myfolder/myasset.png/renditions/* -F"name=web-rendition" -F"file=@myRendition.png"
Response codes
- 201 - CREATED - if Rendition has been created successfully.
- 404 - NOT FOUND - if Asset could not be found or accessed at the provided URI.
- 412 - PRECONDITION FAILED - if root collection cannot be found or accessed.
- 500 - INTERNAL SERVER ERROR - if something else goes wrong.
Update an asset rendition update-an-asset-rendition
Updates respectively replace an asset rendition with the new binary data.
Request: PUT /api/assets/myfolder/myasset.png/renditions/myRendition.png -H"Content-Type: image/png" --data-binary @myRendition.png
Response codes: The response codes are:
- 200 - OK - if Rendition has been updated successfully.
- 404 - NOT FOUND - if Asset could not be found or accessed at the provided URI.
- 412 - PRECONDITION FAILED - if root collection cannot be found or accessed.
- 500 - INTERNAL SERVER ERROR - if something else goes wrong.
Add a comment on an asset create-an-asset-comment
Parameters: The parameters are message
for the message body of the comment and annotationData
for the Annotation data in JSON format.
Request: POST /api/assets/myfolder/myasset.png/comments/* -F"message=Hello World." -F"annotationData={}"
Response codes: The response codes are:
- 201 - CREATED - if Comment has been created successfully.
- 404 - NOT FOUND - if Asset could not be found or accessed at the provided URI.
- 412 - PRECONDITION FAILED - if root collection cannot be found or accessed.
- 500 - INTERNAL SERVER ERROR - if something else goes wrong.
Copy a folder or an asset copy-a-folder-or-asset
Copies a folder or asset available at the provided path to a new destination.
Request Headers: The parameters are:
X-Destination
- a new destination URI within the API solution scope to copy the resource to.X-Depth
- eitherinfinity
or0
. Using0
only copies the resource and its properties and not its children.X-Overwrite
- UseF
to prevent overwriting an asset at the existing destination.
Request: COPY /api/assets/myFolder -H"X-Destination: /api/assets/myFolder-copy"
Response codes: The response codes are:
- 201 - CREATED - if folder/asset has been copied to a non-existing destination.
- 204 - NO CONTENT - if the folder/asset has been copied to an existing destination.
- 412 - PRECONDITION FAILED - if a request header is missing.
- 500 - INTERNAL SERVER ERROR - if something else goes wrong.
Move a folder or an asset move-a-folder-or-asset
Moves a folder or asset at the given path to a new destination.
Request Headers: The parameters are:
X-Destination
- a new destination URI within the API solution scope to copy the resource to.X-Depth
- eitherinfinity
or0
. Using0
only copies the resource and its properties and not its children.X-Overwrite
- Use eitherT
to forcibly delete an existing resources orF
to prevent overwriting an existing resource.
Request: MOVE /api/assets/myFolder -H"X-Destination: /api/assets/myFolder-moved"
Response codes: The response codes are:
- 201 - CREATED - if folder/asset has been copied to a non-existing destination.
- 204 - NO CONTENT - if the folder/asset has been copied to an existing destination.
- 412 - PRECONDITION FAILED - if a request header is missing.
- 500 - INTERNAL SERVER ERROR - if something else goes wrong.
Delete a folder, an asset, or a rendition delete-a-folder-asset-or-rendition
Deletes a resource (-tree) at the provided path.
Request
DELETE /api/assets/myFolder
DELETE /api/assets/myFolder/myAsset.png
DELETE /api/assets/myFolder/myAsset.png/renditions/original
Response codes: The response codes are:
- 200 - OK - if folder has been deleted successfully.
- 412 - PRECONDITION FAILED - if root collection cannot be found or accessed.
- 500 - INTERNAL SERVER ERROR - if something else goes wrong.
Follow best practices and note limitations tips-limitations
-
Assets and their renditions become unavailable via the Assets web interface and the HTTP API when the Off Time is reached. The API returns a 404 error if the On Time is in the future or Off Time is in the past.
-
The Assets HTTP API returns only a subset of metadata. The namespaces are hardcoded and only those namespaces are returned. For complete metadata, see the asset path
/jcr_content/metadata.json
. -
Some properties of folder or asset are mapped to a different prefix when updated using APIs. The
jcr
prefix ofjcr:title
,jcr:description
, andjcr:language
are replaced withdc
prefix. Hence in the returned JSON,dc:title
anddc:description
contain the values ofjcr:title
andjcr:description
, respectively.
Explore related resources