---
title: "Schemas"
description: "The request and response objects the HTTP API endpoints use."
---

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

# Schemas

## Error

| Field | Type | Description |
| --- | --- | --- |
| `error` (required) | `string` |   |
| `code` (required) | `string` |   |

## Issue

| Field | Type | Description |
| --- | --- | --- |
| `path` (required) | `string` |   |
| `code` (required) | `string` | Spec parsing adds schema and semantic codes such as `schema`, `too_large`, `unknown_unit`, `duplicate_panel_id`, `unknown_variable`, `too_many_panels` (more than 200 panels counting row children), `duplicate_query_ref`, `unknown_query_ref` (an override or an expression names a query ref the panel does not have), `threshold_value_missing` (a threshold other than the first omits its value), `duplicate_element_id` (a canvas panel repeats an element id, path `/panels/{i}/display/elements/{k}/id`) and `unknown_element` (a canvas connection names no element, path `/panels/{i}/display/connections/{k}/from` or `/to`). A `timezone` the server cannot load is `unknown_timezone` (path `/timezone`). Saving a dashboard also runs every panel and variable query and adds `unknown_datasource`, `time_range_invalid` (path `/time`), `variable_failed`, `variable_empty` and `variable_unresolved` (paths `/variables/{i}` or `/panels/{i}/queries/{j}/query`, with `/panels/{i}/panels/{j}` for a row child), and `query_invalid`, `query_forbidden`, `limit_exceeded`, `query_timeout`, `datasource_unavailable`, `not_found`, `query_empty`, `expression_error` and `internal` (paths `/panels/{i}/queries/{j}/query`, `/panels/{i}/queries/{j}/expression` for an expression query, `/panels/{i}/datasource` and `/panels/{i}/queries/{j}/datasource`; `query_empty` is reported once for the panel at `/panels/{i}/queries`, and never for an `alertlist` panel, whose empty result is valid). A query issue on a panel or variable the parent version lists in `unverified` may be kept instead of failing the save; see `POST /dashboards/{id}/versions`. |
| `message` (required) | `string` |   |

## ValidationError

| Field | Type | Description |
| --- | --- | --- |
| `error` (required) | `string` |   |
| `code` (required) | `string` |   |
| `issues` (required) | array of [`Issue`](/docs/reference/api/schemas/#issue) |   |

## Role

One of `admin`, `editor`, `commenter`, `viewer`.

## RoleSource

Where a person's role comes from. admin_emails, first_user and group are decided by the server settings or the identity provider and cannot be changed through the API.

One of `admin_emails`, `first_user`, `group`, `manual`, `default`.

## Principal

| Field | Type | Description |
| --- | --- | --- |
| `kind` (required) | `"user"`, `"service_account"` |   |
| `id` (required) | `string` (uuid) |   |
| `name` (required) | `string` |   |
| `email` | `string` |   |
| `role` (required) | [`Role`](/docs/reference/api/schemas/#role) |   |

## Instance

| Field | Type | Description |
| --- | --- | --- |
| `public_url` (required) | `string` (uri) |   |
| `mcp_url` (required) | `string` (uri) |   |
| `oidc_issuer_url` (required) | `string` | The identity provider's issuer, as browsers reach it. |
| `oidc_provider_name` (required) | `string` | The identity provider's display name, empty when none is configured. |
| `allowed_email_domains` (required) | array of `string` | Empty when any domain may sign in. |
| `any_email_domain` (required) | `boolean` |   |
| `session_ttl_seconds` (required) | `integer` |   |

## SessionState

| Field | Type | Description |
| --- | --- | --- |
| `authenticated` (required) | `boolean` |   |
| `principal` | [`Principal`](/docs/reference/api/schemas/#principal) |   |

## ServiceAccount

| Field | Type | Description |
| --- | --- | --- |
| `id` (required) | `string` (uuid) |   |
| `name` (required) | `string` |   |
| `description` (required) | `string` |   |
| `created_by` (required) | `string` (uuid) or `null` |   |
| `created_at` (required) | `string` (date-time) |   |
| `role` (required) | [`Role`](/docs/reference/api/schemas/#role) |   |

## ServiceAccountList

| Field | Type | Description |
| --- | --- | --- |
| `items` (required) | array of [`ServiceAccount`](/docs/reference/api/schemas/#serviceaccount) |   |

## CreateServiceAccountRequest

| Field | Type | Description |
| --- | --- | --- |
| `name` (required) | `string` |   |
| `description` | `string` |   |
| `role` | [`Role`](/docs/reference/api/schemas/#role) | The role the account's keys act with; editor when omitted. |

## UpdateServiceAccountRequest

| Field | Type | Description |
| --- | --- | --- |
| `role` (required) | [`Role`](/docs/reference/api/schemas/#role) |   |

## ServiceAccountKey

| Field | Type | Description |
| --- | --- | --- |
| `id` (required) | `string` (uuid) |   |
| `service_account_id` (required) | `string` (uuid) |   |
| `name` (required) | `string` |   |
| `display_prefix` (required) | `string` |   |
| `created_by` (required) | `string` (uuid) or `null` |   |
| `created_at` (required) | `string` (date-time) |   |
| `expires_at` (required) | `string` (date-time) or `null` |   |
| `last_used_at` (required) | `string` (date-time) or `null` |   |
| `revoked_at` (required) | `string` (date-time) or `null` |   |

## ServiceAccountKeyList

| Field | Type | Description |
| --- | --- | --- |
| `items` (required) | array of [`ServiceAccountKey`](/docs/reference/api/schemas/#serviceaccountkey) |   |

## CreateServiceAccountKeyRequest

| Field | Type | Description |
| --- | --- | --- |
| `name` (required) | `string` |   |
| `expires_at` | `string` (date-time) or `null` |   |

## IssuedServiceAccountKey

| Field | Type | Description |
| --- | --- | --- |
| `key` (required) | [`ServiceAccountKey`](/docs/reference/api/schemas/#serviceaccountkey) |   |
| `token` (required) | `string` | The full key, returned only once. |

## Person

| Field | Type | Description |
| --- | --- | --- |
| `id` (required) | `string` (uuid) |   |
| `name` (required) | `string` |   |
| `email` (required) | `string` |   |
| `created_at` (required) | `string` (date-time) |   |
| `last_login_at` (required) | `string` (date-time) |   |
| `last_seen_at` (required) | `string` (date-time) | Updated at most once a minute while a session is used; seen within the last 2 minutes means online now. |
| `dashboard_count` (required) | `integer` | Dashboards whose first version this person saved, either directly or through an agent request they sent. Dashboards created with a service-account key are not counted. |
| `key_count` (required) | `integer` | Unrevoked, unexpired service-account keys this person created. |
| `session_count` (required) | `integer` | Unexpired sessions. |
| `role` (required) | [`Role`](/docs/reference/api/schemas/#role) |   |
| `role_source` (required) | [`RoleSource`](/docs/reference/api/schemas/#rolesource) |   |
| `role_group` (required) | `string` or `null` | The identity-provider group that decided the role when role_source is group. |
| `role_set_by` (required) | `string` or `null` | The name of the Admin who chose the role when role_source is manual. |
| `role_locked` (required) | `boolean` | True when the role cannot be changed through the API. |

## UpdatePersonRequest

| Field | Type | Description |
| --- | --- | --- |
| `role` (required) | [`Role`](/docs/reference/api/schemas/#role) or `null` | The role to set, or null to clear the chosen role and fall back to the computed one. |

## OutboundDomain

| Field | Type | Description |
| --- | --- | --- |
| `domain` (required) | `string` | A host name, or `*.` followed by a host name for its subdomains only, in lower case ASCII. |
| `added_at` (required) | `string` (date-time) or `null` | Null for an entry set by `SLASHOBSERVE_OUTBOUND_DOMAINS`. |
| `added_by` (required) | `string` or `null` | The name of the person who allowed the domain; null for an entry set by `SLASHOBSERVE_OUTBOUND_DOMAINS` and when that person was deleted. |

## OutboundDomainList

| Field | Type | Description |
| --- | --- | --- |
| `managed_by` (required) | `"settings"`, `"config"` | `config` when `SLASHOBSERVE_OUTBOUND_DOMAINS` is set; the list is then read-only. |
| `domains` (required) | array of [`OutboundDomain`](/docs/reference/api/schemas/#outbounddomain) |   |

## Permissions

What the caller may do with the object; being able to read it implies viewing.

| Field | Type | Description |
| --- | --- | --- |
| `comment` (required) | `boolean` |   |
| `edit` (required) | `boolean` |   |
| `manage` (required) | `boolean` | Rename, change the permissions of and delete a folder. |
| `create` (required) | `boolean` | Create, duplicate or import dashboards into the folder, or move dashboards into it (the Edit level). |

## FolderLevel

One of `view`, `comment`, `edit`, `admin`.

## Folder

| Field | Type | Description |
| --- | --- | --- |
| `id` (required) | `string` (uuid) |   |
| `title` (required) | `string` |   |
| `general` (required) | `boolean` | True for the General folder, which holds dashboards without a folder of their own and is never restricted, renamed or deleted. |
| `restricted` (required) | `boolean` | True when the folder lists people or groups; false means open to everyone by instance role. |
| `dashboard_count` (required) | `integer` | All dashboards in the folder, including ones the caller cannot see when the caller manages it. |
| `grantees` (required) | array of `string` | The names of up to 5 listed people, then groups. At most 5 items. |
| `grantee_count` (required) | `integer` | How many people and groups are listed. |
| `created_by` (required) | [`Author`](/docs/reference/api/schemas/#author) or `null` | Null for General and for folders made before creators were recorded. |
| `permissions` (required) | [`Permissions`](/docs/reference/api/schemas/#permissions) |   |
| `level` (required) | [`FolderLevel`](/docs/reference/api/schemas/#folderlevel) | The caller's level on this folder and on every dashboard in it, the higher of what their role gives and their highest matching entry. Admins always have `admin`. |

## FolderPermissionEntry

| Field | Type | Description |
| --- | --- | --- |
| `kind` (required) | `"user"`, `"group"` |   |
| `user` | `object` | Present when `kind` is `user`. |
| `group` | `string` | Present when `kind` is `group`. |
| `member_count` | `integer` | Present when `kind` is `group`; people who signed in with the group in their stored claims. |
| `level` (required) | [`FolderLevel`](/docs/reference/api/schemas/#folderlevel) |   |

## FolderPermissions

| Field | Type | Description |
| --- | --- | --- |
| `restricted` (required) | `boolean` |   |
| `entries` (required) | array of [`FolderPermissionEntry`](/docs/reference/api/schemas/#folderpermissionentry) |   |

## SavedPrompt

| Field | Type | Description |
| --- | --- | --- |
| `id` (required) | `string` (uuid) |   |
| `name` (required) | `string` | Unique per owner and among shared prompts, ignoring case. Letters, numbers, spaces, `-` and `_`; it starts and ends with a letter or number, and runs of spaces are stored as one. |
| `body` (required) | `string` | The prompt text sent to the agent, trimmed; at most 4000 characters, the same limit as `POST /observe`. |
| `shared` (required) | `boolean` | True when everyone on the server can see and run it; false when only its owner can. |
| `owner` (required) | [`SavedPromptOwner`](/docs/reference/api/schemas/#savedpromptowner) |   |
| `can_edit` (required) | `boolean` | Whether the caller may change or delete it. The server decides; clients never recompute it. |
| `created_at` (required) | `string` (date-time) |   |
| `updated_at` (required) | `string` (date-time) |   |

## SavedPromptOwner

| Field | Type | Description |
| --- | --- | --- |
| `id` (required) | `string` (uuid) |   |
| `name` (required) | `string` | The owner's display name, or their email when they have no name. |

## SavedPromptList

| Field | Type | Description |
| --- | --- | --- |
| `prompts` (required) | array of [`SavedPrompt`](/docs/reference/api/schemas/#savedprompt) | At most 500 items. |

## NewsItem

| Field | Type | Description |
| --- | --- | --- |
| `title` (required) | `string` | Plain text, never markup. |
| `link` (required) | `string` or `null` | An absolute http or https URL without user info, or null when the feed gave none or an unsafe one. |
| `published` (required) | `string` (date-time) or `null` |   |
| `summary` (required) | `string` | Plain text, never markup; may be empty. |

## ActionResult

| Field | Type | Description |
| --- | --- | --- |
| `status` (required) | `integer` | The HTTP status the remote server answered with; a redirect is reported as its own 3xx status. |
| `ok` (required) | `boolean` | True when the status is 2xx. |

## ActionError

| Field | Type | Description |
| --- | --- | --- |
| `error` (required) | `string` |   |
| `code` (required) | `string` |   |
| `host` | `string` | The domain the request was meant for, present on `outbound_domain_not_allowed` and `action_failed`. |

## NewsFeed

| Field | Type | Description |
| --- | --- | --- |
| `title` (required) | `string` |   |
| `items` (required) | array of [`NewsItem`](/docs/reference/api/schemas/#newsitem) | In feed order, at most 50. At most 50 items. |
| `fetched_at` (required) | `string` (date-time) | When the server fetched the feed; a cached feed keeps the time of its fetch. |

## DatasourceStatus

| Field | Type | Description |
| --- | --- | --- |
| `uid` (required) | `string` |   |
| `type` (required) | `string` |   |
| `name` (required) | `string` |   |
| `healthy` (required) | `boolean` |   |
| `message` | `string` |   |
| `checked_at` (required) | `string` (date-time) | When the server last checked the datasource; checks are cached for 10 seconds. |
| `dashboard_count` (required) | `integer` | Dashboards whose latest version uses this datasource. |

## DatasourceList

| Field | Type | Description |
| --- | --- | --- |
| `datasources` (required) | array of [`DatasourceStatus`](/docs/reference/api/schemas/#datasourcestatus) |   |

## MetricName

| Field | Type | Description |
| --- | --- | --- |
| `name` (required) | `string` |   |
| `type` | `string` |   |
| `help` | `string` |   |
| `unit` | `string` |   |
| `table` | `string` |   |

## Author

| Field | Type | Description |
| --- | --- | --- |
| `kind` (required) | `"user"`, `"service_account"` |   |
| `id` (required) | `string` (uuid) |   |
| `name` (required) | `string` |   |
| `email` | `string` |   |

## Creator

Who made version 1 of the dashboard. It never changes.

| Field | Type | Description |
| --- | --- | --- |
| `author` (required) | [`Author`](/docs/reference/api/schemas/#author) |   |
| `origin` (required) | `"web"`, `"cli"`, `"mcp"`, `"api"` or `null` | Where version 1 came from; null for dashboards created before origins were recorded. A label only, never used for access decisions. |
| `origin_client` (required) | `string` or `null` | The MCP client's name when `origin` is `mcp`, else null. |
| `via` (required) | `"direct"`, `"agent"` | `agent` when the agent saved version 1; `author` is then the person or key that asked. |

## DashboardFolder

| Field | Type | Description |
| --- | --- | --- |
| `id` (required) | `string` (uuid) |   |
| `title` (required) | `string` |   |
| `general` (required) | `boolean` | True for the General folder. |

## DashboardSummary

| Field | Type | Description |
| --- | --- | --- |
| `id` (required) | `string` (uuid) |   |
| `title` (required) | `string` |   |
| `tags` (required) | array of `string` |   |
| `latest_version` (required) | `integer` |   |
| `created_at` (required) | `string` (date-time) |   |
| `updated_at` (required) | `string` (date-time) |   |
| `updated_by` (required) | [`Author`](/docs/reference/api/schemas/#author) |   |
| `creator` (required) | [`Creator`](/docs/reference/api/schemas/#creator) |   |
| `folder` (required) | [`DashboardFolder`](/docs/reference/api/schemas/#dashboardfolder) |   |
| `permissions` (required) | [`Permissions`](/docs/reference/api/schemas/#permissions) |   |

## DashboardListItem

| Field | Type | Description |
| --- | --- | --- |
| `id` (required) | `string` (uuid) |   |
| `title` (required) | `string` |   |
| `description` (required) | `string` or `null` | The latest version's Spec description; null when it has none. |
| `tags` (required) | array of `string` |   |
| `latest_version` (required) | `integer` |   |
| `created_at` (required) | `string` (date-time) |   |
| `updated_at` (required) | `string` (date-time) |   |
| `updated_by` (required) | [`Author`](/docs/reference/api/schemas/#author) |   |
| `creator` (required) | [`Creator`](/docs/reference/api/schemas/#creator) |   |
| `datasource_uids` (required) | array of `string` | The distinct datasource uids the latest version uses, sorted. |
| `open_comment_count` (required) | `integer` | Open comment threads on the dashboard; replies are not counted. |
| `folder` (required) | [`DashboardFolder`](/docs/reference/api/schemas/#dashboardfolder) |   |
| `permissions` (required) | [`Permissions`](/docs/reference/api/schemas/#permissions) |   |

## VersionMeta

| Field | Type | Description |
| --- | --- | --- |
| `version` (required) | `integer` |   |
| `parent_version` (required) | `integer` or `null` |   |
| `restored_from` (required) | `integer` or `null` |   |
| `summary` (required) | `string` |   |
| `author` (required) | [`Author`](/docs/reference/api/schemas/#author) |   |
| `created_at` (required) | `string` (date-time) |   |
| `origin` (required) | `"web"`, `"cli"`, `"mcp"`, `"api"` or `null` | Where the save came from; `web` is a signed-in browser, `cli` the observe CLI, `mcp` an MCP client, `api` any other bearer-key caller. A version saved by the agent records the origin of the request that asked for it. Null for versions saved before origins were recorded. A label only, never used for access decisions. |
| `origin_client` (required) | `string` or `null` | The MCP client's self-reported `clientInfo.name` (for example `claude-code`), only when `origin` is `mcp`; unverified. |
| `agent_request_id` (required) | `string` (uuid) or `null` | The agent request that saved this version; null for a version saved directly. |

## Version

| Field | Type | Description |
| --- | --- | --- |
| `version` (required) | `integer` |   |
| `parent_version` (required) | `integer` or `null` |   |
| `restored_from` (required) | `integer` or `null` |   |
| `summary` (required) | `string` |   |
| `author` (required) | [`Author`](/docs/reference/api/schemas/#author) |   |
| `created_at` (required) | `string` (date-time) |   |
| `origin` (required) | `"web"`, `"cli"`, `"mcp"`, `"api"` or `null` | Where the save came from; `web` is a signed-in browser, `cli` the observe CLI, `mcp` an MCP client, `api` any other bearer-key caller. A version saved by the agent records the origin of the request that asked for it. Null for versions saved before origins were recorded. A label only, never used for access decisions. |
| `origin_client` (required) | `string` or `null` | The MCP client's self-reported `clientInfo.name` (for example `claude-code`), only when `origin` is `mcp`; unverified. |
| `agent_request_id` (required) | `string` (uuid) or `null` | The agent request that saved this version; null for a version saved directly. |
| `spec` (required) | `object` | The ObserveSpec document, validated against its own schema. |
| `unverified` (required) | [`Unverified`](/docs/reference/api/schemas/#unverified) |   |

## Unverified

Panels and variables of this version whose queries failed when it was saved but were kept: a Grafana import keeps every failing panel and variable, and a later save keeps one only while it stays unchanged (see `POST /dashboards/{id}/versions`).

| Field | Type | Description |
| --- | --- | --- |
| `panels` (required) | array of [`UnverifiedPanel`](/docs/reference/api/schemas/#unverifiedpanel) |   |
| `variables` (required) | array of [`UnverifiedVariable`](/docs/reference/api/schemas/#unverifiedvariable) |   |

## UnverifiedPanel

| Field | Type | Description |
| --- | --- | --- |
| `panel_id` (required) | `string` |   |
| `issues` (required) | array of [`Issue`](/docs/reference/api/schemas/#issue) |   |

## UnverifiedVariable

| Field | Type | Description |
| --- | --- | --- |
| `name` (required) | `string` |   |
| `issues` (required) | array of [`Issue`](/docs/reference/api/schemas/#issue) |   |

## DashboardWithVersion

| Field | Type | Description |
| --- | --- | --- |
| `dashboard` (required) | [`DashboardSummary`](/docs/reference/api/schemas/#dashboardsummary) |   |
| `version` (required) | [`Version`](/docs/reference/api/schemas/#version) |   |

## SpecChange

| Field | Type | Description |
| --- | --- | --- |
| `op` (required) | `"add"`, `"remove"`, `"replace"`, `"reorder"` |   |
| `path` (required) | `string` | JSON Pointer into the Spec document; the empty string is the whole document. |
| `from` | any or `null` | The previous JSON value at the path. |
| `to` | any or `null` | The new JSON value at the path. |

## VersionConflict

| Field | Type | Description |
| --- | --- | --- |
| `error` (required) | `string` |   |
| `code` (required) | `string` |   |
| `latest_version` (required) | `integer` |   |

## Comment

| Field | Type | Description |
| --- | --- | --- |
| `id` (required) | `string` (uuid) |   |
| `dashboard_id` (required) | `string` (uuid) |   |
| `parent_id` (required) | `string` (uuid) or `null` | The thread's first comment, for a reply; null for a thread's first comment. |
| `version` (required) | `integer` |   |
| `panel_id` (required) | `string` or `null` | The panel the thread is on; null for the whole dashboard. A reply has its thread's panel. |
| `body` (required) | `string` |   |
| `status` (required) | `"open"`, `"resolved"` | For a reply, the status of its thread. |
| `author` (required) | [`Author`](/docs/reference/api/schemas/#author) |   |
| `created_at` (required) | `string` (date-time) |   |
| `updated_at` (required) | `string` (date-time) |   |
| `resolved_at` (required) | `string` (date-time) or `null` |   |
| `resolved_by` (required) | [`Author`](/docs/reference/api/schemas/#author) or `null` |   |
| `resolved_by_version` (required) | `integer` or `null` | The version that fixed the thread, when the resolver named one. Also set by the server when an agent request sent from the thread succeeds. Always null on a reply. |
| `panel_present` (required) | `boolean` | Whether the latest version of the dashboard still has the panel the comment is anchored to. Always true for a whole-dashboard comment. |
| `revision` (required) | `object` or `null` | The latest revision requested for this comment, or null when none was requested. |

## CommentEnvelope

| Field | Type | Description |
| --- | --- | --- |
| `comment` (required) | [`Comment`](/docs/reference/api/schemas/#comment) |   |

## Field

| Field | Type | Description |
| --- | --- | --- |
| `name` (required) | `string` |   |
| `type` (required) | `"time"`, `"number"`, `"string"`, `"bool"`, `"other"` |   |
| `values` (required) | array of any or `null` | Time fields hold epoch milliseconds as integers, number fields hold numbers with `null` for gaps, and `other` fields hold JSON exactly as the datasource adapter produced it. |

## Frame

| Field | Type | Description |
| --- | --- | --- |
| `ref` (required) | `string` | The ref of the panel query that produced this frame: its written ref, or A, B, C... by position. |
| `name` | `string` |   |
| `labels` | `object` |   |
| `fields` (required) | array of [`Field`](/docs/reference/api/schemas/#field) |   |

## QueryMeta

| Field | Type | Description |
| --- | --- | --- |
| `ref` (required) | `string` |   |
| `kind` (required) | `"range"`, `"instant"` |   |
| `step_ms` (required) | `integer` | The query's resolution; 0 for an instant query. |
| `exemplars` | `"ok"`, `"truncated"`, `"unavailable"`, `"unsupported"` | Present only when the query asked for exemplars (`exemplar: true` on a Prometheus range query, on the panel data and preview routes). `ok` has all of them, `truncated` has the 2,000 newest after thinning to one per step, `unavailable` means the exemplar call failed or timed out and the panel still succeeded, and `unsupported` means the datasource or the query kind has no exemplars. |

## DataMeta

| Field | Type | Description |
| --- | --- | --- |
| `kind` (required) | `"range"`, `"instant"` | range when any visible query runs as a range query, which also decides how from and to are aligned. |
| `from` (required) | `string` (date-time) | The start of the aligned range the query ran over. |
| `to` (required) | `string` (date-time) | The end of the aligned range the query ran over. |
| `step_ms` (required) | `integer` | The panel's resolution; 0 for an instant panel. |
| `queries` (required) | array of [`QueryMeta`](/docs/reference/api/schemas/#querymeta) | Every query that ran, in panel order; hidden queries do not run. |
| `cached` (required) | `boolean` | True when the response was served from the proxy's response cache instead of running the query. |
| `executed_at` (required) | `string` (date-time) | When the query ran upstream, which for a cached response is earlier than the request. |
| `source_panel` | `string` | The id of the panel whose queries ran, present only when the requested panel reuses another panel's results; the frames, queries and range are that panel's, and its transforms apply first when the reusing query sets withTransforms. |

## PanelDataError

| Field | Type | Description |
| --- | --- | --- |
| `error` (required) | `string` |   |
| `code` (required) | `string` |   |
| `ref` | `string` | The query that failed, when one query's run failed. |

## PanelData

| Field | Type | Description |
| --- | --- | --- |
| `frames` (required) | array of [`Frame`](/docs/reference/api/schemas/#frame) |   |
| `exemplars` | array of [`Frame`](/docs/reference/api/schemas/#frame) | Present only when at least one query asked for exemplars, and then possibly empty. Each frame is one series' exemplars, its `ref` naming the query and its `labels` the series labels; the fields are `Time` (epoch milliseconds), `Value`, then one string field per exemplar label key. |
| `meta` (required) | [`DataMeta`](/docs/reference/api/schemas/#datameta) |   |

## VariableValues

| Field | Type | Description |
| --- | --- | --- |
| `values` (required) | array of `string` | The values a selection may hold. |
| `texts` | array of `string` | The display text of each value, same length and order as values; present only when some text differs from its value. |
| `truncated` (required) | `boolean` |   |
| `cached` (required) | `boolean` | True when the list was served from the proxy's response cache instead of running the query. |

## Diagnostic

| Field | Type | Description |
| --- | --- | --- |
| `severity` (required) | `"error"`, `"warning"` |   |
| `message` (required) | `string` |   |
| `start` (required) | `integer` | Byte offset of the first byte the diagnostic covers. |
| `end` (required) | `integer` | Byte offset just past the last byte the diagnostic covers. |

## LintResult

| Field | Type | Description |
| --- | --- | --- |
| `diagnostics` (required) | array of [`Diagnostic`](/docs/reference/api/schemas/#diagnostic) |   |

## Revision

| Field | Type | Description |
| --- | --- | --- |
| `id` (required) | `string` (uuid) |   |
| `dashboard_id` (required) | `string` (uuid) |   |
| `source` (required) | `"comment"`, `"prompt"`, `"observe"` | `observe` is the new-dashboard request that created the dashboard; it appears once it has succeeded. |
| `comment_id` (required) | `string` (uuid) or `null` | The comment that requested the revision; null for a prompt, or after the comment was deleted. |
| `panel_id` (required) | `string` or `null` | The panel the request is about (a comment's panel, or the panel a prompt was sent from); null for the whole dashboard. |
| `prompt` (required) | `string` | The follow-up text, or the comment body. |
| `base_version` (required) | `integer` or `null` | The version the requester was looking at; null for the `observe` request that created the dashboard. The agent revises the latest version. |
| `status` (required) | `"queued"`, `"running"`, `"succeeded"`, `"failed"` |   |
| `attempts` (required) | `integer` | Between 0 and 2. |
| `result_version` (required) | `integer` or `null` | The version the revision saved, set when the status is `succeeded`. |
| `error` (required) | `string` or `null` | Why the revision failed, set when the status is `failed`. |
| `requested_by` (required) | [`Author`](/docs/reference/api/schemas/#author) |   |
| `origin` (required) | `"web"`, `"cli"`, `"mcp"`, `"api"` or `null` | Where the request came from; `web` is a signed-in browser, `cli` the observe CLI, `mcp` an MCP client, `api` any other bearer-key caller. Null for requests made before origins were recorded. A label only, never used for access decisions. |
| `origin_client` (required) | `string` or `null` | The MCP client's self-reported `clientInfo.name` (for example `claude-code`), only when `origin` is `mcp`; unverified. |
| `created_at` (required) | `string` (date-time) |   |
| `started_at` (required) | `string` (date-time) or `null` |   |
| `finished_at` (required) | `string` (date-time) or `null` |   |

## RevisionEnvelope

| Field | Type | Description |
| --- | --- | --- |
| `revision` (required) | [`Revision`](/docs/reference/api/schemas/#revision) |   |

## SuggestionEnvelope

| Field | Type | Description |
| --- | --- | --- |
| `suggestion` (required) | [`Suggestion`](/docs/reference/api/schemas/#suggestion) |   |

## Suggestion

| Field | Type | Description |
| --- | --- | --- |
| `id` (required) | `string` (uuid) |   |
| `dashboard_id` (required) | `string` (uuid) |   |
| `panel_id` (required) | `string` | The panel the agent was asked to change. |
| `base_version` (required) | `integer` | The version the proposal is judged inside. |
| `prompt` (required) | `string` |   |
| `status` (required) | `"queued"`, `"running"`, `"succeeded"`, `"failed"` |   |
| `steps` (required) | array of [`AgentStep`](/docs/reference/api/schemas/#agentstep) | At most 200 items. |
| `panel` (required) | `object` or `null` | The proposed panel, set only when the status is `succeeded`. It is not saved anywhere; the client decides whether to apply it. |
| `error` (required) | `string` or `null` | Why the suggestion failed, set only when the status is `failed`. |
| `requested_by` (required) | [`Author`](/docs/reference/api/schemas/#author) |   |
| `origin` (required) | `"web"`, `"cli"`, `"mcp"`, `"api"` or `null` | Where the request came from. A label only, never used for access decisions. |
| `origin_client` (required) | `string` or `null` | The MCP client's self-reported `clientInfo.name`, only when `origin` is `mcp`; unverified. |
| `created_at` (required) | `string` (date-time) |   |
| `started_at` (required) | `string` (date-time) or `null` |   |
| `finished_at` (required) | `string` (date-time) or `null` |   |

## AgentInfo

| Field | Type | Description |
| --- | --- | --- |
| `available` (required) | `boolean` |   |
| `provider` (required) | `string` or `null` | The configured LLM provider, null when no agent is configured. |
| `model` (required) | `string` or `null` | The model the agent uses, null when no agent is configured. |
| `effort` (required) | `"low"`, `"medium"`, `"high"`, `"xhigh"`, `"max"` or `null` | Reasoning effort of the Anthropic provider; null otherwise. |

## AgentStep

| Field | Type | Description |
| --- | --- | --- |
| `at` (required) | `string` (date-time) |   |
| `attempt` (required) | `integer` | The attempt that ran the step. A shutdown release gives the attempt back and deletes its steps, so the re-claimed run reuses the same attempt number with a fresh step list. Clients detect a restarted list by each step's `at`, not by `attempt` alone. |
| `phase` (required) | `"discover"`, `"lint"`, `"query"`, `"save"`, `"repair"` |   |
| `tool` (required) | `string` |   |
| `status` (required) | `"ok"`, `"error"` |   |
| `message` (required) | `string` | The tool's fixed progress text, for example `Listed 37 metrics on prom`. |
| `duration_ms` (required) | `integer` |   |

## AgentUsage

| Field | Type | Description |
| --- | --- | --- |
| `provider` (required) | `string` |   |
| `model` (required) | `string` |   |
| `input_tokens` (required) | `integer` |   |
| `output_tokens` (required) | `integer` |   |
| `cache_read_tokens` (required) | `integer` |   |
| `cache_write_tokens` (required) | `integer` |   |
| `model_calls` (required) | `integer` |   |
| `repair_rounds` (required) | `integer` |   |

## AgentRequest

| Field | Type | Description |
| --- | --- | --- |
| `id` (required) | `string` (uuid) |   |
| `source` (required) | `"comment"`, `"prompt"`, `"observe"` |   |
| `prompt` (required) | `string` |   |
| `dashboard_id` (required) | `string` (uuid) or `null` | The dashboard the request targets; for a new-dashboard request it is null until the request has succeeded. |
| `base_version` (required) | `integer` or `null` | The version a revision was requested against; null for a new-dashboard request. |
| `panel_id` (required) | `string` or `null` |   |
| `comment_id` (required) | `string` (uuid) or `null` |   |
| `status` (required) | `"queued"`, `"running"`, `"succeeded"`, `"failed"` |   |
| `attempts` (required) | `integer` | Between 0 and 2. |
| `result_version` (required) | `integer` or `null` | The version the request saved, set when the status is `succeeded`. |
| `url` (required) | `string` or `null` | The address of the dashboard, set when the status is `succeeded`. |
| `error` (required) | `string` or `null` | Why the request failed, set when the status is `failed`. |
| `steps` (required) | array of [`AgentStep`](/docs/reference/api/schemas/#agentstep) | At most 200 items. |
| `usage` (required) | [`AgentUsage`](/docs/reference/api/schemas/#agentusage) or `null` | Tokens, model calls and repair rounds of the attempt that finished the request. |
| `requested_by` (required) | [`Author`](/docs/reference/api/schemas/#author) |   |
| `origin` (required) | `"web"`, `"cli"`, `"mcp"`, `"api"` or `null` | Where the request came from; `web` is a signed-in browser, `cli` the observe CLI, `mcp` an MCP client, `api` any other bearer-key caller. Null for requests made before origins were recorded. A label only, never used for access decisions. |
| `origin_client` (required) | `string` or `null` | The MCP client's self-reported `clientInfo.name` (for example `claude-code`), only when `origin` is `mcp`; unverified. |
| `created_at` (required) | `string` (date-time) |   |
| `started_at` (required) | `string` (date-time) or `null` |   |
| `finished_at` (required) | `string` (date-time) or `null` |   |

## RequestSummary

| Field | Type | Description |
| --- | --- | --- |
| `id` (required) | `string` (uuid) |   |
| `source` (required) | `"comment"`, `"prompt"`, `"observe"` |   |
| `prompt` (required) | `string` |   |
| `status` (required) | `"queued"`, `"running"`, `"succeeded"`, `"failed"` |   |
| `dashboard_id` (required) | `string` (uuid) or `null` |   |
| `dashboard_title` (required) | `string` or `null` | The dashboard's current title; null when the request has no dashboard. |
| `panel_id` (required) | `string` or `null` |   |
| `result_version` (required) | `integer` or `null` |   |
| `url` (required) | `string` or `null` |   |
| `error` (required) | `string` or `null` |   |
| `origin` (required) | `"web"`, `"cli"`, `"mcp"`, `"api"` or `null` |   |
| `origin_client` (required) | `string` or `null` |   |
| `created_at` (required) | `string` (date-time) |   |
| `started_at` (required) | `string` (date-time) or `null` |   |
| `finished_at` (required) | `string` (date-time) or `null` |   |

## AgentRequestEnvelope

| Field | Type | Description |
| --- | --- | --- |
| `request` (required) | [`AgentRequest`](/docs/reference/api/schemas/#agentrequest) |   |

## ImportRequest

| Field | Type | Description |
| --- | --- | --- |
| `json` (required) | `string` | The Grafana dashboard JSON text, exactly as pasted or uploaded. |
| `mapping` | `object` or `null` | Source datasource key to our datasource uid; keys and values are 1 to 200 bytes. |
| `folder` | `string` | The title of the folder for the new dashboard, trimmed and checked like a folder title; 400 `invalid_request` otherwise. Only the import uses it; the preview checks it and ignores it. |

## ImportSummary

| Field | Type | Description |
| --- | --- | --- |
| `format` (required) | `"classic"`, `"export"`, `"api"` |   |
| `title` (required) | `string` |   |
| `uid` (required) | `string` |   |
| `schema_version` (required) | `integer` |   |
| `bytes` (required) | `integer` |   |
| `panels` (required) | `integer` |   |
| `rows` (required) | `integer` |   |
| `variables` (required) | `integer` |   |

## ImportSourceDatasource

| Field | Type | Description |
| --- | --- | --- |
| `key` (required) | `string` | How the dashboard refers to the datasource (a uid, a name or an `${DS_...}` input). |
| `name` (required) | `string` or `null` |   |
| `type` (required) | `string` or `null` | The Grafana datasource type. |
| `kind` (required) | `string` or `null` | Our datasource type it needs (`prometheus` or `clickhouse`); null for a built-in datasource. |
| `panels` (required) | `integer` |   |
| `match` (required) | `string` or `null` | The uid of our datasource it will use; null while unmatched. |
| `matched_by` (required) | `"mapping"`, `"uid"`, `"alias"`, `"only"` or `null` |   |
| `candidates` (required) | array of `string` | The uids of ours of the same kind. |

## ImportQueryLine

| Field | Type | Description |
| --- | --- | --- |
| `ref_id` (required) | `string` |   |
| `ref` (required) | `string` or `null` |   |
| `datasource` (required) | `string` or `null` |   |
| `rewrites` (required) | array of `string` |   |
| `dropped` (required) | `string` or `null` |   |

## ImportPanelLine

| Field | Type | Description |
| --- | --- | --- |
| `panel_id` (required) | `string` |   |
| `grafana_id` (required) | `integer` or `null` |   |
| `grafana_path` (required) | `string` |   |
| `title` (required) | `string` |   |
| `type` (required) | `string` |   |
| `source_type` (required) | `string` |   |
| `row` (required) | `string` or `null` |   |
| `status` (required) | `"imported"`, `"partial"`, `"placeholder"`, `"unverified"` |   |
| `reasons` (required) | array of `string` |   |
| `paths` (required) | array of `string` |   |
| `queries` (required) | array of [`ImportQueryLine`](/docs/reference/api/schemas/#importqueryline) |   |

## ImportNote

| Field | Type | Description |
| --- | --- | --- |
| `subject` (required) | `string` |   |
| `status` (required) | `"imported"`, `"partial"`, `"placeholder"`, `"unverified"` |   |
| `reason` (required) | `string` |   |
| `paths` (required) | array of `string` |   |

## ImportCounts

| Field | Type | Description |
| --- | --- | --- |
| `total` (required) | `integer` |   |
| `imported` (required) | `integer` |   |
| `partial` (required) | `integer` |   |
| `placeholder` (required) | `integer` |   |
| `unverified` (required) | `integer` |   |

## ImportOptionLine

| Field | Type | Description |
| --- | --- | --- |
| `path` (required) | `string` | The Grafana option path relative to its block, in report syntax. |
| `outcome` (required) | `"mapped"`, `"excluded"`, `"reported"`, `"default"`, `"no_effect"`, `"bookkeeping"` | `default`, `no_effect` and `bookkeeping` are implicit options: a Grafana default value, an option with no visible effect, and editor bookkeeping; they need no Spec setting. |
| `spec` (required) | array of `string` | The ObserveSpec fields the option became, relative to the block's Spec object, array indexes written `[]`; empty when the option was not imported, is implicit, or no catalog names its field. |
| `reason` (required) | `string` or `null` | Why the option was excluded or not imported; null for every other outcome. |

## ImportBlock

| Field | Type | Description |
| --- | --- | --- |
| `kind` (required) | `"dashboard"`, `"variable"`, `"row"`, `"panel"`, `"query"`, `"transformation"`, `"field_config"`, `"override"` |   |
| `path` (required) | `string` | The Grafana path of the block from the dashboard root; empty for the dashboard. |
| `title` (required) | `string` | The panel or row title, variable name, query ref id, transformation id or override matcher id; empty for the dashboard and field config. |
| `source_type` (required) | `string` | The Grafana panel or variable type, or the query kind; empty otherwise. |
| `panel_id` (required) | `string` or `null` | The id of the Spec panel, for panel and row blocks; it matches `panels[].panel_id`. |
| `outcome` (required) | `"excluded"`, `"reported"` or `null` | Set when the whole block was not imported. |
| `reason` (required) | `string` or `null` |   |
| `options` (required) | array of [`ImportOptionLine`](/docs/reference/api/schemas/#importoptionline) |   |
| `implicit` (required) | `integer` | How many implicit options the block carried (outcomes `default`, `no_effect` and `bookkeeping`), including any the size limits left out of `options`. |
| `omitted` (required) | `integer` | Options of any outcome not listed because of the report's size limits. |
| `blocks` (required) | array of [`ImportBlock`](/docs/reference/api/schemas/#importblock) | Child blocks. |

## ImportReport

| Field | Type | Description |
| --- | --- | --- |
| `importer_version` (required) | `integer` |   |
| `verified` (required) | `boolean` | True once every query ran at save time; always false in a preview. |
| `counts` (required) | [`ImportCounts`](/docs/reference/api/schemas/#importcounts) |   |
| `panels` (required) | array of [`ImportPanelLine`](/docs/reference/api/schemas/#importpanelline) |   |
| `notes` (required) | array of [`ImportNote`](/docs/reference/api/schemas/#importnote) |   |
| `blocks` | array of [`ImportBlock`](/docs/reference/api/schemas/#importblock) | The report grouped by dashboard block. Absent in reports stored before importer version 2. |

## ImportPreview

| Field | Type | Description |
| --- | --- | --- |
| `summary` (required) | [`ImportSummary`](/docs/reference/api/schemas/#importsummary) |   |
| `datasources` (required) | array of [`ImportSourceDatasource`](/docs/reference/api/schemas/#importsourcedatasource) |   |
| `ready` (required) | `boolean` | True when every source datasource has a match, so the import can be saved. |
| `report` (required) | [`ImportReport`](/docs/reference/api/schemas/#importreport) |   |
| `spec` (required) | `object` or `null` | The converted ObserveSpec document; null when `ready` is false. |

## ImportRecord

| Field | Type | Description |
| --- | --- | --- |
| `id` (required) | `string` (uuid) |   |
| `dashboard_id` (required) | `string` (uuid) |   |
| `version` (required) | `integer` | The dashboard version the import produced. |
| `source` (required) | `"grafana"` |   |
| `importer_version` (required) | `integer` |   |
| `title` (required) | `string` |   |
| `mapping` (required) | `object` |   |
| `summary` (required) | [`ImportSummary`](/docs/reference/api/schemas/#importsummary) |   |
| `datasources` (required) | array of [`ImportSourceDatasource`](/docs/reference/api/schemas/#importsourcedatasource) |   |
| `report` (required) | [`ImportReport`](/docs/reference/api/schemas/#importreport) |   |
| `created_by` (required) | [`Author`](/docs/reference/api/schemas/#author) |   |
| `created_at` (required) | `string` (date-time) |   |

## ImportMeta

| Field | Type | Description |
| --- | --- | --- |
| `id` (required) | `string` (uuid) |   |
| `dashboard_id` (required) | `string` (uuid) |   |
| `version` (required) | `integer` |   |
| `importer_version` (required) | `integer` |   |
| `title` (required) | `string` |   |
| `counts` (required) | [`ImportCounts`](/docs/reference/api/schemas/#importcounts) |   |
| `created_by` (required) | [`Author`](/docs/reference/api/schemas/#author) |   |
| `created_at` (required) | `string` (date-time) |   |

## ImportList

| Field | Type | Description |
| --- | --- | --- |
| `imports` (required) | array of [`ImportMeta`](/docs/reference/api/schemas/#importmeta) |   |
| `next_cursor` (required) | `string` or `null` |   |

## ImportedDashboard

| Field | Type | Description |
| --- | --- | --- |
| `dashboard` (required) | [`DashboardSummary`](/docs/reference/api/schemas/#dashboardsummary) |   |
| `version` (required) | [`Version`](/docs/reference/api/schemas/#version) |   |
| `import` (required) | [`ImportRecord`](/docs/reference/api/schemas/#importrecord) |   |
| `folder_note` (required) | `string` or `null` | Why the dashboard is not in the requested folder, or null when it is where the request or the source asked. |

## DatasourcesUnresolved

| Field | Type | Description |
| --- | --- | --- |
| `error` (required) | `string` |   |
| `code` (required) | `"datasources_unresolved"` |   |
| `datasources` (required) | array of [`ImportSourceDatasource`](/docs/reference/api/schemas/#importsourcedatasource) |   |

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).