Documentation | 2025.1

# Menus: Swarm main menu items

## Get main menu details

### Summary

Get details of the Swarm main menu items.

GET /api/v11/menus

### Description

Get details of the Swarm main menu items including custom menu items.

Any users can get the Swarm main menu details, the user does not need to be authenticated.

Parameter | Description | Type | Parameter Type | Required
--- | --- | --- | --- | ---
project | Specify a project in the request to return the menu items for the project. | string | query | No

### Example usage

#### Fetch Swarm menu items

Get details of the Swarm main menu items:

curl "https://myswarm-url/api/v11/menus"

Swarm responds with:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data" : {
        "menu": [
          {
            "id": "dashboard",
            "enabled": true,
            "target": "/",
            "cssClass": "component",
            "title": "dashboard",
            "priority": 100,
            "roles": null
          },
          {
            "id": "activity",
            "enabled": true,
            "target": "/activity/",
            "cssClass": "activity",
            "title": "activity",
            "priority": 120,
            "roles": null
          },
          {
            "id": "reviews",
            "enabled": true,
            "target": "/reviews/",
            "cssClass": "component",
            "title": "reviews",
            "priority": 130,
            "roles": null
          },
          {
            "id": "projects",
            "enabled": true,
            "target": "/projects/",
            "cssClass": "projects",
            "title": "projects",
            "priority": 140,
            "roles": null
          },
          {
            "id": "files",
            "enabled": true,
            "target": "/files/",
            "cssClass": "files",
            "title": "files",
            "priority": 150,
            "roles": null
          },
          {
            "id": "changes",
            "enabled": true,
            "target": "/changes/",
            "cssClass": "changes",
            "title": "changes",
            "priority": 160,
            "roles": null
          },
          {
            "id": "jobs",
            "enabled": true,
            "target": "/jobs/",
            "cssClass": "jobs",
            "title": "jobs",
            "priority": 170,
            "roles": null
          },
          {
            "id": "groups",
            "enabled": true,
            "target": "/groups/",
            "cssClass": "groups",
            "title": "groups",
            "priority": 180,
            "roles": null
          },
          {
            "id": "workflows",
            "enabled": true,
            "target": "/workflows/",
            "cssClass": "workflows",
            "title": "workflows",
            "priority": 190,
            "roles": null
          },
          {
            "id": "tests",
            "enabled": true,
            "target": "/testdefinitions/",
            "cssClass": "tests",
            "title": "tests",
            "priority": 200,
            "roles": null
          },
          {
            "id": "jenkins_blue",
            "enabled": true,
            "target": "http://my-jenkins.instance.blue.com",
            "cssClass": "custom_menu",
            "title": "Jenkins Build",
            "priority": 210,
            "roles": "authenticated"
          }
        ],
        "contextMetadata": []
      }
    }

#### Fetch menu items for a project (authenticated and project owner)

Get menu items for project Jam when the authenticated user owns the project:

curl -u "username:ticket" "https://myswarm-url/api/v11/menus?project=jam"

Swarm responds with:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data" : {
        "menu": [
          {
            "id": "activity",
            "enabled": true,
            "target": "/projects/jam/activity/",
            "cssClass": "activity",
            "title": "activity",
            "priority": 120,
            "roles": null
          },
          {
            "id": "reviews",
            "enabled": true,
            "target": "/projects/jam/reviews/",
            "cssClass": "component",
            "title": "reviews",
            "priority": 130,
            "roles": null
          },
          {
            "id": "files",
            "enabled": true,
            "target": "/projects/jam/files/",
            "cssClass": "files",
            "title": "files",
            "priority": 150,
            "roles": null
          },
          {
            "id": "changes",
            "enabled": true,
            "target": "/projects/jam/changes/",
            "cssClass": "changes",
            "title": "changes",
            "priority": 160,
            "roles": null
          },
          {
            "id": "settings",
            "enabled": true,
            "target": "/projects/jam/settings/",
            "cssClass": "settings",
            "title": "settings",
            "priority": 200,
            "roles": null
          }
        ],
        "contextMetadata": {
          "contextName": "jam"
        }
      }
    }

#### Fetch menu items for a project (unauthenticated or not project owner)

Get menu items for project Jam without authentication or when the authenticated user is not a project owner:

curl "https://myswarm-url/api/v11/menus?project=jam"

Swarm responds with:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data" : {
        "menu": [
          {
            "id": "activity",
            "enabled": true,
            "target": "/projects/jam/activity/",
            "cssClass": "activity",
            "title": "activity",
            "priority": 120,
            "roles": null
          },
          {
            "id": "reviews",
            "enabled": true,
            "target": "/projects/jam/reviews/",
            "cssClass": "component",
            "title": "reviews",
            "priority": 130,
            "roles": null
          },
          {
            "id": "files",
            "enabled": true,
            "target": "/projects/jam/files/",
            "cssClass": "files",
            "title": "files",
            "priority": 150,
            "roles": null
          },
          {
            "id": "changes",
            "enabled": true,
            "target": "/projects/jam/changes/",
            "cssClass": "changes",
            "title": "changes",
            "priority": 160,
            "roles": null
          }
        ],
        "contextMetadata": {
          "contextName": "Jam"
        }
      }
    }

#### If a request fails

<error code>:

- 404 Project specified does not exist

    HTTP/1.1 <response error code>

    {
      "error": <error code>,
      "messages": [{
        "code" : "<code string>",
        "text" : "<error message>"
      }],
      "data" : null
    }

Your search for returned results