UI Mounts API

Base path: /api/catalog/workspaces/{workspaceId}/ui-mounts

The UI Mount API lets the frontend shell discover all navigation items, routes, and widgets contributed by installed extensions — without any hardcoded knowledge of which extensions exist.

Authorization: Requires ADMIN role or workspace membership.

Get All Mounts (Bundle)

Returns nav items, routes, and widgets in a single response. Use this on app initialization.

GET /api/catalog/workspaces/{workspaceId}/ui-mounts

Example

curl http://localhost:8080/api/catalog/workspaces/ws-uuid/ui-mounts \
  -b cookies.txt

Response

{
  "code": "SUCCESS",
  "data": {
    "nav": [
      {
        "extensionKey": "crm-extension",
        "label": "CRM",
        "icon": "briefcase",
        "route": "/crm",
        "displayOrder": 1
      }
    ],
    "routes": [
      {
        "extensionKey": "crm-extension",
        "path": "/crm",
        "assetsBaseUrl": "http://localhost:8081/assets"
      }
    ],
    "widgets": [
      {
        "extensionKey": "crm-extension",
        "mountPoint": "dashboard.sidebar",
        "assetsBaseUrl": "http://localhost:8081/assets"
      }
    ]
  }
}

---

Get Nav Items

GET /api/catalog/workspaces/{workspaceId}/ui-mounts/nav

Returns the ordered list of navigation items to render in the app sidebar/header.

Response

{
  "code": "SUCCESS",
  "data": [
    {
      "extensionKey": "crm-extension",
      "label": "CRM",
      "icon": "briefcase",
      "route": "/crm",
      "displayOrder": 1
    }
  ]
}

---

Get Routes

GET /api/catalog/workspaces/{workspaceId}/ui-mounts/routes

Returns all frontend routes registered by extensions.

Response

{
  "code": "SUCCESS",
  "data": [
    {
      "extensionKey": "crm-extension",
      "path": "/crm",
      "assetsBaseUrl": "http://localhost:8081/assets"
    }
  ]
}

---

Get Widgets

GET /api/catalog/workspaces/{workspaceId}/ui-mounts/widgets?mountPoint=dashboard.sidebar

Query Parameters

Parameter	Required	Description
mountPoint	—	Filter widgets by their mount point (e.g. dashboard.sidebar)

---

Get Extension UI Asset

Proxies static assets (JS, CSS, images) from an extension's asset server through the platform.

GET /api/catalog/workspaces/{workspaceId}/ui-mounts/{extensionKey}/assets/**

Example

GET /api/catalog/workspaces/ws-uuid/ui-mounts/crm-extension/assets/main.js

---

Mount Types

Type	Description
NAV	Navigation item in the shell sidebar or header
ROUTE	A full page/view registered in the frontend router
WIDGET	An embeddable component rendered at a named mount point

---

Integration Pattern

// On login — fetch all mounts once
const { data: mounts } = await fetch(`/api/catalog/workspaces/${workspaceId}/ui-mounts`).then(r => r.json());

// Register routes dynamically
mounts.routes.forEach(route => {
  router.addRoute({ path: route.path, component: () => loadRemoteModule(route.assetsBaseUrl) });
});

// Render nav items
mounts.nav.sort((a, b) => a.displayOrder - b.displayOrder).forEach(item => {
  renderNavItem(item.label, item.icon, item.route);
});

See the Frontend UI Mount Integration Guide for a complete walkthrough.