Manage custom dashboards with configurable widget grids. Dashboards can be organised into bases (group containers) using a self-referential parentId hierarchy. Bases appear as concertina drawers in the sidebar, with child dashboards nested inside. Each workspace can have multiple dashboards with drag-and-drop widget layouts, date-range filtering, multi-series charts, auto-refresh, global filters, and JSON import/export. Dashboards support 26 widget types spanning metrics, charts, tables, and content blocks. Widget data is computed server-side via the widget-data endpoint.

Workspace Provisioning

• When a new workspace is created, a default overview dashboard (type: DASHBOARD) is automatically provisioned with 4 widgets: Recent Activity, Total Submissions, Active Matters, and Matters by Status.
• A per-user task list (type: TASK_LIST) is also provisioned for the workspace creator. Additional members receive their task list when added.
• Provisioning is idempotent - safe to call multiple times.
• All dashboard pages resolve the active workspace from the user's current workspace preference (set by the workspace switch API).

Route Conventions

• All endpoints require authentication and appropriate workspace permissions.
• Mutation routes (POST, PUT, DELETE) require a valid security token and validate JSON payloads.
• The GET widget-data endpoint uses query-string encoding for read operations (no security token required).
• Errors follow { error, details? }.

Endpoints

Create Dashboard

Creates a new dashboard for the workspace. The name field is required.

POST /api/dashboards
Content-Type: application/json

// Create a regular dashboard inside a base
{
  "name": "Sales Overview",
  "description": "Key metrics and pipeline health",
  "parentId": "clxyz..."
}

// Create a base (group container)
{
  "name": "Analytics",
  "settings": { "isBase": true, "icon": "layers" }
}

Request Body

Update Dashboard

Updates an existing dashboard. All fields are optional. The config field stores the full widget grid definition including auto-refresh and global filter settings.

PUT /api/dashboards/:id
Content-Type: application/json

{
  "name": "Sales Overview",
  "isStarred": true,
  "config": {
    "version": 1,
    "widgets": [],
    "autoRefreshInterval": 60,
    "globalFilters": [
      { "field": "status", "operator": "eq", "value": "OPEN" }
    ]
  }
}

Request Body

Config Structure

The config field defines the dashboard widget grid, auto-refresh behaviour, and global filters. It is validated against a strict schema. You can export and import this JSON directly from the dashboard UI (Grid/JSON tabs).

{
  "version": 1,
  "autoRefreshInterval": 60,
  "globalFilters": [
    { "field": "status", "operator": "eq", "value": "OPEN" }
  ],
  "widgets": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "type": "bar_chart",
      "dataSource": {
        "type": "matters",
        "dateField": "createdAt",
        "filters": [
          { "field": "status", "operator": "in", "value": ["OPEN", "ON_HOLD"] }
        ]
      },
      "aggregation": { "function": "count", "column": "status" },
      "groupBy": { "column": "status" },
      "secondaryGroupBy": { "column": "priority" },
      "appearance": {
        "title": "Matters by Status & Priority",
        "subtitle": "Multi-series grouped chart",
        "showLegend": true,
        "showSparkline": false
      },
      "layout": { "x": 0, "y": 0, "w": 600, "h": 320, "minW": 300, "minH": 240 }
    }
  ]
}

Top-Level Config Fields

Widget Fields

Widget Types

26 widget types are available, spanning metrics, charts, tables, and content blocks.

Data Sources

Each widget specifies a dataSource object. All sources support dateField for time-based filtering and filters for field-level conditions.

Filter Object

Filters can be applied at the data source level (per-widget) or at the config level (global filters affecting all compatible widgets).

{
  "field": "status",
  "operator": "in",
  "value": ["OPEN", "ON_HOLD"]
}

Widget Data

Fetch computed data for a single widget. The primary endpoint is GET with a base64-encoded query parameter q. A legacy POST endpoint is also available.

GET (preferred)

GET /api/dashboards/:id/widget-data?q=<base64-encoded-json>

The q parameter is the base64 encoding of a JSON object:

{
  "widgetType": "bar_chart",
  "dataSource": { "type": "matters" },
  "aggregation": { "function": "count", "column": "status" },
  "groupBy": { "column": "status" },
  "dateFrom": "2026-01-01T00:00:00.000Z",
  "dateTo": "2026-02-24T23:59:59.999Z"
}

POST (legacy)

POST /api/dashboards/:id/widget-data
Content-Type: application/json

{
  "widgetType": "bar_chart",
  "dataSource": {
    "type": "matters",
    "filters": [
      { "field": "status", "operator": "in", "value": ["OPEN", "ON_HOLD"] }
    ]
  },
  "aggregation": { "function": "count", "column": "status" },
  "groupBy": { "column": "status" },
  "secondaryGroupBy": { "column": "priority" },
  "dateFrom": "2026-01-01T00:00:00.000Z",
  "dateTo": "2026-02-24T23:59:59.999Z",
  "includeSparkline": true,
  "maxRows": 100
}

Request Fields

Response - Single Series

{
  "data": {
    "series": [
      { "label": "Open", "value": 42 },
      { "label": "In Progress", "value": 18 },
      { "label": "Closed", "value": 67 }
    ],
    "summary": { "total": 127, "count": 3, "avg": 42.3 },
    "sparklineData": [12, 15, 18, 22, 19, 24, 17]
  }
}

Response - Multi-Series (with secondaryGroupBy)

{
  "data": {
    "series": [],
    "multiSeries": {
      "categories": ["Open", "In Progress", "Closed"],
      "series": [
        { "name": "High", "data": [12, 5, 20] },
        { "name": "Medium", "data": [20, 8, 30] },
        { "name": "Low", "data": [10, 5, 17] }
      ]
    },
    "summary": { "total": 127, "count": 3 }
  }
}

Response Fields

Aggregation Functions

Appearance Fields

The appearance object controls visual presentation. Only title is required; all other fields are optional and type-dependent.

Date Range Presets

The dashboard UI includes a persistent date range toolbar. When a range is selected, the client computes dateFrom and dateTo and passes them to each widget-data request.

GroupBy Options

{
  "column": "createdAt",
  "dateGranularity": "week",
  "limit": 20,
  "sort": "asc"
}

JSON Import / Export

The dashboard editor supports a Grid/JSON tab switcher. In JSON mode you can view and edit the raw dashboard config directly. Changes are validated in real time.

• Export: Click "Export .json" to download the config as a file, or "Copy" to copy to clipboard.
• Import: Click the Import button and select a .json file. The file is validated before applying.
• Programmatic: Build a dashboard config JSON object and submit it via PUT /api/dashboards/:id with the config field.

{
  "version": 1,
  "widgets": [
    {
      "id": "my-metric-1",
      "type": "metric",
      "dataSource": { "type": "matters" },
      "aggregation": { "function": "count", "column": "id" },
      "appearance": {
        "title": "Total Matters",
        "showSparkline": true
      },
      "layout": { "x": 0, "y": 0, "w": 300, "h": 160 }
    }
  ]
}

KPI Scorecard Example

The kpi_scorecard widget renders 2-4 metrics in a horizontal row, each with its own aggregation, sparkline, and change indicator.

{
  "id": "scorecard-1",
  "type": "kpi_scorecard",
  "dataSource": { "type": "matters" },
  "aggregation": { "function": "count", "column": "id" },
  "appearance": {
    "title": "Matter Summary",
    "scorecardMetrics": [
      { "label": "Total", "column": "id", "aggregation": "count" },
      { "label": "Open", "column": "status_OPEN", "aggregation": "count" },
      { "label": "Completed", "column": "status_COMPLETED", "aggregation": "count" },
      { "label": "Avg Days", "column": "daysOpen", "aggregation": "avg" }
    ]
  },
  "layout": { "x": 0, "y": 0, "w": 1200, "h": 160, "minW": 600, "minH": 160 }
}

Canvas Config

Dashboards use a pixel-based freeform canvas. Widgets are positioned absolutely with x, y pixel coordinates and sized with w, h pixel dimensions. Canvas alignment guides appear automatically when dragging or resizing widgets, showing snap lines to neighbouring widget edges and centres for precise positioning.

AI Dashboard Tools

The AI assistant includes 7 tools for programmatic dashboard management. These tools allow the AI to list, add, update, remove, and bulk-update widgets, as well as replace the entire dashboard config. Additional theme AI tools let the AI read, create, update, and delete custom user themes, enabling AI-driven theme generation and customisation.

See the AI Tools Reference for full parameter details.

Sharing and Permissions

Each dashboard has sharing settings stored in its settings.sharing JSON field. Sharing controls who can view or edit a dashboard, with two visibility modes and per-user collaborator overrides.

Get Sharing Settings

GET /api/dashboards/:id/sharing

{
  "sharing": {
    "visibility": "workspace",
    "workspaceRole": "editor",
    "collaborators": [
      { "userId": "clx...", "role": "editor" }
    ]
  },
  "canManage": true,
  "members": [
    {
      "userId": "clx...",
      "name": "Will Lilley",
      "email": "will@example.com",
      "collaboratorRole": "editor"
    }
  ]
}

visibility is "workspace" or "restricted". workspaceRole is "viewer" or "editor" (default access for workspace members). canManage is true if the user is admin/owner or dashboard creator. collaboratorRole is null if the member is not a collaborator.

Update Sharing Settings

Only workspace admins/owners or the dashboard creator can update sharing settings.

PUT /api/dashboards/:id/sharing
Content-Type: application/json

{
  "visibility": "restricted",
  "workspaceRole": "viewer",
  "collaborators": [
    { "userId": "clx...", "role": "editor" },
    { "userId": "clx...", "role": "viewer" }
  ]
}

Request Body

Cross-Workspace Data (Oversight)

Oversight workspaces can query data from subordinate workspaces in dashboard widgets. Set the sourceWorkspaceId field in a widget's data source to target a subordinate workspace.

{
  "type": "table",
  "tableId": "clx...",
  "sourceWorkspaceId": "clx..."
}

• The widget-data API verifies an active OversightRelationship before querying the subordinate workspace.
• If no oversight relationship exists or it is inactive, the API returns 403.
• The designer sidebar shows a "Workspace" picker above the Source picker when the current workspace has subordinate workspaces.

Autosave

Dashboard widget configuration (layout, data source, appearance, elements) is autosaved with a 2-second debounce. The save indicator shows a dot for unsaved changes, a spinner while saving, and a brief "Autosaved" label that fades out after 2 seconds. Autosave only tracks structural config changes - not live data refreshes or widget data updates.

Dashboard Comments

Each dashboard supports threaded comments via the DashboardComment model. Comments are scoped to a dashboard and user, with optional parentId for nested replies. Comments include a content text field, timestamps (createdAt, updatedAt), and cascade-delete when the parent dashboard is removed.

Delete Dashboard

Deletes a dashboard. The default dashboard cannot be deleted and will return a 400 error.

DELETE /api/dashboards/:id

Error response when deleting default dashboard:

{
  "error": "Cannot delete the default dashboard"
}