You're viewing help content for version:
- 6.5
- 6.4
- 6.3
- 6.2
- Older Versions
The Assets HTTP API is a specific part of the general Marketing Cloud API. For general documentation, see Marketing Cloud API user documentation.
The Assets HTTP API is exposed at /api/assets, and allows for create-read-update-delete (CRUD) operations on Assets, including binary, metadata, renditions, and comments.
The API's response is a JSON 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.
Folders are like directories in tradtional filesystems. They are containers for other folders or asserts. Folders have the following components:
Entities: The entities of a folder are its child elements, which can be folders and assets.
Properties:
name -- Name of the folder. This is the same as the last segment in the URL path without the extension title -- Optional title of the folder which can be displayed instead of its name
Note:
Some properties of folder or asset are mapped to a different prefix. The 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.
self -- Link to itself parent -- Link to the parent folder thumbnail -- (Optional) link to a folder thumbnail image
Assets are actually multi-part elements:
- The properties and metadata of the asset
- Multiple renditions such as the original rendition (which is the originally uploaded asset), a thumbnail and various other renditions. Additional renditions may be images of different sizes, different video encodings, or extracted pages from PDF or InDesign.
- Optional comments
Folders have the following components:
Entities
The children of Assets are its renditions.
Properties
Links
The Assets HTTP API includes the following features:
- Retrieve a folder listing
- Create a folder
- Create an asset
- Update asset binary
- Update asset metadata
- Create an asset rendition
- Update an asset rendition
- Create an asset comment
- Copy a folder or asset
- Move a folder or asset
- Delete a folder, asset, or rendition
Note:
For the ease of readability the following examples omit the full cURL notation. In fact the notation does correlate with Resty which is a script wrapper for cURL.
- Go to http://<Server>:<Port>/system/console/configMgr.
- Navigate to Adobe Granite CSRF Filter.
- Make sure the property Filter Methods incudes: POST, PUT, DELETE.
Retrieves a Siren representation of an existing folder and of its child entities (subfolders or assets).
Request
GET /api/assets/myFolder.json
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 assets/folder.
Properties of contained entities are a subset of the full set of properties of each entity. In order 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.
Creates a new sling:OrderedFolder at the given path. If a * is given instead of a node name the servlet will use the parameter name as node name. Accepted as request data is either a Siren representation of the new folder or a set of name-value pairs, encoded as application/www-form-urlencoded or multipart/form-data, useful for creating a folder directly from an HTML form. Additionally, properties of the folder can be specified as URL query parameters.
The operation will fail with a 500 response code if the parent node of the given path does not exist. If the folder already exists a 409 response code is returned.
Parameters
name - Folder name
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"
201 - CREATED - on successful creation 409 - CONFLICT - if folder already exist 412 - PRECONDITION FAILED - if root collection cannot be found or accessed 500 - INTERNAL SERVER ERROR - if something else goes wrong
Creates a DAM asset at the given path with the given file. If a * is given instead of a node name the servlet will use the parameter name or the file name as node name.
Parameters
name - Asset name file - File reference
POST /api/assets/myFolder/myAsset.png -H"Content-Type: image/png" --data-binary "@myPicture.png"
POST /api/assets/myFolder/* -F"name=myAsset.png" -F"file=@myPicture.png"
201 - CREATED - if Asset has been created successfully 409 - CONFLICT - if Asset already exist 412 - PRECONDITION FAILED - if root collection cannot be found or accessed 500 - INTERNAL SERVER ERROR - if something else goes wrong
Updates an Assets binary (rendition with name original). This will trigger the default Asset workflow if configured.
Request
PUT /api/assets/myfolder/myAsset.png -H"Content-Type: image/png" --data-binary @myPicture.png
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
PUT /api/assets/myfolder/myAsset.png -H"Content-Type: application/json" -d '{"class":"asset", "properties":{"dc:title":"My Asset"}}'
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
Creates a new asset rendition for an asset. If request parameter name is not provided the file name is used as rendition name.
Parameters
name - Rendition name file - File reference
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"
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
PUT /api/assets/myfolder/myasset.png/renditions/myRendition.png -H"Content-Type: image/png" --data-binary @myRendition.png
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
message - Message annotationData - Annotation data (JSON)
POST /api/assets/myfolder/myasset.png/comments/* -F"message=Hello World." -F"annotationData={}"
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
X-Destination - a new destination URI within the API solution scope to copy the resource to X-Depth - either 'infinity' or '0'. The value '0' only copies the resource and its properties, no children. X-Overwrite - 'F' to prevent overwriting an existing destination
COPY /api/assets/myFolder -H"X-Destination: /api/assets/myFolder-copy"
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 or 500 - INTERNAL SERVER ERROR - if something else goes wrong
X-Destination - a new destination URI within the API solution scope to copy the resource to X-Depth - either 'infinity' or '0'. The value '0' only copies the resource and its properties, no children. X-Overwrite - either 'T' to force deletion of existing resources or 'F' to prevent overwriting an existing resource.
MOVE /api/assets/myFolder -H"X-Destination: /api/assets/myFolder-moved"
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 or 500 - INTERNAL SERVER ERROR - if something else goes wrong
DELETE /api/assets/myFolder
DELETE /api/assets/myFolder/myAsset.png
DELETE /api/assets/myFolder/myAsset.png/renditions/original
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