Submit Feedback

Categories and Vocabulary API Basics

Liferay’s REST APIs provide services for Liferay’s categories and vocabularies functionality. You can create and edit vocabularies with the API. You can also associate and edit categories with the API. Start by seeing an example of adding a new vocabulary.

Note

Liferay DXP 2025.Q1+/Portal GA132+ The Categories and Vocabulary API now uses External Reference Codes (ERCs) to reference these elements, enabling consistent identification across instances and supporting batch export/import for improved content management and portability.

Add a Vocabulary

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-f5w3.zip -O

unzip liferay-f5w3.zip

Find your site’s ID. Use the ID in different service calls below.

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

./TaxonomyVocabularies_POST_ToSites.sh 1234

The JSON response shows a new vocabulary has been added:

{
   "availableLanguages" : [ "en-US" ],
   "creator" : {
      "additionalName" : "",
      "contentType" : "UserAccount",
      "familyName" : "Test",
      "givenName" : "Test",
      "id" : 20129,
      "name" : "Test Test",
      "profileURL" : "/web/test"
   },
   "dateCreated" : "2021-09-09T21:03:15Z",
   "dateModified" : "2021-09-09T21:03:15Z",
   "description" : "Foo",
   "id" : 40126,
   "name" : "Able",
   "numberOfTaxonomyCategories" : 0,
   "siteId" : 20125
}

Go to the Categories application by navigating to Administration Menu → Categorization → Categories. See that a new vocabulary has been added.
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
```
Run the TaxonomyVocabularies_POST_ToSites class with the following command. Replace the siteId value with your site’s ID:
```
java -classpath .:* -DsiteId=1234 TaxonomyVocabularies_POST_ToSites
```

Examine the cURL Command

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

curl \
	"http://localhost:8080/o/headless-admin-taxonomy/v1.0/sites/${1}/taxonomy-vocabularies" \
	--data-raw '
		{
			"description": "Foo",
			"name": "Able"
		}' \
	--header "Content-Type: application/json" \
	--request "POST" \
	--user "test@liferay.com: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}/taxonomy-vocabularies"`	The REST service endpoint
`-d "{\"description\": \"Foo\", \"name\": \"Able\"}"`	The data you are requesting to post
`-u "test@liferay.com: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 TaxonomyVocabularies_POST_ToSites.java class adds a vocabulary by calling the vocabulary related service.

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

	TaxonomyVocabularyResource taxonomyVocabularyResource =
		builder.authentication(
			"test@liferay.com", "learn"
		).build();

	TaxonomyVocabulary taxonomyVocabulary =
		taxonomyVocabularyResource.postSiteTaxonomyVocabulary(
			Long.valueOf(System.getProperty("siteId")),
			new TaxonomyVocabulary() {
				{
					description = "Foo";
					name = "Baker";
				}
			});

	System.out.println(taxonomyVocabulary);
}

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

Line (abbreviated)	Description
`TaxonomyVocabularyResource.Builder builder = ...`	Gets a `Builder` for generating a `TaxonomyVocabularyResource` service instance.
`TaxonomyVocabularyResource taxonomyVocabularyResource = builder.authentication(...).build();`	Specifies basic authentication and generates a `TaxonomyVocabularyResource` service instance.
`TaxonomyVocabulary taxonomyVocabulary = taxonomyVocabularyResource.postSiteTaxonomyVocabulary(...);`	Calls the `postSiteTaxonomyVocabulary` 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 TaxonomyVocabularyResource methods.

Important

See TaxonomyVocabularyResource for service details.

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

Get Vocabularies from Site

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

TaxonomyVocabularies_GET_FromSites.sh

Command:

./TaxonomyVocabularies_GET_FromSites.sh 1234

Code:

curl \
	"http://localhost:8080/o/headless-admin-taxonomy/v1.0/sites/${1}/taxonomy-vocabularies" \
	--user "test@liferay.com:learn"

TaxonomyVocabularies_GET_FromSites.java

Command:

java -classpath .:* -DsiteId=1234 TaxonomyVocabularies_GET_FromSites

Code:

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

	TaxonomyVocabularyResource taxonomyVocabularyResource =
		builder.authentication(
			"test@liferay.com", "learn"
		).build();

	Page<TaxonomyVocabulary> page =
		taxonomyVocabularyResource.getSiteTaxonomyVocabulariesPage(
			Long.valueOf(System.getProperty("siteId")), null, null, null,
			Pagination.of(1, 2), null);

	System.out.println(page.getItems());
}

The site’s TaxonomyVocabulary objects appear in JSON.

Get a Vocabulary

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

Tip

Use TaxonomyVocabularies_GET_FromSites.[java|sh] to get Vocabulary IDs.

TaxonomyVocabularies_GET_ById.sh

Command:

./TaxonomyVocabularies_GET_ById.sh 1234

Code:

curl \
	"http://localhost:8080/o/headless-admin-taxonomy/v1.0/taxonomy-vocabularies/${1}" \
	--user "test@liferay.com:learn"

TaxonomyVocabularies_GET_ById.java

Command:

java -classpath .:* -DtaxonomyVocabularyId=1234 TaxonomyVocabularies_GET_ById

Code:

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

	TaxonomyVocabularyResource taxonomyVocabularyResource =
		builder.authentication(
			"test@liferay.com", "learn"
		).build();

	System.out.println(
		taxonomyVocabularyResource.getTaxonomyVocabulary(
			Long.valueOf(System.getProperty("taxonomyVocabularyId"))));
}

The TaxonomyVocabulary fields appear in JSON.

Patch a Vocabulary

Do a partial edit of an existing vocabulary with the following cURL and Java commands. Note, replace 1234 with your vocabulary’s ID.

TaxonomyVocabularies_PATCH_ById.sh

Command:

./TaxonomyVocabularies_PATCH_ById.sh 1234

Code:

curl \
	"http://localhost:8080/o/headless-admin-taxonomy/v1.0/taxonomy-vocabularies/${1}" \
	--data-raw '
		{
			"description": "Bar",
			"name": "Able"
		}' \
	--header "Content-Type: application/json" \
	--request "PATCH" \
	--user "test@liferay.com:learn"

TaxonomyVocabularies_PATCH_ById.java

Command:

java -classpath .:* -DtaxonomyVocabularyId=1234 TaxonomyVocabularies_PATCH_ById

Code:

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

	TaxonomyVocabularyResource taxonomyVocabularyResource =
		builder.authentication(
			"test@liferay.com", "learn"
		).build();

	TaxonomyVocabulary taxonomyVocabulary =
		taxonomyVocabularyResource.patchTaxonomyVocabulary(
			Long.valueOf(System.getProperty("taxonomyVocabularyId")),
			new TaxonomyVocabulary() {
				{
					description = "Bar";
					name = "Baker";
				}
			});

	System.out.println(taxonomyVocabulary);
}

In this example the description is changed from Foo to Bar.

Put a Vocabulary

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

TaxonomyVocabularies_PUT_ById.sh

Command:

./TaxonomyVocabularies_PUT_ById.sh 1234

Code:

curl \
	"http://localhost:8080/o/headless-admin-taxonomy/v1.0/taxonomy-vocabularies/${1}" \
	--data-raw '
		{
			"description": "Goo",
			"name": "Able"
		}' \
	--header "Content-Type: application/json" \
	--request "PUT" \
	--user "test@liferay.com:learn"

TaxonomyVocabularies_PUT_ById.java

Command:

java -classpath .:* -DtaxonomyVocabularyId=1234 TaxonomyVocabularies_PUT_ById

Code:

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

	TaxonomyVocabularyResource taxonomyVocabularyResource =
		builder.authentication(
			"test@liferay.com", "learn"
		).build();

	TaxonomyVocabulary taxonomyVocabulary =
		taxonomyVocabularyResource.putTaxonomyVocabulary(
			Long.valueOf(System.getProperty("taxonomyVocabularyId")),
			new TaxonomyVocabulary() {
				{
					description = "Goo";
					name = "Baker";
				}
			});

	System.out.println(taxonomyVocabulary);
}

Delete a Vocabulary

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

TaxonomyVocabularies_DELETE_ById.sh

Command:

./TaxonomyVocabularies_DELETE_ById.sh 1234

Code:

curl \
	"http://localhost:8080/o/headless-admin-taxonomy/v1.0/taxonomy-vocabularies/${1}" \
	--request "DELETE" \
	--user "test@liferay.com:learn"

TaxonomyVocabularies_DELETE_ById.java

Command

java -classpath .:* -DtaxonomyVocabularyId=1234 TaxonomyVocabularies_DELETE_ById

Code:

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

	TaxonomyVocabularyResource taxonomyVocabularyResource =
		builder.authentication(
			"test@liferay.com", "learn"
		).build();

	taxonomyVocabularyResource.deleteTaxonomyVocabulary(
		Long.valueOf(System.getProperty("taxonomyVocabularyId")));
}

Taxonomy Category Services

The cURL commands and Java classes for taxonomy categories work similarly to taxonomy vocabularies. Note that some services require the taxonomy vocabulary ID.

Files	Description
`TaxonomyCategories_GET_FromTaxonomyVocabularies.[java\\|sh]`	Get a list of categories from a vocabulary.
`TaxonomyCategories_DELETE_ById.[java\\|sh]`	Delete a category.
`TaxonomyCategories_GET_ById[java\\|sh]`	Get a specific category by ID.
`TaxonomyCategories_PATCH_ById.[java\\|sh]`	Patch a category.
`TaxonomyCategories_POST_ToTaxonomyVocabularies.[java\\|sh]`	Post a category to a vocabulary.
`TaxonomyCategories_PUT_ById.[java\\|sh]`	Put a category.

The API Explorer lists all of the TaxonomyVocabulary and TaxonomyCategory services and schemas and has an interface to try out each service.

Improved Vocabulary Management via Batch Engine

Liferay DXP 2025.Q2+/Portal GA135+

The Categories and Vocabulary API supports batch export and import for migrating categories and vocabularies across Liferay instances. The process includes exporting and importing associated permissions, 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.

Vocabulary Permissions

Manage vocabulary permissions using these API endpoints. In the following examples, replace ${1} with the site ID.

Create Vocabulary with Permissions:

Assign custom permissions to a vocabulary during creation by sending a POST request to the vocabulary’s endpoint. The specified roles must already exist in the system. If a role does not exist, the API returns a 404 error.

Example:

curl \
   "http://localhost:8080/o/headless-admin-taxonomy/v1.0/sites/${1}/taxonomy-vocabularies" \
   --data-raw '
      {
         "description": "Foo",
         "name": "Able",
         "permissions": [
               {
                  "roleName": "Role1",
                  "actionIds": ["VIEW", "UPDATE"]
               },
               {
                  "roleName": "Role2",
                  "actionIds": ["VIEW"]
               }
         ]
      }' \
   --header "Content-Type: application/json" \
   --request "POST" \
   --user "test@liferay.com:learn"

The permissions array specifies the roles and their associated permissions for the vocabulary. If no permissions are defined, the vocabulary is created with default permissions assigned to the roles.

Get Vocabulary Permissions:

By default, vocabulary permissions are not included in the response. To retrieve them, append nestedFields=permissions to the query.

Example:

curl \
   "http://localhost:8080/o/headless-admin-taxonomy/v1.0/sites/${1}/taxonomy-vocabularies?nestedFields=permissions" \
   --user "test@liferay.com:learn"

Patch Vocabulary Permissions:

You can update the permissions of an existing vocabulary using a PATCH request, similar to how you would assign permissions during creation.

Example:

curl \
   "http://localhost:8080/o/headless-admin-taxonomy/v1.0/taxonomy-vocabularies/${1}" \
   --data-raw '
      {
         "description": "Bar",
         "name": "Able",
         "permissions": [
               {
                  "roleName": "Role1",
                  "actionIds": ["VIEW", "UPDATE", "DELETE"]
               },
               {
                  "roleName": "Role2",
                  "actionIds": ["VIEW", "PERMISSIONS"]
               }
         ]
      }' \
   --header "Content-Type: application/json" \
   --request "PATCH" \
   --user "test@liferay.com:learn"

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.client.dto.v1_0.TaxonomyVocabulary/JSON?taskItemDelegateName=Tech&filter=name%20eq%20%27Tech%27" \
	--header "Content-Type: application/json" \
	--request "POST" \
	--user "test@liferay.com: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.client.dto.v1_0.TaxonomyVocabulary/JSON specifies the type of data to export (in this case, Taxonomy Vocabulary data in JSON format). The TaxonomyVocabulary refers to the class in the API responsible for representing vocabularies.
taskItemDelegateName=Tech specifies the vocabulary you want to export. In this example, the value Tech corresponds to a vocabulary named Tech. Replace this value with the name of the vocabulary you want to export.
filter=name%20eq%20%27Tech%27 refines the data returned by the export. The filter query parameter is URL-encoded here (name%20eq%20%27Tech%27). The equivalent human-readable version of the filter query is filter=name eq 'Tech'. The encoded version is used in the URL to ensure proper formatting when making the request.

Maintain Creator Data

When importing vocabularies, use the query parameter importCreatorStrategy 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 vocabularies 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.TaxonomyVocabulary?siteId=20110&creatorStrategy=INSERT&importCreatorStrategy=KEEP_CREATOR" \
	--data-raw '
		[
			{
				"name": "Example Vocabulary",
				"description": "A sample vocabulary for testing."
			}
		]' \
	--header "Content-Type: application/json" \
	--request "POST" \
	--user "test@liferay.com:learn"