Menus API

The Menus API provides endpoints for managing menus and menu items in Joomla.

Base URL

/api/index.php/v1/menus

Endpoints Overview

Menu Types

Method	Endpoint	Description
GET	/menus/site	Retrieve all menus
GET	/menus/site/{id}	Retrieve specific menu
POST	/menus/site	Create new menu
PATCH	/menus/site/{id}	Update menu
DELETE	/menus/site/{id}	Delete menu

Menu Items

Method	Endpoint	Description
GET	/menus/site/items	Retrieve all menu items
GET	/menus/site/items/{id}	Retrieve specific item
POST	/menus/site/items	Create new menu item
PATCH	/menus/site/items/{id}	Update menu item
DELETE	/menus/site/items/{id}	Delete menu item

Menu Types

Retrieve all menus

GET /api/index.php/v1/menus/site

Response

{
    "data": [
        {
            "type": "menus",
            "id": "1",
            "attributes": {
                "menutype": "mainmenu",
                "title": "Main Menu",
                "description": "The main menu of the site"
            }
        }
    ]
}

Create menu

POST /api/index.php/v1/menus/site

Request Body

{
    "menutype": "footermenu",
    "title": "Footer Menu",
    "description": "Menu items in the footer"
}

Required fields

Field	Type	Description
menutype	string	Unique identifier for menu
title	string	Menu title

Example

curl -X POST "https://yoursite.com/api/index.php/v1/menus/site" \
  -H "X-Joomla-Token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "menutype": "footermenu",
    "title": "Footer Menu"
  }'

Menu Items

Retrieve all menu items

GET /api/index.php/v1/menus/site/items

Response

{
    "data": [
        {
            "type": "menu-items",
            "id": "101",
            "attributes": {
                "title": "Home",
                "alias": "home",
                "menutype": "mainmenu",
                "type": "component",
                "link": "index.php?option=com_content&view=featured",
                "published": 1,
                "parent_id": 1,
                "level": 1,
                "component_id": 22,
                "language": "*"
            }
        }
    ]
}

Create menu item

POST /api/index.php/v1/menus/site/items

Request Body for article link

{
    "title": "About Us",
    "alias": "about-us",
    "menutype": "mainmenu",
    "type": "component",
    "link": "index.php?option=com_content&view=article&id=1",
    "parent_id": 1,
    "published": 1,
    "access": 1,
    "language": "*"
}

Request Body for external URL

{
    "title": "External Link",
    "alias": "external-link",
    "menutype": "mainmenu",
    "type": "url",
    "link": "https://example.com",
    "parent_id": 1,
    "published": 1
}

Request Body for separator

{
    "title": "---",
    "menutype": "mainmenu",
    "type": "separator",
    "parent_id": 1
}

Required fields

Field	Type	Description
title	string	Menu item title
menutype	string	Menu the item belongs to
type	string	Type (component/url/separator)
link	string	Link URL (except separator)

Optional fields

Field	Type	Default	Description
alias	string	auto	URL-friendly name
parent_id	int	1	Parent menu item ID
published	int	1	Publication status
access	int	1	Access level
language	string	"*"	Language code
browserNav	int	0	Open in: 0=same, 1=new

Example

curl -X POST "https://yoursite.com/api/index.php/v1/menus/site/items" \
  -H "X-Joomla-Token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Contact",
    "alias": "contact",
    "menutype": "mainmenu",
    "type": "component",
    "link": "index.php?option=com_contact&view=contact&id=1",
    "published": 1
  }'

Update menu item

PATCH /api/index.php/v1/menus/site/items/{id}

Example

curl -X PATCH "https://yoursite.com/api/index.php/v1/menus/site/items/101" \
  -H "X-Joomla-Token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "New Title",
    "published": 0
  }'

Delete menu item

DELETE /api/index.php/v1/menus/site/items/{id}

Menu Item Types

Type	Description
component	Link to Joomla component
url	External or internal URL
alias	Alias to another menu item
separator	Separator line
heading	Heading (not clickable)

Common Link Formats

Article

index.php?option=com_content&view=article&id={article_id}

Category blog

index.php?option=com_content&view=category&layout=blog&id={category_id}

Category list

index.php?option=com_content&view=category&id={category_id}

Contact

index.php?option=com_contact&view=contact&id={contact_id}

All contacts

index.php?option=com_contact&view=categories

Filtering

By menu type

GET /api/index.php/v1/menus/site/items?filter[menutype]=mainmenu

By publication status

GET /api/index.php/v1/menus/site/items?filter[published]=1

By parent

GET /api/index.php/v1/menus/site/items?filter[parent_id]=1

Submenu Items

Use parent_id to create submenus.

Example: Submenu item

curl -X POST "https://yoursite.com/api/index.php/v1/menus/site/items" \
  -H "X-Joomla-Token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Sub Item",
    "menutype": "mainmenu",
    "type": "url",
    "link": "/sub-page",
    "parent_id": 101
  }'