dotCMS logodotCMS logo

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.

Parameters#

The API accepts the following parameters:

ParameterDefault ValueDescriptionExamples
path(None)The root path to begin traversing the folder tree.
  • / (e.g. /api/v1/nav/) starts from the root of the site
  • /about-us starts from the "About Us" folder
  • etc.
depth1The depth of the folder tree to return.
  • 1 returns only the element specified in the 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.
languageId1The language ID of content to return.
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",
        "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
            },
            {
                "code":null,
                "folder":"ce49e1e7-4d0f-4af2-a87c-5e9c5562278c",
                "host":"48190c8c-42c4-46af-8d1a-0cd5db894797",
                "languageId":1,
                "href":"/about-us/our-team",
                "title":"Our Team",
                "type":"folder",
                "hash":2075344630,
                "target":"_self",
                "order":3
            }
        ],
        "host":"48190c8c-42c4-46af-8d1a-0cd5db894797",
        "languageId":1,
        "href":"/about-us",
        "title":"About Us",
        "type":"folder",
        "hash":1704969069,
        "target":"_self",
        "order":1
    },
    "messages":[],
    "i18nMessagesMap":{},
    "permissions":[]
}