Tags API Basics

Liferay’s REST APIs provide services for managing tags (referred to as keywords in Liferay’s codebase). You can create, edit, and delete tags using the API. Start with an example of adding a new tag.

Add a Tag

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 [e-mail] and the password test. When prompted, change the password to learn.

Then, follow these steps:

1. Download and unzip Tags API Basics.

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

   unzip liferay-r7u9.zip
   

2. Find your site ID and use it in the following service calls.

3. Use the cURL script to add a new tag to your site. On the command line, navigate to the curl folder. Execute the Keywords_POST_ToSites.sh script with your site ID as a parameter.

   ./Keywords_POST_ToSites.sh 1234
   

   The JSON response shows a new tag has been added:

   {
     "creator" : {
       "additionalName" : "",
       "contentType" : "UserAccount",
       "familyName" : "Test",
       "givenName" : "Test",
       "id" : 20129,
       "name" : "Test Test",
       "profileURL" : "/web/test"
     },
     "dateCreated" : "2021-09-09T21:15:46Z",
     "dateModified" : "2021-09-09T21:15:46Z",
     "id" : 40130,
     "keywordUsageCount" : 0,
     "name" : "foo",
     "siteId" : 20125
   }
   

4. Go to the Tags application by navigating to Administration Menu → Categorization → Tags. See that a new tag has been added.

   

5. The REST service can also be called using the Java client. Navigate out of the curl folder and into the java folder. Compile the source files with the following command:

   javac -classpath .:* *.java
   

6. Run the Keywords_POST_ToSites class with the following command. Replace the siteId value with your site ID:

   java -classpath .:* -DsiteId=1234 Keywords_POST_ToSites
   

Examine the cURL Command

The Keywords_POST_ToSites.sh script calls the REST service with a cURL command.

curl \
	"http://localhost:8080/o/headless-admin-taxonomy/v1.0/sites/${1}/keywords" \
	--data-raw '
		{
			"name": "Foo"
		}' \
	--header "Content-Type: application/json" \
	--request "POST" \
	--user "[e-mail]:learn"

Here are the command’s arguments:

Arguments	Description
-H "Content-Type: application/json"	Indicates that the request body format is JSON.
-X POST	The HTTP method to invoke at the specified endpoint
"http://localhost:8080/o/headless-admin-taxonomy/v1.0/sites/${1}/keywords"	The REST service endpoint
-d "{\"name\": \"Foo\"}"	The data you are requesting to post
-u "[e-mail]:learn"	Basic authentication credentials

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.

The other cURL commands use similar JSON arguments.

Examine the Java Class

The Keywords_POST_ToSites.java class adds a tag by calling the keyword related service.

public static void main(String[] args) throws Exception {
	KeywordResource.Builder builder = KeywordResource.builder();

	KeywordResource keywordResource = builder.authentication(
		"[e-mail]", "learn"
	).build();

	Keyword keyword = keywordResource.postSiteKeyword(
		Long.valueOf(System.getProperty("siteId")),
		new Keyword() {
			{
				name = "Foo";
			}
		});

	System.out.println(keyword);
}

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

Line (abbreviated)	Description
KeywordResource.Builder builder = ...	Gets a Builder for generating a KeywordResource service instance.
KeywordResource keywordResource = builder.authentication(...).build();	Specifies basic authentication and generates a KeywordResource service instance.
Keyword keyword = keywordResource.postSiteKeyword(...);	Calls the keywordResource.postSiteKeyword method and passes the data to post.

Note that the project includes the com.liferay.headless.admin.taxonomy.client.jar file as a dependency. You can find client JAR dependency information for all REST applications in the API explorer in your installation at /o/api.

Note

The main method’s comment demonstrates running the class.

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

Important

See KeywordResource for service details.

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

Get Keyword Posts from Site

You can list a site’s tags by executing the following cURL or Java command. As above, replace 1234 with your site ID.

Keywords_GET_FromSites.sh

Command:

./Keywords_GET_FromSites.sh 1234

Code:

Keywords_GET_FromSites.java

Command:

java -classpath .:* -DsiteId=1234 Keywords_GET_FromSites

Code:

The Site’s Keyword objects appear in JSON.

Get a Keyword

Get a specific tag with the following cURL or Java command. Replace 1234 with the tag’s ID.

Tip

Use Keywords_GET_FromSites.[java|sh] to get site Keyword IDs.

Keywords_GET_ById.sh

Command:

./Keywords_GET_ById.sh 1234

Code:

curl \
	"http://localhost:8080/o/headless-admin-taxonomy/v1.0/keywords/${1}" \
	--user "[e-mail]:learn"

Keywords_GET_ById.java

Command:

java -classpath .:* -DkeywordId=1234 Keywords_GET_ById

Code:

public static void main(String[] args) throws Exception {
	KeywordResource.Builder builder = KeywordResource.builder();

	KeywordResource keywordResource = builder.authentication(
		"[e-mail]", "learn"
	).build();

	System.out.println(
		keywordResource.getKeyword(
			Long.valueOf(System.getProperty("keywordId"))));
}

The Keyword fields appear in JSON.

Put a Keyword

Completely overwrite an existing tag with the following cURL and Java commands. Note, replace 1234 with your tag’s ID.

Keywords_PUT_ById.sh

Command:

./Keywords_PUT_ById.sh 1234

Code:

curl \
	"http://localhost:8080/o/headless-admin-taxonomy/v1.0/keywords/${1}" \
	--data-raw '
		{
			"name": "Bar"
		}' \
	--header "Content-Type: application/json" \
	--request "PUT" \
	--user "[e-mail]:learn"

Keywords_PUT_ById.java

Command:

java -classpath .:* -DkeywordId=1234 Keywords_PUT_ById

Code:

public static void main(String[] args) throws Exception {
	KeywordResource.Builder builder = KeywordResource.builder();

	KeywordResource keywordResource = builder.authentication(
		"[e-mail]", "learn"
	).build();

	Keyword keyword = keywordResource.putKeyword(
		Long.valueOf(System.getProperty("keywordId")),
		new Keyword() {
			{
				name = "Bar";
			}
		});

	System.out.println(keyword);
}

Delete a Keyword

Delete an existing tag with the following cURL and Java commands. Note, replace 1234 with your tag’s ID.

Keywords_DELETE_ById.sh

Command:

./Keywords_DELETE_ById.sh 1234

Code:

curl \
	"http://localhost:8080/o/headless-admin-taxonomy/v1.0/keywords/${1}" \
	--request "DELETE" \
	--user "[e-mail]:learn"

Keywords_DELETE_ById.java

Command

java -classpath .:* -DkeywordId=1234 Keywords_DELETE_ById

Code:

public static void main(String[] args) throws Exception {
	KeywordResource.Builder builder = KeywordResource.builder();

	KeywordResource keywordResource = builder.authentication(
		"[e-mail]", "learn"
	).build();

	keywordResource.deleteKeyword(
		Long.valueOf(System.getProperty("keywordId")));
}

The API Explorer lists all Keyword services and schemas and has an interface to try out each service.

Improved Tags Management via Batch Engine

Liferay DXP 2025.Q2+

The Tags API supports batch export and import for migrating tags across Liferay instances. The process includes handling user filters based on creation/modification dates, name, or other attributes, and maintaining creator data during imports.

For details on using the Batch Engine, see Exporting and Importing Data using the Batch Engine API.

Filter Data

Refine exported data using query parameters.

curl \
   "http://localhost:8080/o/headless-batch-engine/v1.0/export-task/com.liferay.headless.admin.taxonomy.dto.v1_0.Keyword/JSON?taskItemDelegateName=Marketing&filter=name%20eq%20%27Marketing%27" \
   --header "Content-Type: application/json" \
   --request "POST" \
   --user "[e-mail]:learn"

Here’s how the query parameters work in the example:

• Use http://localhost:8080/o/headless-batch-engine/v1.0/export-task/ to start an export task using the Batch Engine API.

• com.liferay.headless.admin.taxonomy.dto.v1_0.Keyword/JSON specifies the type of data to export (in this case, tags in JSON format). The Keyword refers to the class in the API responsible for representing tags.

• taskItemDelegateName=Marketing specifies which tag you want to export. In this example, the value Marketing corresponds to a tag named Marketing. Replace this value with the actual name of the tag you want to export.

• filter=name%20eq%20%27Marketing%27 refines the data returned by the export. The filter query parameter is URL-encoded here (name%20eq%20%27Marketing%27). The equivalent human-readable version of the filter query is filter=name eq 'Marketing'. This filters the results to only include items where the name field is equal to “Marketing”.

Maintain Creator Data

When importing tags, use the importCreatorStrategy query parameter to define how creator data should be handled. The creatorStrategy parameter determines what happens if the creator does not exist in the target system.

You can use these parameters:

• creatorStrategy=INSERT

  Ensures that a new user is added as the creator if the specified creator is missing in the target system. This is required when using importCreatorStrategy=KEEP_CREATOR to ensure missing creators are added during import.

• importCreatorStrategy=KEEP_CREATOR

  Retains the original creator specified in the exported data. If the creator does not exist in the target system, the import fails unless creatorStrategy=INSERT is also set.

• importCreatorStrategy=OVERWRITE_CREATOR

  Replaces the original creator with the importing user. All imported tags are assigned to the user performing the import, regardless of the original creator’s information.

Note

If importCreatorStrategy is omitted, the system defaults to OVERWRITE_CREATOR.

Here’s an example:

curl \
	"http://localhost:8080/o/headless-batch-engine/v1.0/import-task/com.liferay.headless.admin.taxonomy.dto.v1_0.Keyword?siteId=20110&creatorStrategy=INSERT&importCreatorStrategy=KEEP_CREATOR" \
	--data-raw '
		{
			"name": "Tag"
		}' \
	--header "Content-Type: application/json" \
	--request "POST" \
	--user "[e-mail]:learn"

Related Topics

• OAuth2
• API Explorer