PagibleAI JSON:API Navigation

Optimize your site’s performance by retrieving your complete navigation structure—including breadcrumbs, sub-navigation menus, and mega menus - alongside your page content in a single, efficient request. The navigation items, represented as "navs," are streamlined versions of your pages.

These "navs" exclude resource-intensive elements like content, configuration details, and meta fields, ensuring faster loading times. Furthermore, you have the flexibility to apply a distinct set of sparse fields to "navs" compared to full "pages," allowing for precise control over the data you retrieve and display, thus enhancing both speed and customization.

Here's how to efficiently retrieve all the data you need to construct your site's navigation: breadcrumbs and multi-level menus, in a single request. Simply include ancestors and menu in the include parameter of your API request.

https://pagible.com/cms/pages/01993e44-f1b1-7bf8-09ff-f1f0f5f7fdf5?include=ancestors,menu

The ancestors parameter provides the data needed for breadcrumb navigation, while menu delivers the structure required for building comprehensive (mega) menus.

To create a breadcrumb navigation, you need to fetch all items from the current page up to the root page (the ancestors):

https://pagible.com/cms/pages/01993e44-f1b1-7bf8-09ff-f1f0f5f7fdf5?include=ancestors

Then, they are referenced in the relationships of the current page added in the included section of the response:

"relationships": {
  "ancestors": {
    "data": [
      {
        "type": "navs",
        "id": "0198a4b2-3c5e-7f1a-8d2b-e4f6a8c0d2e4"
      },
      {
        "type": "navs",
        "id": "0198d0f8-8c1e-75fc-b7fd-e5d9f3a7c1e3"
      }
    ]
  }
}

They are ordered from the root page to the direct parent of the current page. Each ancestor page item is contained in the included section:

"included": [
  {
    "type": "navs",
    "id": "0198a4b2-3c5e-7f1a-8d2b-e4f6a8c0d2e4",
    "attributes": {
      "parent_id": null,
      "lang": "en",
      "name": "Home",
      "path": "",
      "title": "PagibleAI CMS",
      "to": "",
      "domain": "",
      "tag": "root",
      "theme": "",
      "type": null,
      "cache": 5,
      "has": true,
      "status": 1,
      "createdAt": "2025-07-29T09:00:58.000000Z",
      "updatedAt": "2025-08-20T22:46:15.000000Z"
    },
    "links": {
      "self": "https:\/\/pagible.com\/cms\/pages\/0198a4b2-3c5e-7f1a-8d2b-e4f6a8c0d2e4"
    }
  },
  {
    "type": "navs",
    "id": "0198d0f8-8c1e-75fc-b7fd-e5d9f3a7c1e3",
    "attributes": {
      "parent_id": "0198a4b2-3c5e-7f1a-8d2b-e4f6a8c0d2e4",
      "lang": "en",
      "name": "Blog",
      "path": "blog",
      "title": "Blog | PagibleAI CMS",
      "to": "",
      "domain": "",
      "tag": "blog",
      "theme": "",
      "type": null,
      "cache": 5,
      "has": true,
      "status": 1,
      "createdAt": "2025-07-29T09:00:58.000000Z",
      "updatedAt": "2025-07-29T09:00:58.000000Z"
    },
    "links": {
      "self": "https:\/\/pagible.com\/cms\/pages\/0198d0f8-8c1e-75fc-b7fd-e5d9f3a7c1e3"
    }
  }
]

To construct the breadcrumb, iterate over the ancestors list and match each entry with the corresponding item in the included section by type and id.

The children relationship returns the direct sub-pages of the requested page. This is useful if you want to display pages directly below the current page, e.g. a list of blog articles:

https://pagible.com/cms/pages/0198d0f8-8c1e-75fc-b7fd-e5d9f3a7c1e3?include=children

Then, the relationship will reference the list of direct child pages:

"relationships": {
  "children": {
    "data": [
      {
        "type": "navs",
        "id": "0198e2a4-9d3f-77fe-c9af-f7ebb5c9d3f5"
      },
      {
        "type": "navs",
        "id": "019914a2-b2c8-7a1e-f5d3-c7e9b1d3f5a7"
      }
    ]
  }
}

The child items are included in the included section:

"included": [
  {
    "type": "navs",
    "id": "0198e2a4-9d3f-77fe-c9af-f7ebb5c9d3f5",
    "attributes": {
      "parent_id": "0198d0f8-8c1e-75fc-b7fd-e5d9f3a7c1e3",
      "lang": "en",
      "name": "The Future of Content Management",
      "path": "pagibleai-cms-powerful-simple-scalable-ai-content-management",
      "title": "PagibleAI CMS: Powerful, Simple, Scalable AI-Content Management",
      "to": "",
      "domain": "",
      "tag": "",
      "theme": "",
      "type": null,
      "cache": 5,
      "has": false,
      "status": 1,
      "createdAt": "2025-08-01T12:30:00.000000Z",
      "updatedAt": "2025-08-01T12:30:00.000000Z"
    },
    "links": {
      "self": "https:\/\/pagible.com\/cms\/pages\/0198e2a4-9d3f-77fe-c9af-f7ebb5c9d3f5"
    }
  }
]

The menu relationship is a convenience option to retrieve the navigation menu items based on the configured navigation depth. It returns the menu structure for building your site's navigation. The depth of the menu is controlled by the cms.navdepth configuration, which can be set in your ./config/cms.php file:

https://pagible.com/cms/pages/0198a4b2-3c5e-7f1a-8d2b-e4f6a8c0d2e4?include=menu

The relationships/menu section references all available menu items:

"relationships": {
  "menu": {
    "data": [
      {
        "type": "navs",
        "id": "0198d0f8-8c1e-75fc-b7fd-e5d9f3a7c1e3"
      },
      {
        "type": "navs",
        "id": "0198f4b6-ae5a-79f0-dbc1-a9fdc7dbe5a7"
      },
      {
        "type": "navs",
        "id": "01990608-bf7b-7bf2-edc3-bbafd9edf7b9"
      }
    ]
  }
}

Each menu item in the included section contains a parent_id attribute, which you can use to construct a hierarchical menu structure by matching parent_id values to the id of their parent items.

"included": [
  {
    "type": "navs",
    "id": "0198d0f8-8c1e-75fc-b7fd-e5d9f3a7c1e3",
    "attributes": {
      "parent_id": "0198a4b2-3c5e-7f1a-8d2b-e4f6a8c0d2e4",
      "lang": "en",
      "name": "Blog",
      "path": "blog",
      "title": "Blog | PagibleAI CMS",
      "to": "",
      "domain": "",
      "tag": "blog",
      "theme": "",
      "type": null,
      "cache": 5,
      "has": true,
      "status": 1,
      "createdAt": "2025-07-29T09:00:58.000000Z",
      "updatedAt": "2025-07-29T09:00:58.000000Z"
    },
    "links": {
      "self": "https:\/\/pagible.com\/cms\/pages\/0198d0f8-8c1e-75fc-b7fd-e5d9f3a7c1e3"
    }
  }
]

Navigation items are returned as type navs instead of pages. This is a performance optimization: navs are lightweight page objects that exclude resource-intensive properties like content, config, and meta. This reduces the response size and improves loading times.

You can also apply separate sparse fields to navs and pages independently:

https://pagible.com/cms/pages?filter[tag]=root&include=menu&fields[pages]=name,path,content,menu&fields[navs]=name,path

This requests full content for the page itself but only name and path for the navigation items.

Note that PagibleAI CMS navigation does not return a nested tree structure. Instead, it follows JSON:API conventions where all items are in a flat included array. To build a hierarchical menu, you need to reconstruct the tree structure in your application by matching parent_id values to id values. This approach is consistent with the JSON:API specification and avoids redundant data.

The parent relationship returns the direct parent page of the requested page. This is useful to access the parent page's properties:

https://pagible.com/cms/pages/0198e2a4-9d3f-77fe-c9af-f7ebb5c9d3f5?include=parent

The relationship will reference the parent page:

"relationships": {
  "parent": {
    "data": {
      "type": "navs",
      "id": "0198d0f8-8c1e-75fc-b7fd-e5d9f3a7c1e3"
    }
  }
}

The parent item is included in the included section with its full attributes:

"included": [
  {
    "type": "navs",
    "id": "0198d0f8-8c1e-75fc-b7fd-e5d9f3a7c1e3",
    "attributes": {
      "parent_id": "0198a4b2-3c5e-7f1a-8d2b-e4f6a8c0d2e4",
      "lang": "en",
      "name": "Blog",
      "path": "blog",
      "title": "Blog | PagibleAI CMS",
      "to": "",
      "domain": "",
      "tag": "blog",
      "theme": "",
      "type": null,
      "cache": 5,
      "has": true,
      "status": 1,
      "createdAt": "2025-07-29T09:00:58.000000Z",
      "updatedAt": "2025-07-29T09:00:58.000000Z"
    },
    "links": {
      "self": "https:\/\/pagible.com\/cms\/pages\/0198d0f8-8c1e-75fc-b7fd-e5d9f3a7c1e3"
    }
  }
]

For a root page, the parent/data key will be null, as there's no parent page above the root.

The subtree relationship returns a tree of sub-pages up to three levels deep. This is designed for building mega-menus or similar deep navigation structures:

https://pagible.com/cms/pages/0198a4b2-3c5e-7f1a-8d2b-e4f6a8c0d2e4?include=subtree

The relationship will reference all pages in the subtree:

"relationships": {
  "subtree": {
    "data": [
      {
        "type": "navs",
        "id": "0198d0f8-8c1e-75fc-b7fd-e5d9f3a7c1e3"
      },
      {
        "type": "navs",
        "id": "0198e2a4-9d3f-77fe-c9af-f7ebb5c9d3f5"
      },
      {
        "type": "navs",
        "id": "0198f4b6-ae5a-79f0-dbc1-a9fdc7dbe5a7"
      }
    ]
  }
}

Like with menu and children, all subtree items appear in the included section. Use parent_id to reconstruct the tree hierarchy.