---
title: "Agent requests"
description: "The agent requests 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.

# Agent requests

## GET /agent

Tell whether an agent is configured and which provider and model it uses.

Clients check this before offering the chat composer. Without a configured LLM provider `available` is false and `provider` and `model` are null.

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `200` | The agent configuration. | [`AgentInfo`](/docs/reference/api/schemas/#agentinfo) |
| `401` | Authentication is missing or invalid. | [`Error`](/docs/reference/api/schemas/#error) |
| `500` | The server failed to handle the request. | [`Error`](/docs/reference/api/schemas/#error) |

## GET /observe

List the caller's own agent requests, newest first.

Only requests the caller made are listed; a user sees their own and a service account its own. `source` narrows the list to new-dashboard requests (`observe`), follow-up prompts (`prompt`) or comment revisions (`comment`). A new-dashboard request that failed has no dashboard and lives only in this list. Progress steps are not included; read `GET /observe/{id}` for them.

### Parameters

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `source` | query | `"observe"`, `"prompt"`, `"comment"` |   |
| `limit` | query | `integer` | Between 1 and 100. Default `20`. |
| `cursor` | query | `string` |   |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `200` | One page of the caller's requests. | `object` |
| `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) |
| `500` | The server failed to handle the request. | [`Error`](/docs/reference/api/schemas/#error) |

## POST /observe

Ask the agent to build a new dashboard, or to revise an existing one with a follow-up prompt.

The request is queued and answers 202 at once; poll `GET /observe/{id}` until the status is `succeeded` or `failed`. Without `dashboard_id` the agent builds a new dashboard (`source` is `observe`); the finished request carries the new `dashboard_id` and `url`. With `dashboard_id` the agent revises that dashboard (`source` is `prompt`), exactly like `POST /dashboards/{id}/revisions`; `base_version` defaults to the dashboard's latest 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 (U+202A to U+202E and U+2066 to U+2069), are refused. A caller may have at most 3 new-dashboard requests queued or running (429 `too_many_requests`), the instance at most 20 (429 `agent_busy`), and a dashboard at most 5 revisions (429 `too_many_revisions`). Without a configured LLM provider the endpoint answers 503 `agent_unavailable`.

### Request body

`application/json`, required.

| Field | Type | Description |
| --- | --- | --- |
| `prompt` (required) | `string` |   |
| `dashboard_id` | `string` (uuid) | The dashboard to revise; omit to build a new dashboard. |
| `base_version` | `integer` | A version that exists on the dashboard; only allowed together with `dashboard_id`. Between 1 and 2147483647. |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `202` | The queued agent request. | [`AgentRequestEnvelope`](/docs/reference/api/schemas/#agentrequestenvelope) |
| `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) |
| `413` | The request body exceeds the size limit. | [`Error`](/docs/reference/api/schemas/#error) |
| `429` | Too many agent requests are queued or running (`too_many_requests` for the caller, `agent_busy` for the instance, `too_many_revisions` for the dashboard). | [`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 /observe/{id}

Read one agent request with its progress steps and usage.

Works for any agent request, including comment and prompt revisions. A request that has no dashboard yet, or never got one, is readable only by the principal that made it; anyone else gets 404. Clients poll it once a second until the status is `succeeded` or `failed`. After a shutdown release the re-claimed run reuses its attempt number with a fresh step list, so a client detects a restarted list by each step's `at`, not by `attempt` alone.

### Parameters

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `id` (required) | path | `string` (uuid) |   |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `200` | The agent request with its current status. | [`AgentRequestEnvelope`](/docs/reference/api/schemas/#agentrequestenvelope) |
| `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) |
| `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).