Asset

Assets refer to all the media files (images, videos, PDFs, audio files, and so on) uploaded in your Contentstack repository for future use.

uploadAsset

The "Upload asset" request uploads an asset file to your stack.

To upload assets from your local system to Contentstack and manage their details, you need to use the following "form-data" parameters:

Name	Type	Description
filePath (required)	String	The file path.
description (required)	String	The description of the asset file.
upload (required)	JPG, GIF, PNG, XML, WebP, BMP, TIFF, SVG, and PSD	Select the input type as 'File.' Then, browse and select the asset file that you want to import.
parent_uid	String	If needed, assign a parent folder to your asset by passing the UID of the parent folder.
title	String	Enter a title for your uploaded asset.
tags	String	Assign a specific tag(s) to your uploaded asset.
relative_urls	Boolean	Set this to 'true' to display the relative URL of the asset.
include_dimension	Boolean	Set this to 'true' to include the dimensions (height and width) of the image in the response.

import contentstack; 


Contentstack contentstack = new Contentstack.Builder().build();

Asset asset = contentstack.stack().asset();

Call<ResponseBody> response = asset.uploadAsset("filePath", "description").execute();

if (response.isSuccessful){ 

    System.out.println("Response"+ response) 

}

updateDetails

The "Update asset revision" call upgrades a specified version of an asset as the latest version of that asset.

Name	Type	Description
requestBody (required)	JSONObject	JSON Request body.

import contentstack; 


Contentstack contentstack = new Contentstack.Builder().build();

Asset asset = contentstack.stack().asset();

JSONObject body = new JSONObject();

Call<ResponseBody> response = asset.updateDetails(body).execute();

if (response.isSuccessful){ 

    System.out.println("Response"+ response) 

}

unpublish

Unpublish an asset call is used to unpublish a specific version of an asset from a desired environment.

In the case of Scheduled Unpublished, add the scheduled_at key and provide the date/time in the ISO format as its value. Example: "scheduled_at":"2016-10-07T12:34:36.000Z"

Name	Type	Description
requestBody (required)	JSONObject	JSON Request body.

import contentstack; 


Contentstack contentstack = new Contentstack.Builder().build();

Asset asset = contentstack.stack().asset();

JSONObject body = new JSONBody();

Call<ResponseBody> response = asset.unpublish(body).execute();

if (response.isSuccessful){ 

    System.out.println("Response"+ response) 

}

subfolder

The "Get assets and folders of a parent folder" retrieves details of assets and asset subfolders within a specific parent asset folder.

Name	Type	Description
folderUid (required)	String	Folder uid.
isIncludeFolders (required)	Boolean	Provide true or false.

import contentstack; 


Contentstack contentstack = new Contentstack.Builder().build();

Asset asset = contentstack.stack().asset();

JSONObject body = new JSONBody();

Call<ResponseBody> response = asset.subfolder("folderUid", True).execute();

if (response.isSuccessful){ 

    System.out.println("Response"+ response) 

}

setVersionName

The "Set version name for asset" request allows you to assign a name to a specific version of an asset.

Name	Type	Description
versionNumber (required)	Integer	Asset version number.
requestBody (required)	JSONObject	The request body of JSONObject.

import contentstack; 


Contentstack contentstack = new Contentstack.Builder().build();

Asset asset = contentstack.stack().asset();

JSONObject body = new JSONBody();

Call<ResponseBody> response = asset.setVersionName(3, body).execute();

if (response.isSuccessful){ 

    System.out.println("Response"+ response) 

}

rteInformation

The "Get information on RTE assets" call returns comprehensive information on all assets uploaded through the Rich Text Editor field.

import contentstack; 


Contentstack contentstack = new Contentstack.Builder().build();

Asset asset = contentstack.stack().asset();

Call<ResponseBody> response = asset.rteInformation().execute();

if (response.isSuccessful){ 

    System.out.println("Response"+ response) 

}

replace

The Replace asset call will replace an existing asset with another file on the stack.

Tip: You can try the call manually in any REST API client, such as Postman. Under Body, pass a body parameter named asset[upload] and select the input type as 'File'. This will enable you to select the file that you wish to import. You can assign a parent folder to your asset by using the asset[parent_uid] parameter, where you can pass the UID of the parent folder. Additionally, you can pass optional parameters such as asset[title] and asset[description] which let you enter a title and a description for the uploaded asset, respectively.

Name	Type	Description
filePath (required)	String	The file path.
description (required)	String	The file description.

import contentstack; 


Contentstack contentstack = new Contentstack.Builder().build();

Asset asset = contentstack.stack().asset();

Call<ResponseBody> response = asset.replace("filePath", "description").execute();

if (response.isSuccessful){ 

    System.out.println("Response"+ response) 

}

getVersionNameDetails

The "Get details of all versions of an asset" request allows you to retrieve the details of all the versions of an asset.

The details returned include the actual version number of the asset; the version name along with details such as the assigned version name, the UID of the user who assigned the name, and the time when the version was assigned a name; and the count of the versions.

Name	Type	Description
limit	Integer	Enter the maximum number of version details to be returned.
named	Boolean	Set to true if you want to retrieve only the named versions of your asset.
include_count	Boolean	Enter 'true' to get the total count of the asset version details.

import contentstack; 


Contentstack contentstack = new Contentstack.Builder().build();

Asset asset = contentstack.stack().asset();

JSONObject body = new JSONBody();

Call<ResponseBody> response = asset. getVersionNameDetails().execute();

if (response.isSuccessful){ 

    System.out.println("Response"+ response) 

}

getReferences

The "Get asset references" request returns the details of the entries and the content types in which the specified asset is referenced.

import contentstack; 


Contentstack contentstack = new Contentstack.Builder().build();

Asset asset = contentstack.stack().asset();

JSONObject body = new JSONBody();

Call<ResponseBody> response = asset. getReferences().execute();

if (response.isSuccessful){ 

    System.out.println("Response"+ response) 

}

publish

The "Publish an asset" call is used to publish a specific version of an asset on the desired environment either immediately or at a later date/time.

In case of Scheduled Publishing, add the scheduled_at key and provide the date/time in the ISO format as its value. Example: "scheduled_at":"2016-10-07T12:34:36.000Z"

Name	Type	Description
requestBody (required)	JSONObject	JSON Request body.

import contentstack; 


Contentstack contentstack = new Contentstack.Builder().build();

Asset asset = contentstack.stack().asset();

JSONObject body = new JSONBody();

Call<ResponseBody> response = asset.publish(body).execute();

if (response.isSuccessful){ 

    System.out.println("Response"+ response) 

}

getPermanentUrl

The "Download an asset with a permanent URL" request displays an asset in the response. The asset returned to the response can be saved to your local storage system. Make sure to specify the unique identifier (slug) in the request URL.

This request will return the most recent version of the asset; however, to download the latest published version of the asset, pass the environment query parameter with the environment name.

Name	Type	Description
slugUrl (required)	String	The unique identifier of the asset.

import contentstack; 


Contentstack contentstack = new Contentstack.Builder().build();

Asset asset = contentstack.stack().asset();

Call<ResponseBody> response = asset.getPermanentUrl("slugUrl").execute();

if (response.isSuccessful){ 

    System.out.println("Response"+ response) 

}

getByType

Based on the query request, "Get either images or videos" retrieves assets that are either image files or video files.

Name	Type	Description
assetType (required)	String	Asset type that you want to retrieve. - For images, "images" - For videos, "videos"

import contentstack; 


Contentstack contentstack = new Contentstack.Builder().build();

Asset asset = contentstack.stack().asset();

Call<ResponseBody> response = asset.getByType("assetType").execute();

if (response.isSuccessful){ 

    System.out.println("Response"+ response) 

}

generatePermanentUrl

Generate Permanent Asset URL request allows you to generate a permanent URL for an asset. This URL remains constant irrespective of any subsequent updates to the asset.

Name	Type	Description
body (required)	JSONObject	The JSONObject request body.

import contentstack; 


Contentstack contentstack = new Contentstack.Builder().build();

Asset asset = contentstack.stack().asset();

JSONObject body = new JSONBody();

Call<ResponseBody> response = asset.generatePermanentUrl(body).execute();

if (response.isSuccessful){ 

    System.out.println("Response"+ response) 

}

folder

Get folder instance.

Name	Type	Description
folderUid	String	The UID of the folder that you want either to update or move.

import contentstack; 


Contentstack contentstack = new Contentstack.Builder().build();

Asset asset = contentstack.stack().asset();

Call<ResponseBody> response = asset.folder("folderUid").execute();

[OR]

Call<ResponseBody> response = asset.folder().execute();

if (response.isSuccessful){ 

    System.out.println("Response"+ response) 

}

find

The "Get all assets" request returns comprehensive information on all assets available in a stack.

Name	Type	Description
include_asset_scan_status	Boolean	When true, includes the _asset_scan_status field in the asset response (pending, clean, quarantined, or not_scanned). Opt-in; omitted from the request by default.

import contentstack; 


Contentstack contentstack = new Contentstack.Builder().build();

Asset asset = contentstack.stack().asset();

Call<ResponseBody> response = asset.find().execute();

if (response.isSuccessful){ 

    System.out.println("Response"+ response) 

}

fetch

The "Get an asset" call returns comprehensive information about a specific version of an asset of a stack

TipTo include the publishing details in the response, use the include_publish_details parameter and set its value to ‘true'. This query will return the publishing details of the entry in every environment, along with the version number published in each environment.

Name	Type	Description
include_asset_scan_status	Boolean	When true, includes the _asset_scan_status field in the asset response (pending, clean, quarantined, or not_scanned). Opt-in; omitted from the request by default.

import contentstack; 


Contentstack contentstack = new Contentstack.Builder().build();

Asset asset = contentstack.stack().asset();

Call<ResponseBody> response = asset.fetch().execute();

if (response.isSuccessful){ 

    System.out.println("Response"+ response) 

}

deleteVersionName

The "Delete Version Name of an Asset" request allows you to delete the name assigned to a specific version of an asset. This request resets the name of the asset version to the version number.

Name	Type	Description
versionNumber (required)	Integer	The asset version.

import contentstack; 


Contentstack contentstack = new Contentstack.Builder().build();

Asset asset = contentstack.stack().asset();

Call<ResponseBody> response = asset.deleteVersionName(version).execute();

if (response.isSuccessful){ 

    System.out.println("Response"+ response) 

}

delete

Delete asset call deletes an existing asset from the stack.

import contentstack; 


Contentstack contentstack = new Contentstack.Builder().build();

Asset asset = contentstack.stack().asset();

Call<ResponseBody> response = asset.delete().execute();

if (response.isSuccessful){ 

    System.out.println("Response"+ response) 

}

byFolderUid

The "Get assets of a specific folder" retrieves all assets of a specific asset folder; however, it doesn't retrieve the details of sub-folders within it.

Name	Type	Description
folderUid (required)	String	The folderUid of a specific folder.

import contentstack; 


Contentstack contentstack = new Contentstack.Builder().build();

Asset asset = contentstack.stack().asset();

Call<ResponseBody> response = asset.byFolderUid("folderUid").execute();

if (response.isSuccessful){ 

    System.out.println("Response"+ response) 

}

removeParam

Set header for the request.

Name	Type	Description
key (required)	String	Removes query parameter using a key of request.

import contentstack; 


Contentstack contentstack = new Contentstack.Builder().build();

Asset asset = contentstack.stack().asset().removeParam("key");

addParam

The addParam method adds a query parameter to the Asset request for filtering or configuring the response (e.g., locale, publish details).

Name	Type	Description
key (required)	String	Query parameter name sent with the request (for example, locale or include_publish_details). Set when building the request and applied to Asset methods such as find() and fetch(). Default: None
value (required)	Object	Value assigned to the query parameter. Determines the behavior or filtering applied to the request (for example, "en-us" for locale, or true for include_publish_details). Default: None

Value Handling in Requests:

Values are serialized to strings when sent over HTTP.
- Boolean: true/false
- Number: decimal string (e.g., 10, 3.14)
- String: sent as it is
Pass simple types that align with API expectations:
- String (e.g., "en-us")
- Boolean (e.g., true)
- Numeric types (Integer, Long, etc.)
The value parameter must not be null.

Additional Resource Refer to the asset method for the complete list of query parameters that could be passed in the key.

Example

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Asset;
import java.io.IOException;
import java.util.HashMap;
import java.util.Map;

Map<String, Object> headers = new HashMap<>();
headers.put("api_key", "<API_KEY>");
headers.put("authorization", "<MANAGEMENT_TOKEN>");
Contentstack client = new Contentstack.Builder().build();
Asset asset = client.stack(headers).asset("<ASSET_UID>");
asset.addParam("locale", "en-us");
asset.addParam("include_publish_details", true);
try {
    var response = asset.fetch().execute();
    if (response.isSuccessful()) {
        // Use response.body()
    }
} catch (IOException e) {
    // Handle error
}

addHeader

Sets header for the request.

Name	Type	Description
key (required)	String	Header key for the request.
value (required)	Object	Header value for the request.

import contentstack; 


Contentstack contentstack = new Contentstack.Builder().build();

Asset asset = contentstack.stack().asset();

asset.addHeader("key", value)

fetchAsPojo

The fetchAsPojo method fetches a single asset by UID and deserializes it into a POJO.

import contentstack; 


Contentstack contentstack = new Contentstack.Builder().build();

Asset asset = contentstack.stack().asset("asset_uid");

Response&glt;AssetResponse> response = asset.fetchAsPojo().execute();

if (response.isSuccessful() && response.body() != null) {

    AssetResponse assetResponse = response.body();

    AssetPojo pojo = assetResponse.getAssetPojo();

    System.out.println(" Asset URL: " + pojo.url);

} else {

    System.out.println("Error: " + response.errorBody().string());

}

findAsPojo

The findAsPojo method fetches multiple assets and deserializes them into POJOs.

import contentstack; 


Contentstack contentstack = new Contentstack.Builder().build();

Response<AssetListResponse> response = contentstack.stack().asset().findAsPojo().execute();

if (response.isSuccessful() && response.body() != null) {

    AssetListResponse assetListResponse = response.body();

    List<AssetPojo> assets = assetListResponse.getAssets();

    for (AssetPojo asset : assets) {

        System.out.println(" Asset UID: " + asset.uid);

    }

} else {

    System.out.println("Error: " + response.errorBody().string());

}

byFolderUidAsPojo

The byFolderUidAsPojo method retrieves all assets of a specific asset folder; however, it doesn't retrieve the details of sub-folders within it.

import contentstack; 

Contentstack contentstack = new Contentstack.Builder().build();
Response<AssetListResponse> response = contentstack.stack().asset().byFolderUidAsPojo("folder_uid").execute();
if (response.isSuccessful() && response.body() != null) {
    AssetListResponse assetListResponse = response.body();
    List<AssetPojo> assets = assetListResponse.getAssets();
    for (AssetPojo asset : assets) {
        System.out.println(" Asset UID: " + asset.uid);
    }
} else {
    System.out.println("Error: " + response.errorBody().string());
}

subfolderAsPojo

The subfolderAsPojo method retrieves details of assets and asset subfolders within a specific parent asset folder.

import contentstack; 

Contentstack contentstack = new Contentstack.Builder().build();
Response<AssetListResponse> response = contentstack.stack().asset().subfolderAsPojo("folder_uid", true).execute();
if (response.isSuccessful() && response.body() != null) {
    AssetListResponse assetListResponse = response.body();
    List<AssetPojo> assets = assetListResponse.getAssets();
    for (AssetPojo asset : assets) {
        System.out.println(" Asset Title: " + asset.title);
    }
} else {
    System.out.println("Error: " + response.errorBody().string());
}

getSingleFolderByNameAsPojo

The getSingleFolderByNameAsPojo method retrieves a folder by name and deserializes into POJOs.

import contentstack; 

Contentstack contentstack = new Contentstack.Builder().build();
Asset asset = contentstack.stack().asset();
JSONObject queryContent = new JSONObject();
        queryContent.put("is_dir", true);
        queryContent.put("name", "sub_folder");
        asset.addParam("query", queryContent);
Response<AssetListResponse> response =
asset.getSingleFolderByNameAsPojo().execute();
if (response.isSuccessful() && response.body() != null) {
    AssetListResponse assetListResponse = response.body();
 if (assetListResponse != null) {
    List<AssetPojo> assetPojos = assetListResponse.getAssets();
     for (AssetPojo assetPojo : assetPojos) {
    System.out.println(" Asset UID: " + assetPojo.uid);
    System.out.println(" Asset Title: " + assetPojo.title);          
        }
    }
} else {
    System.out.println("Error: " + response.errorBody().string());
}

getSubfolderAsPojo

The getSubfolderAsPojo method fetches all subfolders.

import contentstack; 

Contentstack contentstack = new Contentstack.Builder().build();
Asset asset = contentstack.stack().asset();
JSONObject queryContent = new JSONObject();
        queryContent.put("is_dir", true);  
        asset.addParam("folder", "blt4f46298330ee5f99");
        asset.addParam("include_folders", true);    
        asset.addParam("query", queryContent);

Response<AssetListResponse> response = asset.getSubfolderAsPojo().execute();
if (response.isSuccessful() && response.body() != null) {
    AssetListResponse assetListResponse = response.body();
    if (assetListResponse != null) {
    List<AssetPojo> assetPojos = assetListResponse.getAssets();
     for (AssetPojo assetPojo : assetPojos) {
    System.out.println(" Asset UID: " + assetPojo.uid);
    System.out.println(" Asset Title: " + assetPojo.title);          
        }
    }
} else {
    System.out.println("Error: " + response.errorBody().string());
}

Asset

Asset

uploadAsset

updateDetails​

unpublish

subfolder

setVersionName

rteInformation

replace

getVersionNameDetails

getReferences

publish

getPermanentUrl

getByType

generatePermanentUrl

folder

find

fetch

deleteVersionName

delete

byFolderUid

removeParam

addParam

addHeader

fetchAsPojo

findAsPojo

byFolderUidAsPojo

subfolderAsPojo

getSingleFolderByNameAsPojo

getSubfolderAsPojo

updateDetails