**API versions** · [V2 (Latest)](/integrations/v2/docs?lang=en) · **V1**

> **This API version is obsolete.** Use the latest version for new integrations. [View the current documentation](/integrations/v2/docs?lang=en)

# Menu

OpenAPI 3.0.3 · API 1.0.0

```json
[
  {
    "url": "https://api.unisoft.world/integrations/v1",
    "description": "API"
  }
]
```

Website navigation menu — a per-site tree (parent/position) of free links and entity links (PAGE/FORM/CAGNOTTE). Content vs structure are separate (use /menu/reorder for the tree). Scopes: `web_menu:read`/`web_menu:write`.

## Operations

## GET /menu

List menu items (a site's tree)

`list_menu`

Required scope: `web_menu:read`. Returns the site's items (flat, ordered by position; rebuild the tree via parent/position). Pass `?virtualId` to target a site (omit = main site).

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "web_menu:read",
  "additional": []
}
```

### Parameters

```json
{
  "name": "virtualId",
  "in": "query",
  "schema": {
    "type": "string"
  },
  "description": "Site id; omit for the main site."
}
```

### Responses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MenuItem"
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "ERROR",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "ERROR"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "INSUFFICIENT_SCOPE"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "web_menu:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /menu

Create a menu item

`create_menu_item`

Required scope: `web_menu:write`. Creates an item at the end of the root level. Use `targetId` for PAGE/FORM/CAGNOTTE items.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "web_menu:write",
  "additional": []
}
```

### Request body

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/MenuItemInput"
      }
    }
  }
}
```

### Responses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/MenuItem"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "VALIDATION_ERROR",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "VALIDATION_ERROR"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "INSUFFICIENT_SCOPE"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "web_menu:write",
  "x-unisoft-mcp": {
    "category": "create",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": false
  }
}
```

## POST /menu/reorder

Reorder / re-parent menu items

`reorder_menu`

Required scope: `web_menu:write`. Sets parent + position of items in one pass (the tree/drag&drop operation). Send the full desired layout.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "web_menu:write",
  "additional": []
}
```

### Request body

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/MenuReorderInput"
      }
    }
  }
}
```

### Responses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "INSUFFICIENT_SCOPE"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "web_menu:write",
  "x-unisoft-mcp": {
    "category": "reorder",
    "readOnly": false,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## PATCH /menu/{id}

Edit a menu item

`update_menu_item`

Required scope: `web_menu:write`. Edits content only (not parent/position). Pass the item's `virtualId` in the body.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "web_menu:write",
  "additional": []
}
```

### Parameters

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
  },
  "description": "Resource id — must be a UUID. A malformed id is rejected with 400 INVALID_UUID (it is not just a 404). Need a fresh one? Call GET /utils/uuid."
}
```

### Request body

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/MenuItemInput"
      }
    }
  }
}
```

### Responses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/MenuItem"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "VALIDATION_ERROR",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "VALIDATION_ERROR"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "web_menu:write",
  "x-unisoft-mcp": {
    "category": "update",
    "readOnly": false,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## DELETE /menu/{id}

Delete a menu item

`delete_menu_item`

Required scope: `web_menu:write`. Pass `?virtualId` to scope to the site.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "web_menu:write",
  "additional": []
}
```

### Parameters

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
  },
  "description": "Resource id — must be a UUID. A malformed id is rejected with 400 INVALID_UUID (it is not just a 404). Need a fresh one? Call GET /utils/uuid."
}
```

```json
{
  "name": "virtualId",
  "in": "query",
  "schema": {
    "type": "string"
  }
}
```

### Responses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "web_menu:write",
  "x-unisoft-mcp": {
    "category": "delete",
    "readOnly": false,
    "destructive": true,
    "idempotent": true,
    "warn": false
  }
}
```

## Schemas

```json
{
  "components": {
    "schemas": {
      "MenuItem": {
        "type": "object",
        "description": "A website menu item, node of a per-site tree (parent/position). A free link (name+url) or an entity link (type + targetId).",
        "properties": {
          "id": {
            "type": "string"
          },
          "organisation": {
            "type": "string"
          },
          "virtualId": {
            "type": "string",
            "nullable": true,
            "description": "Site scope: null = the main site, otherwise a virtual site id."
          },
          "type": {
            "type": "string",
            "enum": [
              "LINK",
              "PAGE",
              "FORM",
              "CAGNOTTE",
              "ACCOUNT",
              "DYNAMIC_ARTICLES"
            ],
            "description": "Item kind. LINK = free link (name+url). PAGE/FORM/CAGNOTTE = entity link (set targetId; the label is resolved from the target). ACCOUNT = fixed link to the member account space (url \"/account\", name editable). DYNAMIC_ARTICLES = articles listing (url \"\")."
          },
          "name": {
            "type": "string",
            "description": "Displayed label (empty for FORM/CAGNOTTE links, which inherit the target's name)."
          },
          "url": {
            "type": "string",
            "description": "Target URL for a free link (empty for entity links; \"/account\" for ACCOUNT)."
          },
          "targetId": {
            "type": "string",
            "description": "Id of the linked entity (required when type is PAGE/FORM/CAGNOTTE)."
          },
          "parent": {
            "type": "string",
            "nullable": true,
            "description": "Parent item id (null = root)."
          },
          "position": {
            "type": "integer",
            "description": "Sort order among siblings."
          },
          "platform": {
            "type": "string",
            "enum": [
              "ALL",
              "ONLY_DESKTOP",
              "ONLY_APPMOBILE"
            ],
            "description": "Display surface: ALL = shown on the desktop website and in the native mobile app; ONLY_DESKTOP = desktop website only; ONLY_APPMOBILE = native mobile app only. Defaults to ALL."
          }
        }
      },
      "MenuItemInput": {
        "type": "object",
        "description": "Payload to create or edit a menu item's CONTENT. Structure (parent/position) is NOT set here — use POST /menu/reorder. On create the item lands at the end of the root level.",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "LINK",
              "PAGE",
              "FORM",
              "CAGNOTTE",
              "ACCOUNT",
              "DYNAMIC_ARTICLES"
            ],
            "description": "Item kind. LINK = free link (name+url). PAGE/FORM/CAGNOTTE = entity link (set targetId). ACCOUNT = member account space — set url to \"/account\". DYNAMIC_ARTICLES = articles listing — set url to \"\"."
          },
          "name": {
            "type": "string",
            "description": "Displayed label (use \"\" for FORM/CAGNOTTE links)."
          },
          "url": {
            "type": "string",
            "description": "Target URL for a free link (use \"\" for entity links; \"/account\" for ACCOUNT)."
          },
          "targetId": {
            "type": "string",
            "description": "Id of the linked entity — required when type is PAGE/FORM/CAGNOTTE."
          },
          "virtualId": {
            "type": "string",
            "nullable": true,
            "description": "Site to attach the item to (null/omit = main site)."
          },
          "platform": {
            "type": "string",
            "enum": [
              "ALL",
              "ONLY_DESKTOP",
              "ONLY_APPMOBILE"
            ],
            "description": "Display surface for this item. ALL = desktop website + native mobile app; ONLY_DESKTOP = desktop website only; ONLY_APPMOBILE = native mobile app only. Omit/invalid → ALL. Only sent when you want to change it (omitting keeps the current value on edit)."
          }
        }
      },
      "MenuReorderInput": {
        "type": "object",
        "description": "Set the parent + position of menu items in one atomic pass (the drag&drop / tree operation). Send the full desired layout.",
        "required": [
          "items"
        ],
        "properties": {
          "virtualId": {
            "type": "string",
            "nullable": true,
            "description": "Site scope (null/omit = main site)."
          },
          "items": {
            "type": "array",
            "description": "Desired layout.",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "parent": {
                  "type": "string",
                  "nullable": true,
                  "description": "Parent item id (null = root)."
                },
                "position": {
                  "type": "integer"
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key",
        "description": "Format: `ke_live_xxx`"
      },
      "apiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    },
    "parameters": {
      "IdParam": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid",
          "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
        },
        "description": "Resource id — must be a UUID. A malformed id is rejected with 400 INVALID_UUID (it is not just a 404). Need a fresh one? Call GET /utils/uuid."
      }
    }
  }
}
```
