Reference
Comments
The comments endpoints of the HTTP API.
GET /dashboards/{id}/comments
List the comments of a dashboard across all versions, oldest first.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
id (required) |
path | string (uuid) |
|
status |
query | "open", "resolved", "all" |
Default "all". |
panel_id |
query | string |
|
limit |
query | integer |
Between 1 and 500. Default 100. |
cursor |
query | string |
Responses
| Status | Description | Body |
|---|---|---|
200 |
One page of comments. | 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}/comments
Comment on a panel or the whole dashboard, or reply to a thread.
A comment starts a thread or replies to one. A thread’s first comment is anchored to a version and to a panel id, or to the whole dashboard when panel_id is absent or null, and never moves; panel_present on responses says whether the latest version still has that panel and is always true for a whole-dashboard comment. A reply names its thread’s comment in parent_id and omits version and panel_id; it takes both from its thread. Replies are one level deep: replying to a reply attaches the new reply to that reply’s thread. A thread’s status lives on its first comment and a reply’s status mirrors it. The body is trimmed first, and the limit of 1 to 4000 characters applies to the trimmed text. Control characters other than newline, carriage return and tab, and the bidirectional override and isolate characters (U+202A to U+202E and U+2066 to U+2069), are refused. A comment.created event with type, dashboard_id, comment_id, status and author, plus panel_id for a comment on a panel and parent_id for a reply, goes to the dashboard’s event stream. A comment queues a revision only when request_revision is true and an LLM provider is configured; a reply never requests a revision. The comment and the revision are created in one transaction, and the comment’s revision holds the queued revision. When the revision succeeds, the server resolves the thread with resolved_by_version set to the saved version, unless it is already resolved. With no LLM provider configured, no revision is queued and revision stays null. At most 5 revisions may be queued or running per dashboard; beyond that the comment is not created.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
id (required) |
path | string (uuid) |
Request body
application/json, required.
| Field | Type | Description |
|---|---|---|
request_revision |
boolean |
Whether to queue an agent revision for the comment, when an agent is configured. A reply cannot request one. Default false. |
version |
integer or null |
Required unless parent_id is set. Between 1 and 2147483647. |
panel_id |
string or null |
The panel to comment on; absent or null means the whole dashboard. Not allowed with parent_id. |
parent_id |
string (uuid) or null |
The comment to reply to. Not allowed with version or panel_id. |
body (required) |
string |
Responses
| Status | Description | Body |
|---|---|---|
201 |
The new comment, open, with the queued revision in revision when one was requested. |
CommentEnvelope |
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 dashboard, the version or the comment named by parent_id does not exist. |
Error |
413 |
The request body exceeds the size limit. | Error |
422 |
The panel id does not exist in that version’s Spec (unknown_panel). |
Error |
429 |
The dashboard already has 5 revisions queued or running (too_many_revisions); the comment is not created. |
Error |
500 |
The server failed to handle the request. | Error |
PATCH /dashboards/{id}/comments/{comment_id}
Resolve or reopen a comment.
Setting the status a comment already has answers 200 with the comment unchanged and sends no event. A real change sends comment.updated with type, dashboard_id, comment_id, status and author (plus panel_id for a comment on a panel), where author is the caller who changed the status or, when an agent request resolves the thread, its requester. Changing a reply changes its thread and returns the thread’s first comment. resolved_by_version names the version that fixed the thread; it must be at least the version the thread is on (400) and at most the dashboard’s latest version (422), it is stored only when the call changes the status to resolved, and reopening clears it.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
id (required) |
path | string (uuid) |
|
comment_id (required) |
path | string (uuid) |
Request body
application/json, required.
| Field | Type | Description |
|---|---|---|
status (required) |
"open", "resolved" |
|
resolved_by_version |
integer |
Between 1 and 2147483647. |
Responses
| Status | Description | Body |
|---|---|---|
200 |
The comment with its current status. | CommentEnvelope |
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 |
resolved_by_version is not a version of this dashboard (unknown_version). |
Error |
500 |
The server failed to handle the request. | Error |
Generated from api/openapi.yaml at bac0fe39. Report a problem.