Reference
Dashboards
The dashboards endpoints of the HTTP API.
GET /dashboards
List the dashboards the caller can see, most recently updated first or grouped by folder.
Filters combine with AND; total_count counts all matches regardless of the cursor. Dashboards in folders the caller cannot see are never listed or counted. A cursor only works with the order it came from; a cursor from the other order is a 400. next_cursor is also set on an offset page and continues after its last row.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
limit |
query | integer |
Between 1 and 200. Default 50. |
cursor |
query | string |
|
offset |
query | integer |
Skip this many dashboards, for numbered pages; counted in the same order and over the same visible, filtered dashboards as total_count. Cannot be combined with cursor (400). Between 0 and 100000. Default 0. |
made_by |
query | string |
Who made the dashboard: me (the caller), user:<uuid>, service_account:<uuid>, agent (saved by the agent), mcp (any MCP client) or mcp:<client> (one MCP client by name). |
datasource |
query | string |
A datasource uid; only dashboards whose latest version uses it. |
q |
query | string |
Case-insensitive text found in the title or the description; leading and trailing whitespace is ignored and a value of only whitespace is rejected. |
folder |
query | string (uuid) |
Only dashboards in this folder; a folder that does not exist or that the caller cannot see gives an empty page, not an error. |
order |
query | "updated", "folder" |
updated (default) sorts by most recent update. folder sorts General last and the other folders by lower-case title, then folder id, and by most recent update inside a folder. Default "updated". |
tag |
query | array of string |
Only dashboards with every given tag. At most 10 items. |
Responses
| Status | Description | Body |
|---|---|---|
200 |
One page of dashboards. | object |
400 |
The request is malformed or fails validation. | Error |
401 |
Authentication is missing or invalid. | Error |
403 |
The caller is not allowed to perform the request; a role that is too low is code forbidden_role. |
Error |
500 |
The server failed to handle the request. | Error |
POST /dashboards
Create a dashboard from a Spec, validating it and running every panel query.
Request body
application/json, required.
| Field | Type | Description |
|---|---|---|
spec (required) |
object |
The ObserveSpec document. |
summary |
string |
A blank or missing summary uses the default Create dashboard. |
folder_id |
string (uuid) |
The folder to create the dashboard in. Missing means the caller’s last used folder they can still create in, else General. 404 when the folder does not exist or the caller cannot see it, 403 when they cannot create there. |
Responses
| Status | Description | Body |
|---|---|---|
201 |
The dashboard and its first version. | DashboardWithVersion |
400 |
The request is malformed or fails validation. | Error |
401 |
Authentication is missing or invalid. | Error |
403 |
The caller is not allowed to perform the request; a role that is too low is code forbidden_role. |
Error |
404 |
The resource does not exist. | Error |
413 |
The request body exceeds the size limit. | Error |
422 |
The Spec fails validation or one of its queries fails; every problem is listed in issues. |
ValidationError |
500 |
The server failed to handle the request. | Error |
GET /dashboards/tags
List every dashboard tag with its dashboard count, by tag name.
Responses
| Status | Description | Body |
|---|---|---|
200 |
Every tag in use, at most 500, ordered by name. | object |
401 |
Authentication is missing or invalid. | Error |
403 |
The caller is not allowed to perform the request; a role that is too low is code forbidden_role. |
Error |
500 |
The server failed to handle the request. | Error |
GET /dashboards/{id}
Get a dashboard with its latest version.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
id (required) |
path | string (uuid) |
Responses
| Status | Description | Body |
|---|---|---|
200 |
The dashboard and its latest version. | DashboardWithVersion |
400 |
The request is malformed or fails validation. | Error |
401 |
Authentication is missing or invalid. | Error |
403 |
The caller is not allowed to perform the request; a role that is too low is code forbidden_role. |
Error |
404 |
The resource does not exist. | Error |
500 |
The server failed to handle the request. | Error |
PATCH /dashboards/{id}
Move a dashboard to another folder.
Needs Edit on the dashboard and on the target folder. A move creates no version, does not change updated_at and sends no event.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
id (required) |
path | string (uuid) |
Request body
application/json, required.
| Field | Type | Description |
|---|---|---|
folder_id (required) |
string (uuid) |
Responses
| Status | Description | Body |
|---|---|---|
200 |
The dashboard in its new folder with its latest version. | DashboardWithVersion |
400 |
The request is malformed or fails validation. | Error |
401 |
Authentication is missing or invalid. | Error |
403 |
The caller is not allowed to perform the request; a role that is too low is code forbidden_role. |
Error |
404 |
The resource does not exist. | Error |
500 |
The server failed to handle the request. | Error |
DELETE /dashboards/{id}
Delete a dashboard with every version, comment, agent request and import record.
Needs Edit on the dashboard. The delete cannot be undone. Open event streams receive dashboard.deleted and then end. While the /observe chat that created the dashboard is still queued or running, the delete is refused.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
id (required) |
path | string (uuid) |
Responses
| Status | Description | Body |
|---|---|---|
204 |
The dashboard and everything that belongs to it are deleted. | |
400 |
The request is malformed or fails validation. | Error |
401 |
Authentication is missing or invalid. | Error |
403 |
The caller is not allowed to perform the request; a role that is too low is code forbidden_role. |
Error |
404 |
The resource does not exist. | Error |
409 |
The agent is still creating this dashboard (dashboard_being_created). |
Error |
500 |
The server failed to handle the request. | Error |
GET /dashboards/{id}/versions
List the versions of a dashboard without their Specs, newest first.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
id (required) |
path | string (uuid) |
|
limit |
query | integer |
Between 1 and 200. Default 50. |
cursor |
query | string |
Responses
| Status | Description | Body |
|---|---|---|
200 |
One page of version metadata. | object |
400 |
The request is malformed or fails validation. | Error |
401 |
Authentication is missing or invalid. | Error |
403 |
The caller is not allowed to perform the request; a role that is too low is code forbidden_role. |
Error |
404 |
The resource does not exist. | Error |
500 |
The server failed to handle the request. | Error |
POST /dashboards/{id}/versions
Save a new version on top of the version the caller last saw, validating the Spec and running every panel query.
A request whose parent version is no longer the latest answers 409, unless it repeats the latest version exactly (same parent, author and Spec), in which case it answers 200 with Idempotent-Replay: true. A failing panel or variable does not fail the save when the parent version lists it in unverified and its queries (every field, with the datasource each query uses) and every variable they reach are unchanged; the new version lists it again with the new issues. Any other failing query is a 422 invalid_spec that lists only the blocking issues.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
id (required) |
path | string (uuid) |
Request body
application/json, required.
| Field | Type | Description |
|---|---|---|
spec (required) |
object |
The ObserveSpec document. |
summary (required) |
string |
|
parent_version (required) |
integer |
Between 1 and 2147483647. |
Responses
| Status | Description | Body |
|---|---|---|
200 |
The request repeats the latest version, so that version is returned. | DashboardWithVersion |
201 |
The new version. | DashboardWithVersion |
400 |
The request is malformed or fails validation. | Error |
401 |
Authentication is missing or invalid. | Error |
403 |
The caller is not allowed to perform the request; a role that is too low is code forbidden_role. |
Error |
404 |
The resource does not exist. | Error |
409 |
The parent version is no longer the latest; latest_version names the current one. |
VersionConflict |
413 |
The request body exceeds the size limit. | Error |
422 |
The Spec fails validation or one of its queries fails; every problem is listed in issues. |
ValidationError |
500 |
The server failed to handle the request. | Error |
GET /dashboards/{id}/versions/{version}
Get one version of a dashboard with its Spec.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
id (required) |
path | string (uuid) |
|
version (required) |
path | integer |
Between 1 and 2147483647. |
Responses
| Status | Description | Body |
|---|---|---|
200 |
The dashboard summary and the requested version. | DashboardWithVersion |
400 |
The request is malformed or fails validation. | Error |
401 |
Authentication is missing or invalid. | Error |
403 |
The caller is not allowed to perform the request; a role that is too low is code forbidden_role. |
Error |
404 |
The resource does not exist. | Error |
500 |
The server failed to handle the request. | Error |
POST /dashboards/{id}/versions/{version}/restore
Save a copy of an earlier version as a new version.
The stored Spec is parsed again and its datasource references are checked, but its queries are not run, so restoring a known-good state does not fail because an upstream is briefly down. The new version copies the restored version’s unverified list.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
id (required) |
path | string (uuid) |
|
version (required) |
path | integer |
Between 1 and 2147483647. |
Request body
application/json, required.
| Field | Type | Description |
|---|---|---|
parent_version (required) |
integer |
Between 1 and 2147483647. |
summary |
string |
A blank or missing summary uses the default Restore version {version}. |
Responses
| Status | Description | Body |
|---|---|---|
201 |
The new version, with restored_from naming the restored one. |
DashboardWithVersion |
400 |
The request is malformed or fails validation. | Error |
401 |
Authentication is missing or invalid. | Error |
403 |
The caller is not allowed to perform the request; a role that is too low is code forbidden_role. |
Error |
404 |
The resource does not exist. | Error |
409 |
The parent version is no longer the latest; latest_version names the current one. |
VersionConflict |
413 |
The request body exceeds the size limit. | Error |
422 |
The Spec fails validation or one of its queries fails; every problem is listed in issues. |
ValidationError |
500 |
The server failed to handle the request. | Error |
POST /dashboards/{id}/duplicate
Save the latest version as version 1 of a new dashboard.
Needs View on the dashboard and Create in the target folder. The copy keeps every Spec field except title, and the source version’s unverified list. Its datasource references are checked but its queries are not run, as for a restore, so duplicating does not fail because an upstream is briefly down. Versions, comments, agent requests and the import record stay with the original.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
id (required) |
path | string (uuid) |
Request body
application/json, required.
| Field | Type | Description |
|---|---|---|
title (required) |
string |
The copy’s title; it must pass the same rules as a Spec title. |
folder_id |
string (uuid) |
The folder to create the dashboard in. Missing means the caller’s last used folder they can still create in, else General. 404 when the folder does not exist or the caller cannot see it, 403 when they cannot create there. |
Responses
| Status | Description | Body |
|---|---|---|
201 |
The new dashboard and its first version. | DashboardWithVersion |
400 |
The request is malformed or fails validation. | Error |
401 |
Authentication is missing or invalid. | Error |
403 |
The caller is not allowed to perform the request; a role that is too low is code forbidden_role. |
Error |
404 |
The resource does not exist. | Error |
413 |
The request body exceeds the size limit. | Error |
422 |
The Spec fails validation or one of its queries fails; every problem is listed in issues. |
ValidationError |
500 |
The server failed to handle the request. | Error |
GET /dashboards/{id}/diff
List the structural changes between two versions of a dashboard.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
id (required) |
path | string (uuid) |
|
from |
query | integer |
Defaults to to minus one. 0 diffs against an empty document, which yields a single add change at the root path "" whose to is the whole Spec. Between 0 and 2147483647. |
to |
query | integer |
Defaults to the latest version. Between 1 and 2147483647. |
Responses
| Status | Description | Body |
|---|---|---|
200 |
The changes from from to to. |
object |
400 |
The request is malformed or fails validation. | Error |
401 |
Authentication is missing or invalid. | Error |
403 |
The caller is not allowed to perform the request; a role that is too low is code forbidden_role. |
Error |
404 |
The resource does not exist. | Error |
500 |
The server failed to handle the request. | Error |
Generated from api/openapi.yaml at bac0fe39. Report a problem.