Asset
Asset
An asset is a file, such as an image, video, PDF, or audio file, that you upload to a stack and use in entries. Use this class to
- upload a file, replace it, or change its title and description
- list assets, the assets in one folder, or only images or videos
- publish, unpublish, or delete an asset
- name asset versions and see where an asset is in use
- open the Folder class for asset folder requests
The asset method on Stack returns a new Asset. It has two forms:
| Name | Type | Description |
|---|---|---|
| assetUid | String | UID of the asset. Omit it to work on all assets. |
Additional Resource The Assets section of the Content Management API (CMA) reference describes every asset request and its response.
addHeader
addHeader adds one request header to the requests that this asset object sends.
| Name | Type | Description |
|---|---|---|
| key (required) | String | Name of the request header. |
| value (required) | String | Value of the request header. |
Returns: Asset. The same asset, for chaining.
Validation
- There is no client-side validation. addHeader stores any key and value.
- An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.
- A null key or value passes here. execute() then throws IllegalArgumentException on the next request.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Client-side only. addHeader stores the header on this asset object and makes no request.
- Every request method on this asset object sends every stored header.
- stack.asset() copies the stack's headers into the new object, and folder copies this object's headers into each Folder it returns. addHeader changes only this object, not the stack or other objects.
- A second call with the same key replaces the first value, including a header the stack set, such as authorization or branch.
Example
Basic usage: fetch an asset from another branch
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Asset;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class FetchAssetOnBranch {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Asset asset = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").asset("<ASSET_UID>")
.addHeader("branch", "<BRANCH>");
Response<ResponseBody> response = asset.fetch().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}addHeaders
addHeaders adds several request headers at once to the requests that this asset object sends.
| Name | Type | Description |
|---|---|---|
| headers (required) | HashMap<String, String> | Header names and values to add. |
Returns: Asset. The same asset, for chaining.
Validation
- Throws NullPointerException when the map is null, because addHeaders copies its entries.
- An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Client-side only. addHeaders copies every pair into the headers of this asset object and makes no request.
- Every request method on this asset object sends every stored header.
- A key that already exists takes the new value, including a header the stack set, such as authorization or branch.
Example
Basic usage: add headers from a map
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Asset;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
import java.util.HashMap;
public class ListAssetsWithHeaders {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
HashMap<String, String> headers = new HashMap<>();
headers.put("branch", "<BRANCH>");
Asset asset = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").asset().addHeaders(headers);
Response<ResponseBody> response = asset.find().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}addParam
addParam adds one query parameter to the requests that this asset object sends.
| Name | Type | Description |
|---|---|---|
| key (required) | String | Name of the query parameter. |
| value (required) | Object | Value of the query parameter. |
Returns: Asset. The same asset, for chaining.
Validation
- There is no client-side validation. addParam stores any key and value.
- An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.
- A null key or value passes here. execute() then throws IllegalArgumentException on a request that sends query parameters.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Client-side only. addParam stores the pair on this asset object and makes no request.
- Every request method sends the stored parameters except generatePermanentUrl, delete, setVersionName, deleteVersionName, getReferences, getByType, publish, and unpublish.
- The SDK writes the value with its toString() method. Pass a JSONObject for a JSON value such as query, because its toString() returns JSON.
- A second call with the same key replaces the first value. The parameter stays on the object for every later request. Asset has no public method that removes a parameter, so call stack.asset() again to start without one.
- byFolderUid and subfolder write folder and include_folders into the same parameters, so those values also stay for later requests.
Example
Basic usage: include the total count when you list assets
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Asset;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class CountAssets {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Asset asset = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").asset()
.addParam("include_count", true);
Response<ResponseBody> response = asset.find().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}addParams
addParams adds several query parameters at once to the requests that this asset object sends.
| Name | Type | Description |
|---|---|---|
| headers (required) | HashMap<String, Object> | Query parameter names and values to add. |
Returns: Asset. The same asset, for chaining.
Validation
- Throws NullPointerException when the map is null, because addParams copies its entries.
- An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Client-side only. addParams copies every pair into the query parameters of this asset object and makes no request.
- Every request method sends the stored parameters except generatePermanentUrl, delete, setVersionName, deleteVersionName, getReferences, getByType, publish, and unpublish.
- A key that already exists takes the new value. Keys that are not in the map keep their values.
- The SDK signature names the parameter headers, but addParams writes query parameters, not headers.
Example
Basic usage: list root assets with their folders
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Asset;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
import java.util.HashMap;
public class ListRootAssets {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
HashMap<String, Object> params = new HashMap<>();
params.put("folder", "cs_root");
params.put("include_folders", true);
Asset asset = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").asset().addParams(params);
Response<ResponseBody> response = asset.find().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}byFolderUid
byFolderUid builds the request that lists the assets in one asset folder, without its subfolders.
| Name | Type | Description |
|---|---|---|
| folderUid (required) | String | UID of the asset folder. |
Returns: Call<ResponseBody>. The request for the assets in the folder, sent when you call execute().
Validation
- There is no client-side validation. byFolderUid does not check folderUid.
- A null folderUid passes here. execute() then throws IllegalArgumentException.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One execute() sends one Get assets of a specific folder request (GET /v3/assets?folder={folder_uid}) with the headers and query parameters on this object.
- byFolderUid writes folder into the query parameters of this asset object, and the value stays for every later request from it. Call stack.asset() again for a request without it.
- The API returns the assets of the folder and not the details of its subfolders. To include subfolders, use the subfolder method.
- The response body is the raw JSON from the API, with the assets under an assets array.
Example
Basic usage: list the assets in a folder
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Asset;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class ListFolderAssets {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Asset asset = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").asset();
Response<ResponseBody> response = asset.byFolderUid("<FOLDER_UID>").execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}byFolderUidAsPojo
byFolderUidAsPojo builds the request that lists the assets in one asset folder, with a typed response.
| Name | Type | Description |
|---|---|---|
| folderUid (required) | String | UID of the asset folder. |
Returns: Call<AssetListResponse>. The request for the assets in the folder as typed objects, sent when you call execute().
Validation
- There is no client-side validation. byFolderUidAsPojo does not check folderUid.
- A null folderUid passes here. execute() then throws IllegalArgumentException.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One execute() sends the same Get assets of a specific folder request as byFolderUid.
- byFolderUidAsPojo writes folder into the query parameters of this asset object, and the value stays for every later request from it. Call stack.asset() again for a request without it.
- Gson reads the assets array of the response into an AssetListResponse. getAssets() returns a List<AssetPojo>, and getRawJson() returns every item as a Map<String, Object> with all its keys.
- AssetPojo exposes getTitle() only. It returns the name for a folder, whose content_type is application/vnd.contenstack.folder, and the title for a file. It throws NullPointerException for an item without content_type. Read other values from getRawJson().
- AssetListResponse keeps only the assets array, so top-level keys such as count are not available. Use the ResponseBody form of the method to read them.
Example
Basic usage: print the title of each asset in a folder
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Asset;
import com.contentstack.cms.stack.AssetListResponse;
import com.contentstack.cms.stack.AssetPojo;
import retrofit2.Response;
import java.io.IOException;
import java.util.List;
public class ListFolderAssetTitles {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Asset asset = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").asset();
Response<AssetListResponse> response = asset.byFolderUidAsPojo("<FOLDER_UID>").execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
List<AssetPojo> items = response.body().getAssets();
for (AssetPojo item : items) {
System.out.println(item.getTitle());
}
}
}delete
delete builds the request that deletes one asset from the stack.
Returns: Call<ResponseBody>. The request for the deletion notice, sent when you call execute().
Validation
- Throws NullPointerException when the asset has no UID, because the request path needs one. Create the object with stack.asset("<ASSET_UID>").
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
Warning delete removes the asset and its file from the stack. The asset requests in the API reference include no restore request, so upload the file again if you need it back.
- One execute() sends one Delete asset request (DELETE /v3/assets/{asset_uid}) with the headers on this object. It does not send the query parameters from addParam.
- The response body is the raw JSON from the API, with a notice message.
Example
Basic usage: delete an asset
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Asset;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class DeleteAsset {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Asset asset = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").asset("<ASSET_UID>");
Response<ResponseBody> response = asset.delete().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}deleteVersionName
deleteVersionName builds the request that removes the name from one version of an asset.
| Name | Type | Description |
|---|---|---|
| versionNumber (required) | int | Asset version whose name to remove. |
Returns: Call<ResponseBody>. The request that removes the version name, sent when you call execute().
Validation
- Throws NullPointerException when the asset has no UID, because the request path needs one. Create the object with stack.asset("<ASSET_UID>").
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
Warning deleteVersionName removes the name, and the version shows its version number again. The version itself stays. Set a name again with the setVersionName method.
- One execute() sends one Delete Version Name of Asset request (DELETE /v3/assets/{asset_uid}/versions/{version_number}/name) with the headers on this object.
- The API reference lists status 204 for this request. Retrofit returns a null body for a 204 response, so check response.code() instead of reading the body.
Example
Basic usage: remove the name of version 3
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Asset;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class RemoveAssetVersionName {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Asset asset = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").asset("<ASSET_UID>");
Response<ResponseBody> response = asset.deleteVersionName(3).execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println("Version name removed, status " + response.code());
}
}fetch
fetch builds the request that retrieves one asset by its UID.
Returns: Call<ResponseBody>. The request for the asset, sent when you call execute().
Validation
- Throws NullPointerException when the asset has no UID, because the request path needs one. Create the object with stack.asset("<ASSET_UID>").
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One execute() sends one Get an asset request (GET /v3/assets/{asset_uid}) with the headers and query parameters on this object.
- The API reference lists the following query parameters for this request. Add them with addParam:
- version: the asset version to return. Without it, the API returns the latest version.
- environment: the environment whose published version to return.
- include_path, include_publish_details, relative_urls, include_branch, and include_metadata: true adds that detail.
- The response body is the raw JSON from the API, with the asset under an asset key.
- For the same request with a typed response, use the fetchAsPojo method.
Example
Basic usage: fetch one asset
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Asset;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class FetchAsset {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Asset asset = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").asset("<ASSET_UID>");
Response<ResponseBody> response = asset.fetch().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}Query parameters: fetch version 2 of an asset with its publish details
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Asset;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class FetchAssetVersion {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Asset asset = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").asset("<ASSET_UID>")
.addParam("version", 2)
.addParam("include_publish_details", true);
Response<ResponseBody> response = asset.fetch().execute();
if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
System.out.println(response.body().string());
}
}fetchAsPojo
fetchAsPojo builds the request that retrieves one asset by its UID, with a typed response.
Returns: Call<AssetResponse>. The request for the asset as a typed object, sent when you call execute().
Validation
- Throws NullPointerException when the asset has no UID, because the request path needs one. Create the object with stack.asset("<ASSET_UID>").
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
- On a rejection response.body() is null, so check isSuccessful() before you read it.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One execute() sends the same Get an asset request as fetch (GET /v3/assets/{asset_uid}), with the headers and query parameters on this object.
- Gson reads the asset object of the response into an AssetResponse. getAssetPojo() returns an AssetPojo, and getRawJson() returns the asset as a Map<String, Object> with all its keys.
- AssetPojo exposes getTitle() only. Read the URL, file name, size, and other values from getRawJson().
Example
Basic usage: read the title and URL of an asset
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Asset;
import com.contentstack.cms.stack.AssetResponse;
import retrofit2.Response;
import java.io.IOException;
public class ReadAssetDetails {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Asset asset = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").asset("<ASSET_UID>");
Response<AssetResponse> response = asset.fetchAsPojo().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
AssetResponse body = response.body();
System.out.println(body.getAssetPojo().getTitle());
System.out.println(body.getRawJson().get("url"));
}
}find
find builds the request that lists the assets in the stack.
Returns: Call<ResponseBody>. The request for the stack's assets, sent when you call execute().
Validation
- There is no client-side validation.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One execute() sends one Get all assets request (GET /v3/assets) with the headers and query parameters on this object.
- The API reference lists the following query parameters for this request, among others. Add them with addParam:
- folder: a folder UID, or cs_root for the root folder.
- include_folders: true adds folder details to the list.
- environment: the environment whose published assets to return.
- include_publish_details, include_count, relative_urls, include_branch, and include_metadata: true adds that detail.
- asc and desc: the field UID to sort by.
- The response body is the raw JSON from the API, with the assets under an assets array.
- The SDK sends one request and does not page through results.
- For the same request with a typed response, use the findAsPojo method.
Example
Basic usage: list the assets in the stack
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Asset;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class ListAssets {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Asset asset = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").asset();
Response<ResponseBody> response = asset.find().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}Query parameters: list root assets and folders in order of creation date, with a count
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Asset;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class ListRootAssetsSorted {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Asset asset = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").asset()
.addParam("folder", "cs_root")
.addParam("include_folders", true)
.addParam("asc", "created_at")
.addParam("include_count", true);
Response<ResponseBody> response = asset.find().execute();
if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
System.out.println(response.body().string());
}
}findAsPojo
findAsPojo builds the request that lists the assets in the stack, with a typed response.
Returns: Call<AssetListResponse>. The request for the stack's assets as typed objects, sent when you call execute().
Validation
- There is no client-side validation.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
- On a rejection response.body() is null, so check isSuccessful() before you call getAssets().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One execute() sends the same Get all assets request as find (GET /v3/assets), with the headers and query parameters on this object.
- Gson reads the assets array of the response into an AssetListResponse. getAssets() returns a List<AssetPojo>, and getRawJson() returns every item as a Map<String, Object> with all its keys.
- AssetPojo exposes getTitle() only. It returns the name for a folder, whose content_type is application/vnd.contenstack.folder, and the title for a file. It throws NullPointerException for an item without content_type. Read other values from getRawJson().
- AssetListResponse keeps only the assets array, so top-level keys such as count are not available. Use the ResponseBody form of the method to read them.
Example
Basic usage: print the title of each asset
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Asset;
import com.contentstack.cms.stack.AssetListResponse;
import com.contentstack.cms.stack.AssetPojo;
import retrofit2.Response;
import java.io.IOException;
import java.util.List;
public class ListAssetTitles {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Asset asset = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").asset();
Response<AssetListResponse> response = asset.findAsPojo().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
List<AssetPojo> items = response.body().getAssets();
for (AssetPojo item : items) {
System.out.println(item.getTitle());
}
}
}folder
folder returns a Folder object for asset folder requests, either for a new folder or for one existing folder.
| Name | Type | Description |
|---|---|---|
| folderUid (required) | String | UID of an existing folder. |
Returns: Folder. A new folder object.
Overloads
- folder(): This overload takes no parameters. It returns a Folder for create.
- folder(String folderUid)
Validation
- There is no client-side validation. folder accepts any UID, including null and an empty string.
- The Folder request methods fetch, update, and delete throw IllegalAccessError when the folder holds no UID or an empty UID.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Client-side only. folder makes no request.
- The new Folder gets a copy of this asset's headers, including any header from addHeader. It does not get this asset's query parameters.
- See the Folder class for the requests a folder sends.
Example
Basic usage: create a folder and fetch another one
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Asset;
import com.contentstack.cms.stack.Folder;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class UseAssetFolders {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Asset asset = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").asset();
JSONObject details = new JSONObject();
details.put("name", "docs-test-images");
JSONObject body = new JSONObject();
body.put("asset", details);
Response<ResponseBody> created = asset.folder().create(body).execute();
if (!created.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + created.code() + " " + created.errorBody().string());
return;
}
System.out.println(created.body().string());
Folder existing = asset.folder("<FOLDER_UID>");
Response<ResponseBody> response = existing.fetch().execute();
if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
System.out.println(response.body().string());
}
}generatePermanentUrl
generatePermanentUrl builds the request that gives an asset a permanent URL, which stays the same when the asset changes later.
| Name | Type | Description |
|---|---|---|
| body (required) | JSONObject | Request body with the URL under an asset key. |
| body.asset.permanent_url (required) | String | Permanent URL, ending in a slug you choose. |
Returns: Call<ResponseBody>. The request for the asset with its permanent URL, sent when you call execute().
Validation
- Throws NullPointerException when the asset has no UID, because the request path needs one. Create the object with stack.asset("<ASSET_UID>").
- execute() throws IllegalArgumentException when body is null, because the request needs a body.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
Warning The API lets you generate the permanent URL of an asset only once. After that you can no longer change it, so choose the slug with care.
- One execute() sends one Generate permanent asset URL request (PUT /v3/assets/{asset_uid}) with body as the JSON body and the headers on this object. It does not send the query parameters from addParam.
- The API reference gives the URL format https://images.contentstack.io/v3/assets/{stack_api_key}/{asset_uid}/{slug}, where the slug is any unique identifier.
- The response body is the raw JSON from the API, with the asset under an asset key.
- To download the asset through the slug, use the getPermanentUrl method.
Example
Basic usage: give an asset a permanent URL
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Asset;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class CreatePermanentUrl {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Asset asset = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").asset("<ASSET_UID>");
JSONObject details = new JSONObject();
details.put("permanent_url", "https://images.contentstack.io/v3/assets/<API_KEY>/<ASSET_UID>/spring-hero.jpeg");
JSONObject body = new JSONObject();
body.put("asset", details);
Response<ResponseBody> response = asset.generatePermanentUrl(body).execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}getByType
getByType builds the request that lists only the image assets or only the video assets of the stack.
| Name | Type | Description |
|---|---|---|
| assetType (required) | String | images or videos. |
Returns: Call<ResponseBody>. The request for the image or video assets, sent when you call execute().
Validation
- There is no client-side validation. getByType sends any assetType value.
- A null assetType passes here. execute() then throws IllegalArgumentException.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One execute() sends one Get either only images or videos request (GET /v3/assets/{asset_type}) with the headers on this object.
- getByType does not send query parameters, so a query or include_branch parameter from addParam never reaches the API on this request.
- The response body is the raw JSON from the API, with the assets under an assets array.
Example
Basic usage: list the image assets
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Asset;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class ListImageAssets {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Asset asset = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").asset();
Response<ResponseBody> response = asset.getByType("images").execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}Videos: list the video assets
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Asset;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class ListVideoAssets {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Asset asset = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").asset();
Response<ResponseBody> response = asset.getByType("videos").execute();
if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
System.out.println(response.body().string());
}
}getPermanentUrl
getPermanentUrl builds the request that downloads an asset through the slug of its permanent URL.
| Name | Type | Description |
|---|---|---|
| slugUrl (required) | String | Slug at the end of the permanent URL. |
Returns: Call<ResponseBody>. The request for the asset file, sent when you call execute().
Validation
- Throws NullPointerException when the asset has no UID, because the request path needs one. Create the object with stack.asset("<ASSET_UID>").
- getPermanentUrl does not check slugUrl. A null slug passes here, and execute() then throws IllegalArgumentException.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One execute() sends GET /v3/assets/{asset_uid}/{slug} to the host of the client, with the headers and query parameters on this object.
- The Download an asset with permanent URL reference documents the path /assets/{api_key}/{asset_uid}/{slug}, with the stack API key before the asset UID.
- Create the permanent URL first with the generatePermanentUrl method.
- The API returns the latest version of the asset. Add the environment parameter with addParam to download the latest published version on that environment.
- The response body is the file itself. Read it with response.body().bytes() or byteStream().
Example
Basic usage: download an asset and save it to a file
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Asset;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Paths;
public class DownloadPermanentAsset {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Asset asset = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").asset("<ASSET_UID>")
.addParam("environment", "<ENVIRONMENT>");
Response<ResponseBody> response = asset.getPermanentUrl("spring-hero.jpeg").execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
Files.write(Paths.get("spring-hero.jpeg"), response.body().bytes());
}
}getReferences
getReferences builds the request that lists the entries and content types that reference an asset.
Returns: Call<ResponseBody>. The request for the entries and content types that reference the asset, sent when you call execute().
Validation
- Throws NullPointerException when the asset has no UID, because the request path needs one. Create the object with stack.asset("<ASSET_UID>").
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One execute() sends one Get asset references request (GET /v3/assets/{asset_uid}/references) with the headers on this object.
- getReferences does not send query parameters. The include_publish_details, include_count, deleted, and include_branch parameters that the API reference lists cannot reach the API through this method.
- The response body is the raw JSON from the API, with the referencing entries under a references array.
Example
Basic usage: list where an asset is in use
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Asset;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class ListAssetReferences {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Asset asset = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").asset("<ASSET_UID>");
Response<ResponseBody> response = asset.getReferences().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}getSingleFolderByName
getSingleFolderByName builds the request that finds an asset folder by its name.
Returns: Call<ResponseBody>. The request for the matching folder, sent when you call execute().
Validation
- There is no client-side validation. getSingleFolderByName does not check that the query parameter is present.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One execute() sends one Get a single folder by name request (GET /v3/assets) with the headers and query parameters on this object.
- getSingleFolderByName adds no parameters itself. Before you call it, add the query parameter with addParam, as a JSONObject with is_dir set to true and name set to the folder name. The SDK writes the object as JSON.
- Without query, the request is the same as find and lists every asset.
- The response body is the raw JSON from the API, with the matching folder under an assets array.
Example
Basic usage: find the folder named Product images
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Asset;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class FindFolderByName {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
JSONObject query = new JSONObject();
query.put("is_dir", true);
query.put("name", "Product images");
Asset asset = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").asset()
.addParam("query", query);
Response<ResponseBody> response = asset.getSingleFolderByName().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}getSingleFolderByNameAsPojo
getSingleFolderByNameAsPojo builds the request that finds an asset folder by its name, with a typed response.
Returns: Call<AssetListResponse>. The request for the matching folder as typed objects, sent when you call execute().
Validation
- There is no client-side validation. getSingleFolderByNameAsPojo does not check that the query parameter is present.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One execute() sends one Get a single folder by name request (GET /v3/assets) with the headers and query parameters on this object.
- getSingleFolderByNameAsPojo adds no parameters itself. Before you call it, add the query parameter with addParam, as a JSONObject with is_dir set to true and name set to the folder name. The SDK writes the object as JSON.
- Without query, the request is the same as find and lists every asset.
- Gson reads the assets array of the response into an AssetListResponse. getAssets() returns a List<AssetPojo>, and getRawJson() returns every item as a Map<String, Object> with all its keys.
- AssetPojo exposes getTitle() only. It returns the name for a folder, whose content_type is application/vnd.contenstack.folder, and the title for a file. It throws NullPointerException for an item without content_type. Read other values from getRawJson().
Example
Basic usage: read the UID of the folder named Product images
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Asset;
import com.contentstack.cms.stack.AssetListResponse;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
import java.util.List;
import java.util.Map;
public class FindFolderUidByName {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
JSONObject query = new JSONObject();
query.put("is_dir", true);
query.put("name", "Product images");
Asset asset = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").asset()
.addParam("query", query);
Response<AssetListResponse> response = asset.getSingleFolderByNameAsPojo().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
List<Map<String, Object>> folders = response.body().getRawJson();
for (Map<String, Object> folder : folders) {
System.out.println(folder.get("name") + " " + folder.get("uid"));
}
}
}getSubfolder
getSubfolder builds the request that lists only the subfolders of one parent folder, without asset files.
Returns: Call<ResponseBody>. The request for the folder's subfolders, sent when you call execute().
Validation
- There is no client-side validation. getSubfolder does not check that the query parameter is present.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One execute() sends one Get subfolders of a parent folder request (GET /v3/assets) with the headers and query parameters on this object.
- getSubfolder adds no parameters itself. Before you call it, add the following three parameters with addParam:
- folder: the UID of the parent folder.
- include_folders: true.
- query: a JSONObject with is_dir set to true, so the API returns folders and no asset files.
- The response body is the raw JSON from the API, with the subfolders under an assets array.
Example
Basic usage: list the subfolders of a folder
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Asset;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class ListSubfolders {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
JSONObject query = new JSONObject();
query.put("is_dir", true);
Asset asset = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").asset()
.addParam("folder", "<FOLDER_UID>")
.addParam("include_folders", true)
.addParam("query", query);
Response<ResponseBody> response = asset.getSubfolder().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}getSubfolderAsPojo
getSubfolderAsPojo builds the request that lists only the subfolders of one parent folder, with a typed response.
Returns: Call<AssetListResponse>. The request for the folder's subfolders as typed objects, sent when you call execute().
Validation
- There is no client-side validation. getSubfolderAsPojo does not check that the query parameter is present.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One execute() sends one Get subfolders of a parent folder request (GET /v3/assets) with the headers and query parameters on this object.
- getSubfolderAsPojo adds no parameters itself. Before you call it, add the following three parameters with addParam:
- folder: the UID of the parent folder.
- include_folders: true.
- query: a JSONObject with is_dir set to true, so the API returns folders and no asset files.
- Gson reads the assets array of the response into an AssetListResponse. getAssets() returns a List<AssetPojo>, and getRawJson() returns every item as a Map<String, Object> with all its keys.
- AssetPojo exposes getTitle() only. It returns the name for a folder, whose content_type is application/vnd.contenstack.folder, and the title for a file. It throws NullPointerException for an item without content_type. Read other values from getRawJson().
Example
Basic usage: print the name of each subfolder
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Asset;
import com.contentstack.cms.stack.AssetListResponse;
import com.contentstack.cms.stack.AssetPojo;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
import java.util.List;
public class ListSubfolderNames {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
JSONObject query = new JSONObject();
query.put("is_dir", true);
Asset asset = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").asset()
.addParam("folder", "<FOLDER_UID>")
.addParam("include_folders", true)
.addParam("query", query);
Response<AssetListResponse> response = asset.getSubfolderAsPojo().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
List<AssetPojo> items = response.body().getAssets();
for (AssetPojo item : items) {
System.out.println(item.getTitle());
}
}
}getVersionNameDetails
getVersionNameDetails builds the request that lists the versions of an asset with their names.
Returns: Call<ResponseBody>. The request for the asset's versions, sent when you call execute().
Validation
- Throws NullPointerException when the asset has no UID, because the request path needs one. Create the object with stack.asset("<ASSET_UID>").
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One execute() sends one Get Details of All Versions of an Asset request (GET /v3/assets/{asset_uid}/versions) with the headers and query parameters on this object.
- The API reference lists the following query parameters for this request. Add them with addParam:
- named: true returns only the named versions.
- include_count: true adds the total number of versions.
- include_updated_at and include_updated_by: true adds when and by whom each version changed.
- The response body is the raw JSON from the API, with the versions under a versions array. A version has _version_name only when it has a name.
Example
Basic usage: list the versions of an asset
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Asset;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class ListAssetVersions {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Asset asset = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").asset("<ASSET_UID>");
Response<ResponseBody> response = asset.getVersionNameDetails().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}Query parameters: list only named versions with a count
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Asset;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class ListNamedAssetVersions {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Asset asset = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").asset("<ASSET_UID>")
.addParam("named", true)
.addParam("include_count", true);
Response<ResponseBody> response = asset.getVersionNameDetails().execute();
if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
System.out.println(response.body().string());
}
}publish
publish builds the request that publishes one version of an asset on the environments and locales you name, now or at a scheduled time.
| Name | Type | Description |
|---|---|---|
| requestBody (required) | JSONObject | Request body with the targets under an asset key. |
| requestBody.asset.environments (required) | List<String> | Environments to publish on. |
| requestBody.asset.locales (required) | List<String> | Locales to publish on. |
| requestBody.version | int | Asset version to publish. |
| requestBody.scheduled_at | String | ISO 8601 date and time to publish later. |
Returns: Call<ResponseBody>. The request for the publish notice, sent when you call execute().
Validation
- Throws NullPointerException when the asset has no UID, because the request path needs one. Create the object with stack.asset("<ASSET_UID>").
- execute() throws IllegalArgumentException when requestBody is null, because the request needs a body.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One execute() sends one Publish an asset request (POST /v3/assets/{asset_uid}/publish) with requestBody as the JSON body and the headers on this object. It does not send the query parameters from addParam.
- The API publishes the metadata of the asset together with the asset.
- Without scheduled_at, the API publishes the asset now. With it, the API schedules the job for that time, for example 2026-12-01T09:00:00.000Z.
- The API queues the job, and the response body holds a notice message, not the published asset. Track the job with the PublishQueue class.
Example
Basic usage: publish an asset on one environment now
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Asset;
import okhttp3.ResponseBody;
import org.json.simple.JSONArray;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class PublishAsset {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Asset asset = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").asset("<ASSET_UID>");
JSONArray environments = new JSONArray();
environments.add("<ENVIRONMENT>");
JSONArray locales = new JSONArray();
locales.add("<LOCALE>");
JSONObject target = new JSONObject();
target.put("environments", environments);
target.put("locales", locales);
JSONObject requestBody = new JSONObject();
requestBody.put("asset", target);
Response<ResponseBody> response = asset.publish(requestBody).execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}All parameters: schedule a publish of version 2
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Asset;
import okhttp3.ResponseBody;
import org.json.simple.JSONArray;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class SchedulePublishAsset {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Asset asset = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").asset("<ASSET_UID>");
JSONArray environments = new JSONArray();
environments.add("<ENVIRONMENT>");
JSONArray locales = new JSONArray();
locales.add("<LOCALE>");
JSONObject target = new JSONObject();
target.put("environments", environments);
target.put("locales", locales);
JSONObject requestBody = new JSONObject();
requestBody.put("asset", target);
requestBody.put("version", 2);
requestBody.put("scheduled_at", "2026-12-01T09:00:00.000Z");
Response<ResponseBody> response = asset.publish(requestBody).execute();
if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
System.out.println(response.body().string());
}
}replace
replace builds the request that replaces the file of an existing asset with another file.
| Name | Type | Description |
|---|---|---|
| filePath (required) | String | Path of the new file. |
| description (required) | String | Description of the asset. |
Returns: Call<ResponseBody>. The request for the replaced asset, sent when you call execute().
Validation
- Throws NullPointerException when the asset has no UID, because the request path needs one. Create the object with stack.asset("<ASSET_UID>").
- Throws NullPointerException when filePath or description is null.
- When filePath is empty or names no existing file, the SDK sends the request without a file, and the API rejects it.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One execute() sends one Replace asset request (PUT /v3/assets/{asset_uid}) as multipart form data, with the headers and query parameters on this object.
- The SDK sends two form fields: asset[upload] with the file, and asset[description]. It sets the content type of the file from its name with Java's built-in file name map.
- replace does not send a title or parent folder. Change those with the updateDetails method.
- The API reference lists environment, relative_urls, and include_branch as query parameters for this request. Add them with addParam.
- The response body is the raw JSON from the API, with the asset under an asset key.
Example
Basic usage: replace the file of an asset
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Asset;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class ReplaceAssetFile {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Asset asset = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").asset("<ASSET_UID>");
Response<ResponseBody> response = asset.replace("<FILE_PATH>", "Updated hero image").execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}rteInformation
rteInformation builds the request that lists the assets uploaded through the Rich Text Editor (RTE) field.
Returns: Call<ResponseBody>. The request for the Rich Text Editor assets, sent when you call execute().
Validation
- There is no client-side validation.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One execute() sends one Get information on RTE assets request (GET /v3/assets/rt) with the headers and query parameters on this object.
- The API reference lists include_branch for this request. Add it with addParam.
- The response body is the raw JSON from the API, a top-level array in which each item has an image URL, a thumb URL, and a title.
Example
Basic usage: list the RTE assets
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Asset;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class ListRteAssets {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Asset asset = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").asset();
Response<ResponseBody> response = asset.rteInformation().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}setVersionName
setVersionName builds the request that gives a name to one version of an asset.
| Name | Type | Description |
|---|---|---|
| versionNumber (required) | int | Asset version to name. |
| requestBody (required) | JSONObject | Request body with the name under an upload key. |
| requestBody.upload._version_name (required) | String | Name for the version. |
Returns: Call<ResponseBody>. The request for the named asset version, sent when you call execute().
Validation
- setVersionName does not check the asset UID. On an asset without a UID, execute() throws IllegalArgumentException, because the request path needs one.
- execute() throws IllegalArgumentException when requestBody is null, because the request needs a body.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One execute() sends one Set Version Name for Asset request (POST /v3/assets/{asset_uid}/versions/{version_number}/name) with requestBody as the JSON body and the headers on this object. It does not send the query parameters from addParam.
- The response body is the raw JSON from the API, with a notice message.
- To read the names, use the getVersionNameDetails method.
Example
Basic usage: name version 3 of an asset
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Asset;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class NameAssetVersion {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Asset asset = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").asset("<ASSET_UID>");
JSONObject upload = new JSONObject();
upload.put("_version_name", "Spring campaign final");
JSONObject requestBody = new JSONObject();
requestBody.put("upload", upload);
Response<ResponseBody> response = asset.setVersionName(3, requestBody).execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}subfolder
subfolder builds the request that lists the assets and, optionally, the subfolders inside one parent folder.
| Name | Type | Description |
|---|---|---|
| folderUid (required) | String | UID of the parent folder. |
| isIncludeFolders (required) | Boolean | true adds the subfolders to the list. |
Returns: Call<ResponseBody>. The request for the assets and subfolders in the folder, sent when you call execute().
Validation
- There is no client-side validation.
- A null folderUid or isIncludeFolders passes here. execute() then throws IllegalArgumentException.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One execute() sends one Get assets and subfolders of a parent folder request (GET /v3/assets?folder={folder_uid}&include_folders={value}) with the headers and query parameters on this object.
- subfolder writes folder and include_folders into the query parameters of this asset object, and the values stay for every later request from it.
- With isIncludeFolders set to false, the request returns the same list as byFolderUid.
- The response body is the raw JSON from the API, with assets and folders under one assets array. A folder carries is_dir set to true.
- To list only the subfolders, use the getSubfolder method.
Example
Basic usage: list the assets and subfolders of a folder
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Asset;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class ListFolderContents {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Asset asset = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").asset();
Response<ResponseBody> response = asset.subfolder("<FOLDER_UID>", true).execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}Assets only: leave the subfolders out
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Asset;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class ListFolderFilesOnly {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Asset asset = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").asset();
Response<ResponseBody> response = asset.subfolder("<FOLDER_UID>", false).execute();
if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
System.out.println(response.body().string());
}
}subfolderAsPojo
subfolderAsPojo builds the request that lists the assets and, optionally, the subfolders inside one parent folder, with a typed response.
| Name | Type | Description |
|---|---|---|
| folderUid (required) | String | UID of the parent folder. |
| isIncludeFolders (required) | Boolean | true adds the subfolders to the list. |
Returns: Call<AssetListResponse>. The request for the assets and subfolders in the folder as typed objects, sent when you call execute().
Validation
- There is no client-side validation.
- A null folderUid or isIncludeFolders passes here. execute() then throws IllegalArgumentException.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One execute() sends the same Get assets and subfolders of a parent folder request as subfolder.
- subfolderAsPojo writes folder and include_folders into the query parameters of this asset object, and the values stay for every later request from it.
- Gson reads the assets array of the response into an AssetListResponse. getAssets() returns a List<AssetPojo>, and getRawJson() returns every item as a Map<String, Object> with all its keys.
- AssetPojo exposes getTitle() only. It returns the name for a folder, whose content_type is application/vnd.contenstack.folder, and the title for a file. It throws NullPointerException for an item without content_type. Read other values from getRawJson().
- AssetListResponse keeps only the assets array, so top-level keys such as count are not available. Use the ResponseBody form of the method to read them.
Example
Basic usage: print the names of the assets and subfolders in a folder
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Asset;
import com.contentstack.cms.stack.AssetListResponse;
import com.contentstack.cms.stack.AssetPojo;
import retrofit2.Response;
import java.io.IOException;
import java.util.List;
public class ListFolderContentTitles {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Asset asset = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").asset();
Response<AssetListResponse> response = asset.subfolderAsPojo("<FOLDER_UID>", true).execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
List<AssetPojo> items = response.body().getAssets();
for (AssetPojo item : items) {
System.out.println(item.getTitle());
}
}
}unpublish
unpublish builds the request that unpublishes one version of an asset from the environments and locales you name, now or at a scheduled time.
| Name | Type | Description |
|---|---|---|
| requestBody (required) | JSONObject | Request body with the targets under an asset key. |
| requestBody.asset.environments (required) | List<String> | Environments to unpublish from. |
| requestBody.asset.locales (required) | List<String> | Locales to unpublish from. |
| requestBody.version | int | Asset version to unpublish. |
| requestBody.scheduled_at | String | ISO 8601 date and time to unpublish later. |
Returns: Call<ResponseBody>. The request for the unpublish notice, sent when you call execute().
Validation
- Throws NullPointerException when the asset has no UID, because the request path needs one. Create the object with stack.asset("<ASSET_UID>").
- execute() throws IllegalArgumentException when requestBody is null, because the request needs a body.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
Warning unpublish removes the asset from the environments you name, so the delivery API stops returning it there. Publish it again with the publish method to undo it.
- One execute() sends one Unpublish an asset request (POST /v3/assets/{asset_uid}/unpublish) with requestBody as the JSON body and the headers on this object. It does not send the query parameters from addParam.
- Without scheduled_at, the API unpublishes the asset now. With it, the API schedules the job for that time, for example 2026-12-01T09:00:00.000Z.
- The API queues the job, and the response body holds a notice message, not the unpublished asset. Track the job with the PublishQueue class.
Example
Basic usage: unpublish an asset from one environment now
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Asset;
import okhttp3.ResponseBody;
import org.json.simple.JSONArray;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class UnpublishAsset {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Asset asset = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").asset("<ASSET_UID>");
JSONArray environments = new JSONArray();
environments.add("<ENVIRONMENT>");
JSONArray locales = new JSONArray();
locales.add("<LOCALE>");
JSONObject target = new JSONObject();
target.put("environments", environments);
target.put("locales", locales);
JSONObject requestBody = new JSONObject();
requestBody.put("asset", target);
Response<ResponseBody> response = asset.unpublish(requestBody).execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}All parameters: schedule a unpublish of version 2
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Asset;
import okhttp3.ResponseBody;
import org.json.simple.JSONArray;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class ScheduleUnpublishAsset {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Asset asset = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").asset("<ASSET_UID>");
JSONArray environments = new JSONArray();
environments.add("<ENVIRONMENT>");
JSONArray locales = new JSONArray();
locales.add("<LOCALE>");
JSONObject target = new JSONObject();
target.put("environments", environments);
target.put("locales", locales);
JSONObject requestBody = new JSONObject();
requestBody.put("asset", target);
requestBody.put("version", 2);
requestBody.put("scheduled_at", "2026-12-01T09:00:00.000Z");
Response<ResponseBody> response = asset.unpublish(requestBody).execute();
if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
System.out.println(response.body().string());
}
}updateDetails
updateDetails builds the request that changes the title and description of an asset, or makes an earlier version the latest.
| Name | Type | Description |
|---|---|---|
| requestBody (required) | JSONObject | Request body with the details under an asset key. |
| requestBody.asset.title | String | New title of the asset. |
| requestBody.asset.description | String | New description of the asset. |
| requestBody.version | int | Version to make the latest version. |
Returns: Call<ResponseBody>. The request for the updated asset, sent when you call execute().
Validation
- Throws NullPointerException when the asset has no UID, because the request path needs one. Create the object with stack.asset("<ASSET_UID>").
- execute() throws IllegalArgumentException when requestBody is null, because the request needs a body.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One execute() sends one PUT /v3/assets/{asset_uid} request with requestBody as the JSON body and the query parameters on this object.
- The API reference documents two uses of this request:
- Update asset changes the title and description. It changes the metadata only, not the file. Replace the file with the replace method.
- Update asset revision makes the version in version the latest version, with the title and description you pass.
- The response body is the raw JSON from the API, with the asset under an asset key.
Example
Basic usage: change the title and description
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Asset;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class UpdateAssetDetails {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Asset asset = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").asset("<ASSET_UID>");
JSONObject details = new JSONObject();
details.put("title", "Spring hero image");
details.put("description", "Hero image for the spring campaign");
JSONObject requestBody = new JSONObject();
requestBody.put("asset", details);
Response<ResponseBody> response = asset.updateDetails(requestBody).execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}All parameters: make version 2 the latest version
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Asset;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class RestoreAssetVersion {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Asset asset = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").asset("<ASSET_UID>");
JSONObject details = new JSONObject();
details.put("title", "Spring hero image");
details.put("description", "Restored from version 2");
JSONObject requestBody = new JSONObject();
requestBody.put("asset", details);
requestBody.put("version", 2);
Response<ResponseBody> response = asset.updateDetails(requestBody).execute();
if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
System.out.println(response.body().string());
}
}uploadAsset
uploadAsset builds the request that uploads a file from your local system to the stack as a new asset.
| Name | Type | Description |
|---|---|---|
| filePath (required) | String | Path of the file to upload. |
| description (required) | String | Description of the asset. null sends none. |
| parentUid (required) | String | UID of the destination folder. null uploads to the root. |
| title (required) | String | Title of the asset. null sends none. |
| tags (required) | String[] | Tags for the asset. null or empty sends none. |
Returns: Call<ResponseBody>. The request for the new asset, sent when you call execute().
Overloads
- uploadAsset(String filePath, String description)
- uploadAsset(String filePath, String parentUid, String title, String description, String[] tags)
Validation
- Throws NullPointerException when filePath is null.
- When filePath is empty or names no existing file, the SDK leaves the file out of the form. If no other field remains, uploadAsset throws IllegalStateException, because a form needs at least one field. Otherwise the request goes out without a file, and the API rejects it because asset[upload] is mandatory.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One execute() sends one Upload asset request (POST /v3/assets) as multipart form data, with the headers and query parameters on this object.
- The SDK sends the following form fields, and leaves out any field whose argument is null:
- asset[upload]: the file, under its own file name.
- asset[parent_uid], asset[title], and asset[description]: the matching arguments.
- asset[tags]: the tags joined with commas into one value.
- The SDK sets the content type of the file from its extension, in one of the following two ways:
- The SDK maps 15 extensions itself: .svg, .webp, .json, .woff, .woff2, .ttf, .otf, .eot, .mp4, .m4a, .mkv, .webm, .ico, .csv, and .md.
- For other extensions it asks javax.activation.MimetypesFileTypeMap, which returns application/octet-stream for a type it does not know.
- The API reference lists relative_urls, include_dimension, and include_branch as query parameters for this request. Add them with addParam.
- The response body is the raw JSON from the API, with the new asset under an asset key. Read its uid to work on the asset later.
Example
Basic usage: upload a file with a description
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Asset;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class UploadAsset {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Asset asset = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").asset();
Response<ResponseBody> response = asset.uploadAsset("<FILE_PATH>", "Hero image for the spring campaign").execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}All parameters: upload a file into a folder with a title, description, and tags
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Asset;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class UploadAssetToFolder {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Asset asset = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").asset()
.addParam("include_dimension", true);
String[] tags = {"campaign", "hero"};
Response<ResponseBody> response = asset.uploadAsset("<FILE_PATH>", "<FOLDER_UID>", "docs-test-hero-image", "Hero image for the spring campaign", tags).execute();
if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
System.out.println(response.body().string());
}
}