Reference
Panel suggestions
The panel suggestions endpoints of the HTTP API.
POST /dashboards/{id}/suggestions
Ask the agent to propose a change to one panel without saving anything.
The request is queued and answers 202 at once; the agent proposes one panel and saves nothing, so the dashboard and its versions never change. A suggestion is private to the caller: only the caller can read it, it never appears in revisions, the observe list or the activity timeline, it sends no events, and it is exempt from the one-running-per-dashboard rule, so it neither waits behind nor blocks a revision of the dashboard, but it shares the worker pool and can wait for a free worker. Poll GET /dashboards/{id}/suggestions/{suggestion_id} every second until the status is succeeded or failed. version is the version the proposal is judged inside, and panel_id must be a data, text or dashboard list panel of that version. The prompt 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, are refused. panel is the editor’s current draft of the panel, optional; it is placed into the version at the panel’s position and validated there with the Spec rules before anything is queued, must keep the id panel_id and stay a data, text or dashboard list panel, must not contain the NUL character and may be at most 63 KiB as compact JSON once placed (a request body over 96 KiB is refused). The proposed panel is validated inside the base version with the user’s draft, and its queries run with the save rules before the suggestion succeeds. A caller may have 2 suggestions queued or running and the instance 10. Without a configured LLM provider the endpoint answers 503 agent_unavailable.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
id (required) |
path | string (uuid) |
Request body
application/json, required.
| Field | Type | Description |
|---|---|---|
version (required) |
integer |
A version that exists on the dashboard. Between 1 and 2147483647. |
panel_id (required) |
string |
|
prompt (required) |
string |
|
panel |
object or null |
The editor’s current draft of the panel. Omit it or send null to start from the stored panel. |
Responses
| Status | Description | Body |
|---|---|---|
202 |
The queued suggestion. | SuggestionEnvelope |
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 or the version does not exist. | Error |
413 |
The request body exceeds the size limit. | Error |
422 |
The panel is not a data, text or dashboard list panel of that version (unknown_panel), or the draft fails inside the version (invalid_spec, with issues). |
Error or ValidationError |
429 |
The caller already has 2 suggestions queued or running (too_many_suggestions), or 10 are queued or running across the instance (agent_busy). |
Error |
500 |
The server failed to handle the request. | Error |
503 |
No LLM provider is configured (agent_unavailable). |
Error |
GET /dashboards/{id}/suggestions/{suggestion_id}
Read one panel suggestion.
Only the caller who requested the suggestion can read it; any other caller, a suggestion of another dashboard and an unknown id all answer 404. panel is set only when the status is succeeded and error only when it is failed. Poll every second until the status is succeeded or failed; suggestions send no events.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
id (required) |
path | string (uuid) |
|
suggestion_id (required) |
path | string (uuid) |
Responses
| Status | Description | Body |
|---|---|---|
200 |
The suggestion with its current status and progress steps. | SuggestionEnvelope |
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.