API: Dashboards

Manage dashboards and their cards, bookmarks, and comments. All endpoints require authentication unless noted. 45 endpoints.

`POST /api/comments`

Create a comment

Request body (JSON)

Field	Type	Required
`resourceType`	string	yes
`resourceId`	string	yes
`content`	string	yes
`parentId`	string	no
`context`	object	no
`mentions`	array of string	no

Responses: 201 · 400 · 401 · 409

`PUT /api/comments/{id}`

Update a comment

Path parameters

Name	Type	Required	Description
`id`	string	yes

Request body (JSON)

Field	Type	Required	Description
`content`	string	yes

Responses: 200 · 400 · 401 · 404

`DELETE /api/comments/{id}`

Delete a comment

Path parameters

Name	Type	Required	Description
`id`	string	yes

Responses: 204 — No content · 401 · 404

`GET /api/comments/{resourceType}/{resourceId}`

List comments for a resource

Path parameters

Name	Type	Required	Description
`resourceType`	string	yes
`resourceId`	string	yes

Query parameters

Name	Type	Required	Description
`limit`	integer	no
`offset`	integer	no

Responses: 200 · 400 · 401

`GET /api/dashboards`

List dashboards (optionally filtered by stage)

Query parameters

Name	Type	Required
`includeDeleted`	boolean	no
`stage`	string	no
`publishedOnly`	boolean	no
`limit`	integer	no
`offset`	integer	no
`include`	`"viewerMeta"`	no

Responses: 200 · 400 · 401

`POST /api/dashboards`

Create a new dashboard

Request body (JSON)

Field	Type	Required
`name`	string	yes
`description`	string	no
`layout`	string	no
`theme`	string	no

Responses: 201 · 400 · 401 · 409

`GET /api/dashboards/{id}`

Get dashboard by ID

Path parameters

Name	Type	Required	Description
`id`	string	yes

Responses: 200 · 400 · 401 · 404

`PUT /api/dashboards/{id}`

Update a dashboard

Path parameters

Name	Type	Required	Description
`id`	string	yes

Request body (JSON)

Field	Type	Required
`name`	string	no
`description`	string	no
`layout`	string	no
`theme`	string	no
`filterState`	string	no
`isPublished`	boolean	no

Responses: 200 · 400 · 401 · 404

`DELETE /api/dashboards/{id}`

Delete a dashboard (soft delete)

Path parameters

Name	Type	Required	Description
`id`	string	yes

Responses: 204 — No content · 401 · 404

`GET /api/dashboards/{id}/access`

List per-user access grants for a dashboard

Path parameters

Name	Type	Required	Description
`id`	string	yes

Responses: 200 · 400 · 401

`POST /api/dashboards/{id}/access`

Grant a workspace member access to a dashboard

Path parameters

Name	Type	Required	Description
`id`	string	yes

Request body (JSON)

Field	Type	Required	Description
`email`	string	yes
`permission`	`"viewer"` \| `"editor"`	yes

Responses: 201 · 400 · 401 · 409

`DELETE /api/dashboards/{id}/access/{accessId}`

Revoke a dashboard access grant

Path parameters

Name	Type	Required	Description
`id`	string	yes
`accessId`	string	yes

Responses: 204 — No content · 401 · 404

`GET /api/dashboards/{id}/access/candidates`

Search workspace members to share a dashboard with

Path parameters

Name	Type	Required	Description
`id`	string	yes

Query parameters

Name	Type	Required	Description
`q`	string	no

Responses: 200 · 400 · 401

`GET /api/dashboards/{id}/bookmarks`

List bookmarks for a dashboard

Path parameters

Name	Type	Required	Description
`id`	string	yes

Responses: 200 · 400 · 401

`POST /api/dashboards/{id}/bookmarks`

Create a dashboard bookmark

Path parameters

Name	Type	Required	Description
`id`	string	yes

Request body (JSON)

Field	Type	Required
`name`	string	yes
`state`	object	yes
`isDefault`	boolean	no
`isPersonal`	boolean	no

Responses: 201 · 400 · 401 · 409

`GET /api/dashboards/{id}/cards`

List cards in a dashboard

Path parameters

Name	Type	Required	Description
`id`	string	yes

Query parameters

Name	Type	Required	Description
`pageId`	string	no

Responses: 200 · 400 · 401

`POST /api/dashboards/{id}/cards`

Add a card to a dashboard

Path parameters

Name	Type	Required	Description
`id`	string	yes

Request body (JSON)

Field	Type	Required
`id`	string	no
`cardType`	string	yes
`title`	string	no
`description`	string	no
`position`	object	yes
`chartSpec`	object	no
`savedQueryId`	string	no
`textContent`	string	no
`imageUrl`	string	no
`value`	string	no
`pageId`	string	no

Responses: 201 · 400 · 401 · 409

`PUT /api/dashboards/{id}/cards/{cardId}`

Update a dashboard card

Path parameters

Name	Type	Required	Description
`id`	string	yes
`cardId`	string	yes

Request body (JSON)

Field	Type	Required
`cardType`	string	no
`title`	string	no
`description`	string	no
`position`	object	no
`chartSpec`	object	no
`savedQueryId`	string,null	no
`textContent`	string	no
`imageUrl`	string	no
`value`	string	no
`ordinal`	integer	no
`pageId`	string	no

Responses: 200 · 400 · 401 · 404

`DELETE /api/dashboards/{id}/cards/{cardId}`

Delete a dashboard card

Path parameters

Name	Type	Required	Description
`id`	string	yes
`cardId`	string	yes

Responses: 204 — No content · 401 · 404

`POST /api/dashboards/{id}/cards/{cardId}/summarize`

Generate and persist an AI summary of a card’s data (AIX-12)

Runs the card’s model-backed spec through the governed pipeline (row-capped at 50), phrases a 2-4 sentence summary via the cosmos aux model, and stores it in dashboard_cards.ai_narrative. 503 AI_NOT_CONFIGURED when no AI provider is configured; fail-closed RLS gate on the card’s source as on card-data.

Path parameters

Name	Type	Required	Description
`id`	string	yes
`cardId`	string	yes

Responses: 200 · 400 · 401 · 403 · 404 · 502 · 503

`DELETE /api/dashboards/{id}/cards/{cardId}/summarize`

Clear a card’s AI summary (AIX-12)

Path parameters

Name	Type	Required	Description
`id`	string	yes
`cardId`	string	yes

Responses: 204 — No content · 401 · 404

`PUT /api/dashboards/{id}/cards/batch`

Batch-update dashboard cards (layout/spec) in one request

Path parameters

Name	Type	Required	Description
`id`	string	yes

Request body (JSON)

Field	Type	Required	Description
`updates`	array of object	yes

Responses: 200 · 400 · 401 · 404

`POST /api/dashboards/{id}/cards/from-query`

Create a card from a saved query

Path parameters

Name	Type	Required	Description
`id`	string	yes

Request body (JSON)

Field	Type	Required
`savedQueryId`	string	yes
`title`	string	no
`position`	object	no
`pageId`	string	no

Responses: 201 · 400 · 401 · 409

`PUT /api/dashboards/{id}/cards/reorder`

Reorder dashboard cards

Path parameters

Name	Type	Required	Description
`id`	string	yes

Request body (JSON)

Field	Type	Required	Description
`cardIds`	array of string	yes

Responses: 200 · 400 · 401 · 404

`POST /api/dashboards/{id}/duplicate`

Duplicate a dashboard with its pages, cards and filters

Path parameters

Name	Type	Required	Description
`id`	string	yes

Responses: 201 · 400 · 401 · 409

`POST /api/dashboards/{id}/export`

Export the dashboard as a file (server-rendered)

Path parameters

Name	Type	Required	Description
`id`	string	yes

Request body (JSON)

Field	Type	Required	Description
`format`	`"pdf"` \| `"csv"` \| `"xlsx"` \| `"pptx"` \| `"docx"`	no

Responses: 200

`GET /api/dashboards/{id}/filters`

List filters for a dashboard

Path parameters

Name	Type	Required	Description
`id`	string	yes

Responses: 200 · 400 · 401

`POST /api/dashboards/{id}/filters`

Add a filter to a dashboard

Path parameters

Name	Type	Required	Description
`id`	string	yes

Request body (JSON)

Field	Type	Required
`fieldId`	string	yes
`filterType`	string	yes
`label`	string	no
`defaultValue`	string	no
`linkedCardIds`	array of string	no

Responses: 201 · 400 · 401 · 409

`PUT /api/dashboards/{id}/filters/{filterId}`

Update a dashboard filter

Path parameters

Name	Type	Required	Description
`id`	string	yes
`filterId`	string	yes

Request body (JSON)

Field	Type	Required
`fieldId`	string	no
`filterType`	string	no
`label`	string	no
`defaultValue`	string	no
`linkedCardIds`	array of string	no
`ordinal`	integer	no

Responses: 200 · 400 · 401 · 404

`DELETE /api/dashboards/{id}/filters/{filterId}`

Delete a dashboard filter

Path parameters

Name	Type	Required	Description
`id`	string	yes
`filterId`	string	yes

Responses: 204 — No content · 401 · 404

`GET /api/dashboards/{id}/pages`

List pages in a dashboard

Path parameters

Name	Type	Required	Description
`id`	string	yes

Responses: 200 · 400 · 401

`POST /api/dashboards/{id}/pages`

Create a dashboard page

Path parameters

Name	Type	Required	Description
`id`	string	yes

Request body (JSON)

Field	Type	Required
`id`	string	no
`name`	string	yes
`pageIndex`	integer	no
`isHidden`	boolean	no

Responses: 201 · 400 · 401 · 409

`PUT /api/dashboards/{id}/pages/{pageId}`

Update a dashboard page

Path parameters

Name	Type	Required	Description
`id`	string	yes
`pageId`	string	yes

Request body (JSON)

Field	Type	Required
`name`	string	no
`pageIndex`	integer	no
`isHidden`	boolean	no

Responses: 204 — No content · 401 · 404

`DELETE /api/dashboards/{id}/pages/{pageId}`

Delete a dashboard page

Path parameters

Name	Type	Required	Description
`id`	string	yes
`pageId`	string	yes

Responses: 204 — No content · 401 · 404

`POST /api/dashboards/{id}/pages/reorder`

Reorder dashboard pages

Path parameters

Name	Type	Required	Description
`id`	string	yes

Request body (JSON)

Field	Type	Required	Description
`pageIds`	array of string	yes

Responses: 204 — No content · 401 · 404

`POST /api/dashboards/{id}/publish`

Publish a dashboard version (snapshot current state)

Path parameters

Name	Type	Required	Description
`id`	string	yes

Request body (JSON)

Field	Type	Required
`changeNote`	string	no
`override`	boolean	no
`overrideReason`	string	no

Responses: 200 · 400 · 401 · 404

`GET /api/dashboards/{id}/schedules`

List dashboard delivery schedules

Path parameters

Name	Type	Required	Description
`id`	string	yes

Responses: 200 · 400 · 401

`POST /api/dashboards/{id}/schedules`

Create a dashboard delivery schedule

Path parameters

Name	Type	Required	Description
`id`	string	yes

Request body (JSON)

Field	Type	Required
`name`	string	yes
`cronExpression`	string	yes
`format`	`"pdf"` \| `"csv"` \| `"xlsx"` \| `"pptx"` \| `"docx"`	no
`recipients`	array of string	no
`timezone`	string	no
`isActive`	boolean	no

Responses: 201 · 400 · 401 · 409

`PUT /api/dashboards/{id}/schedules/{scheduleId}`

Update a dashboard delivery schedule

Path parameters

Name	Type	Required	Description
`id`	string	yes
`scheduleId`	string	yes

Request body (JSON)

Field	Type	Required
`name`	string	no
`cronExpression`	string	no
`format`	`"pdf"` \| `"csv"` \| `"xlsx"` \| `"pptx"` \| `"docx"`	no
`recipients`	array of string	no
`timezone`	string	no
`isActive`	boolean	no

Responses: 200 · 400 · 401 · 404

`DELETE /api/dashboards/{id}/schedules/{scheduleId}`

Delete a dashboard delivery schedule

Path parameters

Name	Type	Required	Description
`id`	string	yes
`scheduleId`	string	yes

Responses: 200

`GET /api/dashboards/{id}/schedules/{scheduleId}/runs`

Delivery run history for a dashboard schedule

Path parameters

Name	Type	Required	Description
`id`	string	yes
`scheduleId`	string	yes

Responses: 200 · 400 · 401

`PUT /api/dashboards/bookmarks/{bookmarkId}`

Update a dashboard bookmark

Path parameters

Name	Type	Required	Description
`bookmarkId`	string	yes

Request body (JSON)

Field	Type	Required
`name`	string	no
`state`	object	no
`isDefault`	boolean	no
`isPersonal`	boolean	no

Responses: 200 · 400 · 401 · 404

`DELETE /api/dashboards/bookmarks/{bookmarkId}`

Delete a dashboard bookmark

Path parameters

Name	Type	Required	Description
`bookmarkId`	string	yes

Responses: 204 — No content · 401 · 404

`POST /api/dashboards/bulk-delete`

Delete multiple dashboards in bulk (soft delete)

Request body (JSON)

Field	Type	Required	Description
`ids`	array of string	yes

Responses: 200 · 400 · 401 · 404

`GET /api/dashboards/page`

List dashboards with authoritative totals and stable cursor pagination

Shared means an explicit active dashboard access grant received by the caller, directly or through a workspace group. Ownership, workspace visibility, public links and embeds are excluded.

Query parameters

Name	Type	Required
`includeDeleted`	boolean	no
`stage`	string	no
`publishedOnly`	boolean	no
`limit`	integer	no
`cursor`	string	no
`scope`	`"all"` \| `"shared"`	no
`include`	`"viewerMeta"`	no

Responses: 200 · 400 · 401 · 404