Navigation REST APIdocumentation for the dotCMS Content Management System

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":[]
}