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
| Method | URL | Summary | Ability | Weight |
|---|---|---|---|---|
GET | /api/v1/dashboards | Index dashboards | dashboards:read | 1 |
POST | /api/v1/dashboards | Store dashboards | dashboards:write | 3 |
GET | /api/v1/dashboards/{dashboard} | Show dashboards | dashboards:read | 1 |
PUT | /api/v1/dashboards/{dashboard} | Update dashboards | dashboards:write | 3 |
DELETE | /api/v1/dashboards/{dashboard} | Destroy dashboards | dashboards:write | 3 |
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
| Method | URL | Summary | Ability | Weight |
|---|---|---|---|---|
GET | /api/v1/dashboard-shares | Index dashboard shares | dashboards:read | 1 |
POST | /api/v1/dashboard-shares | Store dashboard shares | dashboards:write | 3 |
GET | /api/v1/dashboard-shares/{dashboardShare} | Show dashboard shares | dashboards:read | 1 |
PUT | /api/v1/dashboard-shares/{dashboardShare} | Update dashboard shares | dashboards:write | 3 |
DELETE | /api/v1/dashboard-shares/{dashboardShare} | Destroy dashboard shares | dashboards:write | 3 |
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.