---
title: "Panel suggestions"
description: "The panel suggestions endpoints of the HTTP API."
---

> Documentation Index
> Fetch the complete documentation index at: https://slashobserve.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Panel suggestions

## 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`](/docs/reference/api/schemas/#suggestionenvelope) |
| `400` | The request is malformed or fails validation. | [`Error`](/docs/reference/api/schemas/#error) |
| `401` | Authentication is missing or invalid. | [`Error`](/docs/reference/api/schemas/#error) |
| `403` | The caller is not allowed to perform the request; a role that is too low is code `forbidden_role`. | [`Error`](/docs/reference/api/schemas/#error) |
| `404` | The dashboard or the version does not exist. | [`Error`](/docs/reference/api/schemas/#error) |
| `413` | The request body exceeds the size limit. | [`Error`](/docs/reference/api/schemas/#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`](/docs/reference/api/schemas/#error) or [`ValidationError`](/docs/reference/api/schemas/#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`](/docs/reference/api/schemas/#error) |
| `500` | The server failed to handle the request. | [`Error`](/docs/reference/api/schemas/#error) |
| `503` | No LLM provider is configured (`agent_unavailable`). | [`Error`](/docs/reference/api/schemas/#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`](/docs/reference/api/schemas/#suggestionenvelope) |
| `400` | The request is malformed or fails validation. | [`Error`](/docs/reference/api/schemas/#error) |
| `401` | Authentication is missing or invalid. | [`Error`](/docs/reference/api/schemas/#error) |
| `403` | The caller is not allowed to perform the request; a role that is too low is code `forbidden_role`. | [`Error`](/docs/reference/api/schemas/#error) |
| `404` | The resource does not exist. | [`Error`](/docs/reference/api/schemas/#error) |
| `500` | The server failed to handle the request. | [`Error`](/docs/reference/api/schemas/#error) |

Generated from [`api/openapi.yaml`](https://github.com/slashobserve/slashobserve/blob/bac0fe39/api/openapi.yaml) at `bac0fe39`. [Report a problem](https://github.com/slashobserve/slashobserve/issues/new).