Navigation REST API

The navigation REST API enables you to retrieve information about the dotCMS file and folder tree through REST API calls.

Usage #

The Navigation API has a single method, /api/v1/nav, which retrieves a list of navigation elements (folders, files, pages, and menu links) that have the Show on Menu property set to true. The nav method operates in live mode, returning only published content.

Initializing...

Parameters #

The API accepts the following parameters:

Parameter	Default Value	Description	Examples
`uri`*	(None)	The root path to begin traversing the folder tree.	`/` (e.g. `/api/v1/nav/`) starts from the root of the site, though the path may be provided with or without a leading slash. `/about-us` starts from the "About Us" folder etc.
`depth`	1	The depth of the folder tree to return.	1 returns only the element specified in the `uri` path. 2 returns the element specified in the path, and if that element is a folder, returns all direct children of that folder. 3 returns all children and grandchildren of the element specified in the path. etc.
`languageId`	1	The language ID of content to return.	1 (or unspecified) returns content in the Default Language. 2 or higher returns content with the specified Language ID. Note: The Default Language Fall-Through Configuration will be respected for returned content.

Examples #

Return a Site or Folder (depth=1)#

The following curl command returns information on the /about-us folder (without any of its children) on the dotCMS Demo Site:

curl --location --request GET "https://demo.dotcms.com/api/v1/nav/about-us"

The command returns the following JSON results (formatted here for readability):

{
    "errors":[],
    "entity": {
        "code":null,
        "folder":"1049e7fe-1553-4731-bdf9-ba069f1dc08b",
        "host":"48190c8c-42c4-46af-8d1a-0cd5db894797",
        "languageId":1,
        "href":"/about-us",
        "title":"About Us",
        "type":"folder",
        "hash":1547125655,
        "target":"_self",
        "order":1
    },
    "messages":[],
    "i18nMessagesMap":{},
    "permissions":[]
}

Return the Direct Children of a Site or Folder (depth=2)#

The following curl command returns the /about-us folder on the dotCMS Demo Site, and all folders and files within it in the language with Language ID 2 (Spanish):

curl --location --request GET "https://demo.dotcms.com/api/v1/nav/about-us?depth=2&languageId=2"

The command returns the following JSON results (formatted here for readability):

{
    "errors":[],
    "entity": {
        "code":null,
        "folder":"1049e7fe-1553-4731-bdf9-ba069f1dc08b",
        "host":"48190c8c-42c4-46af-8d1a-0cd5db894797",
        "languageId":1,
        "href":"/about-us",
        "title":"About Us",
        "type":"folder",
        "hash":1704969069,
        "target":"_self",
        "order":1,
        "children": [
            {
                "code":null,
                "folder":null,
                "host":"48190c8c-42c4-46af-8d1a-0cd5db894797",
                "languageId":1,
                "href":"/about-us/index",
                "title":"About Us",
                "type":"htmlpage",
                "hash":467696219,
                "target":"_self",
                "order":0
            },
            {
                "code":null,
                "folder":"d19a2815-1037-4a17-bce5-7a36eeaa8d54",
                "host":"48190c8c-42c4-46af-8d1a-0cd5db894797",
                "languageId":1,
                "href":"/about-us/locations",
                "title":"Locations",
                "type":"folder",
                "hash":1931963491,
                "target":"_self",
                "order":2
            }
        ]
    },
    "messages":[],
    "i18nMessagesMap":{},
    "permissions":[]
}

Navigation Permissions #

By default, Navigation API methods do not check permissions. This means users will see all navigation items, even if they don't have permission to view those items.

To force permissions to affect Navigation methods, set the ENABLE_NAV_PERMISSION environment property to true. After this change, only items the current user has permissions to View are returned in the navigation.

ENABLE_NAV_PERMISSION_CHECK=true

If the ENABLE_NAV_PERMISSION_CHECK property is enabled, it is recommend that you enclose the navigation in a #dotcache block to avoid performance degradation.

Usage Examples #

Retrieve navigation for the "about-us" section with default depth (1 level) in English:

Request:

curl -X GET "http://localhost:8080/api/v1/nav/about-us?languageId=1" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "entity": {
    "title": "About Us",
    "target": "_self",
    "code": "about-us",
    "folder": "abc123",
    "host": "host456",
    "href": "/about-us",
    "languageId": 1,
    "order": 1,
    "type": "folder",
    "hash": 12345678,
    "children": [
      {
        "title": "Our Team",
        "target": "_self",
        "code": "our-team",
        "folder": "def789",
        "host": "host456",
        "href": "/about-us/our-team",
        "languageId": 1,
        "order": 1,
        "type": "htmlpage",
        "hash": 87654321
      }
    ]
  }
}

Retrieve navigation for the products section with 3 levels of depth: