Asset Libraries API Basics

Liferay’s REST APIs provide endpoints for creating, retrieving, updating, and deleting asset libraries.

Starting with Liferay DXP 2025.Q4, these same endpoints also manage Content Management System (CMS) spaces. See Create a Content Management System Space to learn more.

Create Asset Libraries

Start a new Liferay DXP instance by running

docker run -it -m 8g -p 8080:8080 liferay/dxp:2025.q1.6-lts

Sign in to Liferay at http://localhost:8080 using the email address test@liferay.com and the password test. When prompted, change the password to learn.

Then, follow these steps:

Download and unzip Categories and Vocabulary API Basics.

curl https://resources.learn.liferay.com/examples/liferay-z2u9.zip -O

unzip liferay-z2u9.zip

Navigate to the curl folder in the command line, then execute the AssetLibraries_POST.sh script to create a new asset library.

./AssetLibraries_POST.sh

Although the sample script includes several parameters, the basic POST request only requires a unique assetLibraryKey, a name, and a settings object (which can be empty).

curl \
"http://localhost:8080/o/headless-asset-library/v1.0/asset-libraries" \
--data-raw '
   {
      "assetLibraryKey": "my-asset-library-key",
      "name": "My Asset Library",
      "settings": {}
   }' \
--header "Content-Type: application/json" \
--request "POST" \
--user "test@liferay.com:learn"

The JSON response confirms the asset library was created:

{
   "actions" : {
      "pin" : {
         "method" : "PUT",
         "href" : "http://localhost:8080/o/headless-asset-library/v1.0/asset-libraries/35914/pins"
      },
      "connect-sites" : {
         "method" : "GET",
         "href" : "http://localhost:8080/o/headless-asset-library/v1.0/asset-libraries/35914"
      },
      "permissions" : {
         "method" : "PATCH",
         "href" : "http://localhost:8080/o/headless-asset-library/v1.0/asset-libraries/35914"
      },
      "get" : {
         "method" : "GET",
         "href" : "http://localhost:8080/o/headless-asset-library/v1.0/asset-libraries/35914"
      },
      "unpin" : {
         "method" : "DELETE",
         "href" : "http://localhost:8080/o/headless-asset-library/v1.0/asset-libraries/35914/pins"
      },
      "update" : {
         "method" : "PATCH",
         "href" : "http://localhost:8080/o/headless-asset-library/v1.0/asset-libraries/35914"
      },
      "assign-members" : {
         "method" : "GET",
         "href" : "http://localhost:8080/o/headless-asset-library/v1.0/asset-libraries/35914"
      },
      "delete" : {
         "method" : "DELETE",
         "href" : "http://localhost:8080/o/headless-asset-library/v1.0/asset-libraries/35914"
      }
   },
   "assetLibraryKey" : "My Asset Library",
   "creatorUserId" : 20132,
   "dateCreated" : "2025-10-03T14:00:00Z",
   "dateModified" : "2025-10-03T14:00:00Z",
   "description" : "A new asset library created through the Headless API",
   "externalReferenceCode" : "47143084-6150-16d8-0a65-907d5ed6d6d7",
   "id" : 35914,
   "name" : "My Asset Library",
   "settings" : {
      "autoTaggingEnabled" : true,
      "availableLanguageIds" : [ ],
      "defaultLanguageId" : "",
      "logoColor" : "outline-0",
      "mimeTypeLimits" : [ ],
      "sharingEnabled" : true,
      "trashEnabled" : true,
      "trashEntriesMaxAge" : 0,
      "useCustomLanguages" : false
   },
   "siteId" : 35915,
   "type" : "AssetLibrary"
}

Note the id and externalReferenceCode values. Use them when retrieving, updating, or deleting asset libraries.

To verify the creation, open the Asset Libraries application in Global Menu () → Applications → Asset Libraries.
To run the Java example, navigate to the java folder and compile the source files:
```
javac -classpath .:* *.java
```
Run the AssetLibraries_POST class with the following command.
```
java --add-opens java.base/java.net=ALL-UNNAMED -classpath .:* AssetLibraries_POST
```
On an older version of Liferay with Java 8, remove the --add-opens argument:
```
java -classpath .:* AssetLibraries_POST
```

Examine the cURL Command

The AssetLibraries_POST.sh script calls the REST service using cURL.

curl \
	"http://localhost:8080/o/headless-asset-library/v1.0/asset-libraries" \
	--data-raw '{
			"assetLibraryKey": "my-asset-library-key",
			"description": "This asset library was created by the headless API.",
			"name": "My Asset Library",
			"settings": {},
			"type": "AssetLibrary"
	}' \
	--header "Accept: application/json" \
	--header "Content-Type: application/json" \
	--request "POST" \
	--user "test@liferay.com:learn"

The main arguments are

Arguments	Description
`--header "Content-Type: application/json"`	Declares JSON as the request body format.
`--request "POST"`	The HTTP method to invoke at the specified endpoint
`"http://localhost:8080/o/headless-asset-library/v1.0/asset-libraries"`	The REST service endpoint for creating an Asset Library
`--data-raw '{...}'`	The JSON body containing the Asset Library properties to create
`--user "test@liferay.com:learn"`	Basic authentication credentials

The JSON body in --data-raw includes these top-level parameters:

Parameter	Description
`assetLibraryKey`	Unique key for the library, used internally
`description`	Text description of the Asset Library
`name`	Display name of the Asset Library (required)
`permissions`	Array of permission objects defining roles and allowed actions
`settings`	Configuration object for library behavior
`type`	Type of resource. Possible values: AssetLibrary or Liferay DXP 2025.Q4+ Space.

You can view the full AssetLibrary schema in the OpenAPI definition at http://[host]:[port]/o/api?endpoint=http://[host]:[port]/o/headless-asset-library/v1.0/openapi.json

Note

Basic authentication is used here for demonstration purposes. For production, you should authorize users via OAuth2. See Using OAuth2 to Authorize Users for a sample React application that uses OAuth2.

Examine the Java Class

The AssetLibraries_POST.java class adds an asset library using the AssetLibraryResource service.

public class AssetLibraries_POST {

/**
 * java --add-opens java.base/java.net=ALL-UNNAMED -classpath .:* AssetLibraries_POST
 */
public static void main(String[] args) throws Exception {
	AssetLibraryResource.Builder builder = AssetLibraryResource.builder();

	AssetLibraryResource assetLibraryResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	System.out.println(
		assetLibraryResource.postAssetLibrary(_createAssetLibrary()));
}

private static AssetLibrary _createAssetLibrary() {
	return new AssetLibrary() {
		{
			setAssetLibraryKey("my-asset-library-key");
			setDescription(
				"This asset library was created by the headless API.");
			setName("My Asset Library");
			setSettings(new Settings());
			setType(AssetLibrary.Type.ASSET_LIBRARY);
		}
	};
}

This class invokes the REST service using only three lines of code:

Line (abbreviated)	Description
`AssetLibraryResource.Builder builder = AssetLibraryResource.builder();`	Creates a `Builder` for generating an `AssetLibraryResource` service instance.
`AssetLibraryResource assetLibraryResource = builder.authentication(...).build();`	Sets the basic authentication credentials and builds the `AssetLibraryResource` service instance.
`AssetLibrary assetLibrary = new AssetLibrary();`	Creates a new `AssetLibrary` object to hold the data to post.
`assetLibrary.setAssetLibraryKey(...);`, `setDescription(...);`, `setName(...);`	Defines the asset library’s key, description, and name.
`assetLibrary.setSettings(new Settings());`	Initializes an empty `Settings` object for the asset library.
`assetLibrary.setType(AssetLibrary.Type.ASSET_LIBRARY);`	Sets the asset library type.
`assetLibraryResource.postAssetLibrary(assetLibrary);`	Sends a POST request with the `AssetLibrary` data to create a new asset library.

The project includes the com.liferay.headless.asset.library.client.jar as a dependency. You can find client JAR dependency information for all REST applications in the API explorer in your installation at /o/api.

The other example Java classes are similar to this one but call different AssetLibraryResource methods.

Note

The main method’s comment demonstrates running the class.

Important

See AssetLibraryResource for service details.

Below are examples of calling other AssetLibrary REST services using cURL and Java.

Create Content Management System Spaces

Beta Feature Liferay DXP 2025.Q4+

Important

Currently, this feature is behind a beta feature flag (LPD-17564) and also depends on release feature flags (LPS-179669 and LPD-34594). Read Feature Flags for more information.

You can create Content Management System (CMS) spaces using the same AssetLibrary endpoints. The only difference is that the type field must be set to "Space" instead of "AssetLibrary".

-cURL

Change the type field to "Space".

curl \
   "http://localhost:8080/o/headless-asset-library/v1.0/asset-libraries" \
   --data-raw '
      {
         "assetLibraryKey": "my-space-key",
         "description": "A new space created through the Headless API",
         "name": "My Space",
         "settings": {},
         "type": "Space"
      }' \
   --header "Accept: application/json" \
   --header "Content-Type: application/json" \
   --request "POST" \
   --user "test@liferay.com:learn"

The JSON response confirms the CMS space was created:

(...)
},
"assetLibraryKey" : "My Space",
"creatorUserId" : 20131,
"dateCreated" : "2025-10-09T11:54:31Z",
"dateModified" : "2025-10-09T11:54:31Z",
"description" : "A new space created through the Headless API",
"externalReferenceCode" : "2847d0b7-09ab-6e6a-ac55-4cc4cbb70b44",
"id" : 36582,
"name" : "My Space",
"settings" : {
   "autoTaggingEnabled" : false,
   "availableLanguageIds" : [ ],
   "defaultLanguageId" : "",
   "logoColor" : "outline-0",
   "mimeTypeLimits" : [ ],
   "sharingEnabled" : true,
   "trashEnabled" : true,
   "trashEntriesMaxAge" : 0,
   "useCustomLanguages" : false
},
"siteId" : 36583,
"type" : "Space"
}

Java

Update the setType method in the Java class to define the resource as a CMS space instead of an asset library.

(...)

public class AssetLibraries_POST {

   /**
   * java --add-opens java.base/java.net=ALL-UNNAMED -classpath .:* AssetLibraries_POST
   */
   public static void main(String[] args) throws Exception {
      AssetLibraryResource.Builder builder =
         AssetLibraryResource.builder();

      AssetLibraryResource assetLibraryResource =
         builder.authentication(
            "test@liferay.com", "learn"
         ).build();

      System.out.println(
         assetLibraryResource.postAssetLibrary(
            _createAssetLibrary()));
   }

      private static AssetLibrary _createAssetLibrary() {
      return new AssetLibrary() {
         {
            setAssetLibraryKey("my-asset-library-key");
            setDescription("A new asset library created through the Headless API");
            setName("My Asset Library");
            setSettings(new Settings());
            setType(AssetLibrary.Type.SPACE);
         }
      };
   }

}

You must include the setType(AssetLibrary.Type.SPACE); statement in your Java class to specify that the new resource should be created as a Space rather than an Asset Library.

Note

All other methods work the same for asset libraries and spaces. Use the corresponding ID or external reference code to call them. The response includes the type field, showing whether the resource is an asset library or a space.

Retrieve Asset Libraries

You can retrieve asset libraries using cURL or Java commands.

Replace 1234 with the asset library ID. You can find this value in the creation response or under Asset Library Settings → Details in the UI.

Find the asset library ID via the UI in the Asset Library Settings.

cURL

Command:
```
./AssetLibraries_GET_ById.sh 1234
```
Code:

curl \
	"http://localhost:8080/o/headless-asset-library/v1.0/asset-libraries/${1}" \
	--header "Accept: application/json" \
	--user "test@liferay.com:learn"

Java

Command:

java --add-opens java.base/java.net=ALL-UNNAMED -classpath .:* -DassetLibraryId=1234 AssetLibraries_GET_ById

On an older version of Liferay with Java 8, remove the --add-opens argument:

java -classpath .:* -DassetLibraryId=1234 AssetLibraries_GET_ById

Code:

public class AssetLibraries_GET_ById {

/**
 * java --add-opens java.base/java.net=ALL-UNNAMED -classpath .:* -DassetLibraryId=1234 AssetLibraries_GET_ById
 */
public static void main(String[] args) throws Exception {
	AssetLibraryResource.Builder builder = AssetLibraryResource.builder();

	AssetLibraryResource assetLibraryResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	System.out.println(
		assetLibraryResource.getAssetLibrary(
			Long.valueOf(System.getProperty("assetLibraryId"))));
}

}

The response returns an AssetLibrary object in JSON format.

By External Reference Code (ERC)

Replace ExternalReferenceCode with the asset library’s external reference code, automatically assigned when created (in this example, 47143084-6150-16d8-0a65-907d5ed6d6d7). You can later edit the asset library to change the ERC to a more readable value.

cURL

Command:

./AssetLibraries_GET_ByExternalReferenceCode.sh ExternalReferenceCode

Code:

curl \
	"http://localhost:8080/o/headless-asset-library/v1.0/asset-libraries/by-external-reference-code/${1}" \
	--header "Accept: application/json" \
	--user "test@liferay.com:learn"

Java

Command:

java --add-opens java.base/java.net=ALL-UNNAMED -classpath .:* -DassetLibraryExternalReferenceCode=ExternalReferenceCode AssetLibraries_GET_ByExternalReferenceCode

On an older version of Liferay with Java 8, remove the --add-opens argument:

java -classpath .:* -ExternalReferenceCode=ExternalReferenceCode AssetLibraries_GET_ByExternalReferenceCode

Code:

public class AssetLibraries_GET_ByExternalReferenceCode {

/**
 * java --add-opens java.base/java.net=ALL-UNNAMED -classpath .:* -DassetLibraryExternalReferenceCode=ExternalReferenceCode AssetLibraries_GET_ByExternalReferenceCode
 */
public static void main(String[] args) throws Exception {
	AssetLibraryResource.Builder builder = AssetLibraryResource.builder();

	AssetLibraryResource assetLibraryResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	System.out.println(
		assetLibraryResource.getAssetLibraryByExternalReferenceCode(
			System.getProperty("assetLibraryExternalReferenceCode")));
}

}

The response returns an AssetLibrary object in JSON format.

Patch Asset Libraries

Update specific fields of an existing asset library. Replace 1234 with your asset library’s ID.

cURL

Command:
```
./AssetLibraries_PATCH_ById.sh 1234
```
Code:

curl \
	"http://localhost:8080/o/headless-asset-library/v1.0/asset-libraries/${1}" \
	--data-raw '{
			"description": "This asset library was patched by the headless API.",
			"externalReferenceCode": "my-asset-library-001"
	}' \
	--header "Accept: application/json" \
	--header "Content-Type: application/json" \
	--request "PATCH" \
	--user "test@liferay.com:learn"

Java

Command:

java --add-opens java.base/java.net=ALL-UNNAMED -classpath .:* -DassetLibraryId=1234 AssetLibraries_PATCH_ById

On an older version of Liferay with Java 8, remove the --add-opens argument:

java -classpath .:* -DassetLibraryId=1234 AssetLibraries_PATCH_ById

Code:

public class AssetLibraries_PATCH_ById {

/**
 * java --add-opens java.base/java.net=ALL-UNNAMED -classpath .:* -DassetLibraryId=1234 AssetLibraries_PATCH_ById
 */
public static void main(String[] args) throws Exception {
	AssetLibraryResource.Builder builder = AssetLibraryResource.builder();

	AssetLibraryResource assetLibraryResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	System.out.println(
		assetLibraryResource.patchAssetLibrary(
			Long.valueOf(System.getProperty("assetLibraryId")),
			_createAssetLibrary()));
}

private static AssetLibrary _createAssetLibrary() {
	return new AssetLibrary() {
		{
			setDescription(
				"This asset library was patched by the headless API.");
			setExternalReferenceCode("my-asset-library-001");
		}
	};
}

In this example, the description is updated from A new asset library created through the Headless API to A new asset library description edited through the Headless API.

The external reference code (ERC) is also changed from the system-generated value to my-asset-library-001.

Put Asset Libraries

Overwrite an existing asset library using its external reference code (ERC). In this example, use my-asset-library-001, the ERC updated in the previous step.

cURL

Command:

./AssetLibraries_PUT_ByExternalReferenceCode.sh ExternalReferenceCode

Code:

curl \
	"http://localhost:8080/o/headless-asset-library/v1.0/asset-libraries/by-external-reference-code/${1}" \
	--data-raw '{
			"assetLibraryKey": "updated-asset-library-key",
			"description": "This asset library was updated by the headless API.",
			"externalReferenceCode": "updated-asset-library-001",
			"name": "Updated Asset Library",
	}' \
	--header "Accept: application/json" \
	--header "Content-Type: application/json" \
	--request "PUT" \
	--user "test@liferay.com:learn"

Java

Command:

java --add-opens java.base/java.net=ALL-UNNAMED -classpath .:* -DassetLibraryExternalReferenceCode=ExternalReferenceCode AssetLibraries_PUT_ByExternalReferenceCode

On an older version of Liferay with Java 8, remove the --add-opens argument:

java -classpath .:* -DassetLibraryExternalReferenceCode=ExternalReferenceCode AssetLibraries_PUT_ByExternalReferenceCode

Code:

public class AssetLibraries_PUT_ByExternalReferenceCode {

/**
 * java --add-opens java.base/java.net=ALL-UNNAMED -classpath .:* -DassetLibraryExternalReferenceCode=ExternalReferenceCode AssetLibraries_PUT_ByExternalReferenceCode
 */
public static void main(String[] args) throws Exception {
	AssetLibraryResource.Builder builder = AssetLibraryResource.builder();

	AssetLibraryResource assetLibraryResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	System.out.println(
		assetLibraryResource.putAssetLibraryByExternalReferenceCode(
			System.getProperty("assetLibraryExternalReferenceCode"),
			_createAssetLibrary()));
}

private static AssetLibrary _createAssetLibrary() {
	return new AssetLibrary() {
		{
			setAssetLibraryKey("updated-asset-library-key");
			setDescription(
				"This asset library was updated by the headless API.");
			setExternalReferenceCode("updated-asset-library-001");
			setName("Updated Asset Library");
		}
	};
}

Note

If the specified asset library does not exist, this PUT request creates a new one.

Delete Asset Libraries

Delete an existing asset library. Replace 1234 with your asset library’s ID.

cURL

Command:
```
./AssetLibraries_DELETE_ById.sh 1234
```
Code:

curl \
	"http://localhost:8080/o/headless-asset-library/v1.0/asset-libraries/${1}" \
	--header "Accept: application/json" \
	--request "DELETE" \
	--user "test@liferay.com:learn"

Java

Command

java --add-opens java.base/java.net=ALL-UNNAMED -classpath .:* -DassetLibraryId=1234 AssetLibraries_DELETE_ById

On an older version of Liferay with Java 8, remove the --add-opens argument:

java -classpath .:* -DassetLibraryId=1234 AssetLibraries_DELETE_ById

Code:

public class AssetLibraries_DELETE_ById {

/**
 * java --add-opens java.base/java.net=ALL-UNNAMED -classpath .:* -DassetLibraryId=1234 AssetLibraries_DELETE_ById
 */
public static void main(String[] args) throws Exception {
	AssetLibraryResource.Builder builder = AssetLibraryResource.builder();

	AssetLibraryResource assetLibraryResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	assetLibraryResource.deleteAssetLibrary(
		Long.valueOf(System.getProperty("assetLibraryId")));
}

}

Capability:

Content Management System

Resource Type:

Official Documentation

Feature:

API Development

Categories and Tags

Deployment Approach:

Liferay PaaS

Liferay SaaS

Liferay Self-Hosted