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:
| Parameter | Default Value | Description | Examples |
|---|---|---|---|
| path | (None) | The root path to begin traversing the folder tree. |
|
| depth | 1 | The depth of the folder tree to return. |
|
| languageId | 1 | The 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":[]
}
