Asset

View as Markdown

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:

NameTypeDescription
assetUidStringUID 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.

NameTypeDescription
key (required)String

Name of the request header.

Default: Not applicable
value (required)String

Value of the request header.

Default: Not applicable

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.

NameTypeDescription
headers (required)HashMap<String, String>

Header names and values to add.

Default: Not applicable

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.

NameTypeDescription
key (required)String

Name of the query parameter.

Default: Not applicable
value (required)Object

Value of the query parameter.

Default: Not applicable

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.

NameTypeDescription
headers (required)HashMap<String, Object>

Query parameter names and values to add.

Default: Not applicable

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.

NameTypeDescription
folderUid (required)String

UID of the asset folder.

Default: Not applicable

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.

NameTypeDescription
folderUid (required)String

UID of the asset folder.

Default: Not applicable

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.

NameTypeDescription
versionNumber (required)int

Asset version whose name to remove.

Default: Not applicable

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.

NameTypeDescription
folderUid (required)String

UID of an existing folder.

Default: Not applicable

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.

NameTypeDescription
body (required)JSONObject

Request body with the URL under an asset key.

Default: Not applicable
body.asset.permanent_url (required)String

Permanent URL, ending in a slug you choose.

Default: Not applicable

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.

NameTypeDescription
assetType (required)String

images or videos.

Default: Not applicable

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.

NameTypeDescription
slugUrl (required)String

Slug at the end of the permanent URL.

Default: Not applicable

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.

NameTypeDescription
requestBody (required)JSONObject

Request body with the targets under an asset key.

Default: Not applicable
requestBody.asset.environments (required)List<String>

Environments to publish on.

Default: Not applicable
requestBody.asset.locales (required)List<String>

Locales to publish on.

Default: Not applicable
requestBody.versionint

Asset version to publish.

Default: API default
requestBody.scheduled_atString

ISO 8601 date and time to publish later.

Default: Not set (runs now)

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.

NameTypeDescription
filePath (required)String

Path of the new file.

Default: Not applicable
description (required)String

Description of the asset.

Default: Not applicable

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.

NameTypeDescription
versionNumber (required)int

Asset version to name.

Default: Not applicable
requestBody (required)JSONObject

Request body with the name under an upload key.

Default: Not applicable
requestBody.upload._version_name (required)String

Name for the version.

Default: Not applicable

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.

NameTypeDescription
folderUid (required)String

UID of the parent folder.

Default: Not applicable
isIncludeFolders (required)Boolean

true adds the subfolders to the list.

Default: Not applicable

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.

NameTypeDescription
folderUid (required)String

UID of the parent folder.

Default: Not applicable
isIncludeFolders (required)Boolean

true adds the subfolders to the list.

Default: Not applicable

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.

NameTypeDescription
requestBody (required)JSONObject

Request body with the targets under an asset key.

Default: Not applicable
requestBody.asset.environments (required)List<String>

Environments to unpublish from.

Default: Not applicable
requestBody.asset.locales (required)List<String>

Locales to unpublish from.

Default: Not applicable
requestBody.versionint

Asset version to unpublish.

Default: API default
requestBody.scheduled_atString

ISO 8601 date and time to unpublish later.

Default: Not set (runs now)

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.

NameTypeDescription
requestBody (required)JSONObject

Request body with the details under an asset key.

Default: Not applicable
requestBody.asset.titleString

New title of the asset.

Default: API default
requestBody.asset.descriptionString

New description of the asset.

Default: API default
requestBody.versionint

Version to make the latest version.

Default: API default

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.

NameTypeDescription
filePath (required)String

Path of the file to upload.

Default: Not applicable
description (required)String

Description of the asset. null sends none.

Default: Not applicable
parentUid (required)String

UID of the destination folder. null uploads to the root.

Default: Not applicable
title (required)String

Title of the asset. null sends none.

Default: Not applicable
tags (required)String[]

Tags for the asset. null or empty sends none.

Default: Not applicable

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());
    }
}