SIGNALS Docs
Reader View

Dashboards API

Read dashboard widgets and manage personal dashboards and published snapshots through REST and MCP.

Access

Use dashboards:read for reads and dashboards:write for writes. Personal boards belong exclusively to their creator. Publishing, editing and unpublishing shares also requires settings.manage. Seeing a shared board grants access to its layout; each widget still uses the recipient's domain permissions, warehouse access, privacy restrictions and cost visibility.

All operations follow API conventions. Success bodies use {data}. Invalid commands return 422; missing abilities or permissions return 403. Missing or invisible shared boards return 404.

Personal boards

MethodURLSummaryAbilityWeight
GET/api/v1/dashboardsIndex dashboardsdashboards:read1
POST/api/v1/dashboardsStore dashboardsdashboards:write3
GET/api/v1/dashboards/{dashboard}Show dashboardsdashboards:read1
PUT/api/v1/dashboards/{dashboard}Update dashboardsdashboards:write3
DELETE/api/v1/dashboards/{dashboard}Destroy dashboardsdashboards:write3

Create with {"name":"Dispatch"} to use the caller's role preset, or supply a layout object. A layout contains groups and optional hidden_plugin_widgets. Groups contain id, nullable label and widgets; widget entries contain key and optional id, size, col, row, w, h and settings. The layout resolver normalises placement and removes widgets the caller cannot view. Supplied group and widget IDs must contain 1–80 ASCII letters, digits, underscores or hyphens. Omitted IDs are generated.

Names are limited to 255 characters, group labels to 80, groups to 30 and each group to 100 widgets. Widget settings use the same sanitisation as the UI. Unknown command fields and unknown structured layout fields are rejected.

Reads return id, name, view, view_layouts, sort_order, version and the sanitised layout. Updates require expected_version from the last read. The entire update is atomic; a stale version returns 422 without changing any fields. Omitted update fields remain unchanged. Explicit null resets view_layouts to defaults; other required fields reject null. At least one personal dashboard must remain after deletion.

Board and share lists accept per_page (1–100, default 25) and cursor. Pagination metadata contains per_page, next_cursor and prev_cursor.

Widget catalogue and data

GET /api/v1/dashboard-widgets returns the fixed, permission-filtered catalogue without pagination metadata. Snapshot widgets retain their semantic settings, including the activity heatmap’s range=me personal scope. Each definition describes its renderer, sizes, ranges, comparisons and default settings.

GET /api/v1/dashboard-widgets/{key}/data?from=2026-11-01&to=2026-11-30 returns the renderer payload through the same provider and cache path as the UI, including its computed_at timestamp. Dates are inclusive viewer-local dates; the window must span at most 92 days. An optional warehouse narrows the caller's accessible warehouses. An inaccessible warehouse produces an empty scope.

Range-aware widgets use that window. Snapshot and personal widgets retain their normal scope. Optional settings[...] are sanitised by the registered definition. Numeric settings use whole decimal integers, for example settings[limit]=5 or settings[threshold]=95. Boolean settings accept true, false, 1 and 0, for example settings[pending_only]=false. Query values are converted only when the definition accepts that setting and type; invalid, out-of-range or undefined settings are omitted. Date settings and range locking are controlled by from and to. Widget reads never grant the source permissions needed to inspect their data or follow links. URL-encode catalogue keys in the path, including plugin package slashes: for plugin:acme/notify:signals.stat-card, use /api/v1/dashboard-widgets/plugin%3Aacme%2Fnotify%3Asignals.stat-card/data. Unknown widget keys return 404; unavailable widgets return 403.

Dashboard shares and published snapshots

MethodURLSummaryAbilityWeight
GET/api/v1/dashboard-sharesIndex dashboard sharesdashboards:read1
POST/api/v1/dashboard-sharesStore dashboard sharesdashboards:write3
GET/api/v1/dashboard-shares/{dashboardShare}Show dashboard sharesdashboards:read1
PUT/api/v1/dashboard-shares/{dashboardShare}Update dashboard sharesdashboards:write3
DELETE/api/v1/dashboard-shares/{dashboardShare}Destroy dashboard sharesdashboards:write3

Publish with name, layout and role_ids and/or user_ids. At least one target is required. Targets must satisfy the same role hierarchy and active-user rules as the dashboard UI. Administrators receive role_ids and user_ids in share responses; recipient responses omit those audience identifiers. A share is a read-only snapshot; editing the author's personal board does not change it.

PATCH preserves omitted name, type, layouts and audience. Supplying either audience array replaces the complete audience, including the other array; send both arrays to retain both kinds of target. Explicit null resets view_layouts; other required fields and an empty replacement audience reject null or empty values. Publication, republishing and unpublishing emit audited events through the existing actions.

MCP

The full discovery profile exposes list-dashboard-widgets, get-dashboard-widget-data, list-dashboards, get-dashboard, create-dashboard, update-dashboard, delete-dashboard, list-dashboard-shares, get-dashboard-share, publish-dashboard-share, update-dashboard-share and delete-dashboard-share. Each invokes its matching REST operation with the same validation, permissions and response envelope. Deletion tools require confirm=true. Read-only mode omits mutation tools. whoami includes registered tool names in mcp.tools and contract fingerprints.

Code-defined report boards remain separate: GET /api/v1/report-boards returns a fixed catalogue without pagination metadata; POST /api/v1/report-boards/{board}/run runs its permitted tiles.

Dashboard types

Saved dashboards and shares have an application type (view): briefing, command or board. Briefing and command dashboards can be saved, shared and customised in the web UI alongside widget boards. Existing dashboards default to board.

REST accepts and returns view and view_layouts. Omit view on creation to use board, or select briefing or command. view_layouts maps either of those two types to its card order and hidden lists. Unknown types and structured keys are rejected. Card IDs are sanitised using the UI rules: unknown IDs are removed and duplicates collapse. Null or an empty object restores default compositions; omitting the field on PATCH preserves the saved compositions.

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

{"name":"Dispatch","view":"briefing","view_layouts":{"briefing":{"order":["statement","attention"],"hidden":["revenue-trend"]}}}

Reads include the saved type and compositions alongside the widget layout. Shares capture only the selected type's composition, and each recipient's permissions still determine which cards are visible. The organisation's settings/dashboard.default_view remains a separate default-view setting. See organisation view defaults.