Submit Feedback
Site APIs

Navigation Menu API Basics

Liferay’s REST APIs provide services for Liferay’s navigation menus. You can create and edit navigation menus with the API. Start by seeing an example of adding a new navigation menu.

Note

Liferay DXP 2025.Q2+ The Navigation Menus 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.

Important

Liferay 2026.Q1+The Navigation Menu endpoints moved fromheadless-deliverytoheadless-admin-site to better align with site-scoped operations and batch processing.

Deprecation: The headless-delivery endpoints are deprecated. Existing integrations continue to work for backward compatibility. Use the headless-admin-site API for new integrations.

ERC requirement: The new endpoints identify sites and navigation menus by external reference codes (ERCs).

Batch support: The headless-admin-site API supports Batch Engine import and export for navigation menus.

Adding a Navigation Menu

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:

  1. Download and unzip Navigation Menu API Basics.

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

    unzip liferay-p7s4.zip

  2. Find your site ID. Use it in different service calls below.

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

    ./NavigationMenus_POST_ToSites.sh 1234

    The JSON response shows a new navigation menu has been added:

    {
"creator" : {
   "additionalName" : "",
   "contentType" : "UserAccount",
   "familyName" : "Test",
   "givenName" : "Test",
   "id" : 20129,
   "name" : "Test Test"
},
"dateCreated" : "2021-09-09T21:41:31Z",
"dateModified" : "2021-09-09T21:41:31Z",
"id" : 40131,
"name" : "Foo",
"navigationMenuItems" : [ ],
"siteId" : 20125
}

  4. Go to the Navigation Menus application by navigating to Administration Menu → Site Builder → Navigation Menus. See that a new navigation menu has been added.

    See that a new Navigation Menu 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 NavigationMenus_POST_ToSites class with the following command. Replace the siteId value with your site ID:

    java -classpath .:* -DsiteId=1234 NavigationMenus_POST_ToSites

Examine the cURL Command

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

curl \
	"http://localhost:8080/o/headless-delivery/v1.0/sites/${1}/navigation-menus" \
	--data-raw '
		{
			"name": "Foo"
		}' \
	--header "Content-Type: application/json" \
	--request "POST" \
	--user "test@liferay.com:learn"

Here are the command’s arguments:

ArgumentsDescription
-H "Content-Type: application/json"Indicates that the request body format is JSON.
-X POSTThe HTTP method to invoke at the specified endpoint
"http://localhost:8080/o/headless-delivery/v1.0/sites/${1}/navigation-menus"The REST service endpoint
-d "{\"name\": \"Foo\"}"The data you are requesting to post
-u "test@liferay.com:learn"Basic authentication credentials
Note

The endpoint shown above uses the deprecated headless-delivery path for backward compatibility. For new integrations on 2026.Q1+, use the headless-admin-site endpoint instead.

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 NavigationMenus_POST_ToSites.java class adds a navigation menu by calling the NavigationMenuResource service.

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

	NavigationMenuResource navigationMenuResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	NavigationMenu navigationMenu =
		navigationMenuResource.postSiteNavigationMenu(
			Long.valueOf(System.getProperty("siteId")),
			new NavigationMenu() {
				{
					name = "Foo";
				}
			});

	System.out.println(navigationMenu);
}

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

Line (abbreviated)Description
NavigationMenuResource.Builder builder = ...Gets a Builder for generating a NavigationMenuResource service instance.
NavigationMenuResource navigationMenuResource = builder.authentication(...).build();Specifies basic authentication and generates a NavigationMenuResource service instance.
NavigationMenu navigationMenu = navigationMenuResource.postSiteNavigationMenu(...);Calls the navigationMenuResource.postSiteNavigationMenu method and passes the data to post.

Note that the project includes the com.liferay.headless.delivery.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 NavigationMenuResource methods.

Important

See NavigationMenuResource for service details.

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

Get Navigation Menus from Site

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

Command:

./NavigationMenus_GET_FromSites.sh 1234

Code:

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

Command:

java -classpath .:* -DsiteId=1234 NavigationMenus_GET_FromSites

Code:

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

	NavigationMenuResource navigationMenuResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	Page<NavigationMenu> page =
		navigationMenuResource.getSiteNavigationMenusPage(
			Long.valueOf(System.getProperty("siteId")),
			Pagination.of(1, 2));

	System.out.println(page);
}

The site’s NavigationMenu objects appear in JSON.

Get a Navigation Menu

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

Tip

Use NavigationMenus_GET_FromSites.[java|sh] to get NavigationMenu IDs.

Command:

./NavigationMenus_GET_ById.sh 1234

Code:

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

Command:

java -classpath .:* -DnavigationMenuId=1234 NavigationMenus_GET_ById

Code:

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

	NavigationMenuResource navigationMenuResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	System.out.println(
		navigationMenuResource.getNavigationMenu(
			Long.valueOf(System.getProperty("navigationMenuId"))));
}

The NavigationMenu fields appear in JSON.

Put a Navigation Menu

Do a complete overwrite of an existing navigation menu with the following cURL and Java commands. Note, replace 1234 with your navigation menu’s ID.

Command:

./NavigationMenus_PUT_ById.sh 1234

Code:

curl \
	"http://localhost:8080/o/headless-delivery/v1.0/navigation-menus/${1}" \
	--data-raw '
		{
			"name": "Bar"
		}' \
	--header "Content-Type: application/json" \
	--request "PUT" \
	--user "test@liferay.com:learn"

Command:

java -classpath .:* -DnavigationMenuId=1234 NavigationMenus_PUT_ById

Code:

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

	NavigationMenuResource navigationMenuResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	NavigationMenu navigationMenu =
		navigationMenuResource.putNavigationMenu(
			Long.valueOf(System.getProperty("navigationMenuId")),
			new NavigationMenu() {
				{
					name = "Bar";
				}
			});

	System.out.println(navigationMenu);
}

Delete a Navigation Menu

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

Command:

./NavigationMenus_DELETE_ById.sh 1234

Code:

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

Command

java -classpath .:* -DnavigationMenuId=1234 NavigationMenus_DELETE_ById

Code:

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

	NavigationMenuResource navigationMenuResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	navigationMenuResource.deleteNavigationMenu(
		Long.valueOf(System.getProperty("navigationMenuId")));
}

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

Liferay DXP 2025.Q3

The Navigation Menus API supports batch export and import for migrating site navigation menus and related entities across Liferay instances. You can include associated permissions, apply user-defined filters based on creation/modification dates or other attributes, and configure how creator data is handled during import requests.

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

Manage navigation menu permissions using these API endpoints. Replace ${1} with the site ID or navigation menu ID in the examples.

  1. Create Navigation Menu with Permissions

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

    If you omit the permissions array, the navigation menu is created with default permissions.

    If you include the permissions array, Liferay applies the specified roles and actions during creation.

    Example:

    curl \
	"http://localhost:8080/o/headless-delivery/v1.0/sites/${1}/navigation-menus" \
	--data-binary '
		{
			"name": "Main Menu",
			"permissions": [
				{
					"roleName": "Owner",
					"actionIds": ["VIEW", "UPDATE"]
				}
			]
		}' \
	--header "Content-Type: application/json" \
	--request "POST" \
	--user "test@liferay.com:learn"

  2. Get Navigation Menu Permissions

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

    Example:

    curl \
   "http://localhost:8080/o/headless-delivery/v1.0/sites/20126/navigation-menus?nestedFields=permissions" \
   --user "test@liferay.com:learn"

  3. Update Navigation Menu Permissions

    Update the permissions of an existing navigation menu using a PUT request. Replace ${1} with the navigation menu ID.

    This operation replaces all existing navigation menu permissions. Only the roles and actions included in the request remain after the update.

    Tip

    You can find the navigation menu ID while getting navigation menus from a site.

    Example:

    curl \
"http://localhost:8080/o/headless-delivery/v1.0/navigation-menus/${1}/permissions" \
--data-binary '
   [
      {
         "actionIds": ["VIEW", "UPDATE", "DELETE", "PERMISSIONS"],
         "roleName": "Owner"
      }
   ]' \
--header "Content-Type: application/json" \
--request "PUT" \
--user "test@liferay.com:learn"

Filter Data

You can use filters to refine which navigation menus to fetch or export. Filters work in two contexts:

  1. Fetch filtered navigation menus using the getSiteNavigationMenusPage endpoint. Retrieve only the menus you need using the filter parameter:

    curl \
   "http://localhost:8080/o/headless-delivery/v1.0/sites/20126/navigation-menus?filter=dateCreated%20le%202025-07-18T14%3A25%3A00Z&sort=dateCreated%3Adesc" \
   --header "Content-Type: application/json" \
   --request "GET" \
   --user "test@liferay.com:learn"

    Here’s how the query parameters work:

    ParameterDescription
    http://localhost:8080/o/headless-delivery/v1.0/sites/20126/navigation-menusEndpoint to fetch navigation menus for site 20126 using the headless delivery API.
    filter=dateCreated%20le%202025-07-18T14%3A25%3A00ZURL-encoded. Refines results to include only menus created on or before July 18, 2025, at 14:25 UTC.
    sort=dateCreated%3AdescURL-encoded. Orders results by dateCreated in descending order (most recent first).
    Tip

    Add a search= parameter to retrieve specific navigation menus by name. For example,

    http://localhost:8080/o/headless-delivery/v1.0/sites/20126/navigation-menus?filter=dateCreated%20le%202025-07-18T14%3A25%3A00Z&search=Main&sort=dateModified:desc

    This retrieves only navigation menus with Main in the name.

  2. Export filtered navigation menus using the postSiteNavigationMenusPageExportBatch endpoint. Use the same filter syntax to limit which menus are included in the export file:

    curl \
   "http://localhost:8080/o/headless-delivery/v1.0/sites/20126/navigation-menus/export-batch?filter=dateCreated%20ge%202025-07-17T00%3A00%3A00Z&search=Main&sort=dateModified%3Adesc" \
   --data-binary '' \
   --header "Content-Type: application/json" \
   --request "POST" \
   --user "test@liferay.com:learn"

    Here’s how the query parameters work:

    ParameterDescription
    http://localhost:8080/o/headless-delivery/v1.0/sites/20126/navigation-menus/export-batchEndpoint to start an export batch for navigation menus on site 20126.
    filter=dateCreated%20ge%202025-07-17T00%3A00%3A00ZURL-encoded. Limits the export to menus created on or after July 17, 2025, at midnight UTC.
    search=MainFilters exported menus to those whose name contains “Main” (case-insensitive).
    sort=dateModified%3AdescURL-encoded. Orders exported menus by dateModified in descending order (most recent first).
    --data-binary ''Empty body because filtering and sorting are controlled entirely via query parameters.

Maintain Creator Data

When importing navigation menus, you can use the importCreatorStrategy and creatorStrategy query parameters to control how creator information is handled.

ParameterDescription
creatorStrategy=INSERTAdds a new user as the creator if the specified creator is missing in the target system. Required when using importCreatorStrategy=KEEP_CREATOR.
importCreatorStrategy=KEEP_CREATORKeeps the original creator from the exported data. The import fails if the creator does not exist unless creatorStrategy=INSERT is also set.
importCreatorStrategy=OVERWRITE_CREATORReplaces the original creator with the importing user. All imported navigation menus are assigned to the user performing the import. Defaults to this if omitted.

Here’s an example:

curl \
   "http://localhost:8080/o/headless-batch-engine/v1.0/import-task/com.liferay.headless.delivery.dto.v1_0.NavigationMenu?siteId=20126&creatorStrategy=INSERT&importCreatorStrategy=KEEP_CREATOR" \
   --data-raw '
   [
      {
         "name": "Secondary Menu",
         "externalReferenceCode": "secondary-menu-001",
         "navigationType": "Primary"
      }
   ]' \
   --header "Content-Type: application/json" \
   --request "POST" \
   --user "test@liferay.com:learn"
Capability:
Sites
Resource Type:
Official Documentation
Feature:
Site Navigation
Deployment Approach:
Liferay PaaS
Liferay SaaS
Liferay Self-Hosted