Reference

Schemas

The request and response objects the HTTP API endpoints use.

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`

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`

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`

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`

ServiceAccountList

Field	Type	Description
`items` (required)	array of `ServiceAccount`

CreateServiceAccountRequest

Field	Type	Description
`name` (required)	`string`
`description`	`string`
`role`	`Role`	The role the account’s keys act with; editor when omitted.

UpdateServiceAccountRequest

Field	Type	Description
`role` (required)	`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`

CreateServiceAccountKeyRequest

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

IssuedServiceAccountKey

Field	Type	Description
`key` (required)	`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`
`role_source` (required)	`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` 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`

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` or `null`	Null for General and for folders made before creators were recorded.
`permissions` (required)	`Permissions`
`level` (required)	`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`

FolderPermissions

Field	Type	Description
`restricted` (required)	`boolean`
`entries` (required)	array of `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`
`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`	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`	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`

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`
`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`
`creator` (required)	`Creator`
`folder` (required)	`DashboardFolder`
`permissions` (required)	`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`
`creator` (required)	`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`
`permissions` (required)	`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`
`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`
`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`

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`
`variables` (required)	array of `UnverifiedVariable`

UnverifiedPanel

Field	Type	Description
`panel_id` (required)	`string`
`issues` (required)	array of `Issue`

UnverifiedVariable

Field	Type	Description
`name` (required)	`string`
`issues` (required)	array of `Issue`

DashboardWithVersion

Field	Type	Description
`dashboard` (required)	`DashboardSummary`
`version` (required)	`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`
`created_at` (required)	`string` (date-time)
`updated_at` (required)	`string` (date-time)
`resolved_at` (required)	`string` (date-time) or `null`
`resolved_by` (required)	`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`

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`

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`	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`
`exemplars`	array of `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`

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`

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`
`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`

SuggestionEnvelope

Field	Type	Description
`suggestion` (required)	`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`	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`
`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`	At most 200 items.
`usage` (required)	`AgentUsage` or `null`	Tokens, model calls and repair rounds of the attempt that finished the request.
`requested_by` (required)	`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`

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`

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`
`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`	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`
`panels` (required)	array of `ImportPanelLine`
`notes` (required)	array of `ImportNote`
`blocks`	array of `ImportBlock`	The report grouped by dashboard block. Absent in reports stored before importer version 2.

ImportPreview

Field	Type	Description
`summary` (required)	`ImportSummary`
`datasources` (required)	array of `ImportSourceDatasource`
`ready` (required)	`boolean`	True when every source datasource has a match, so the import can be saved.
`report` (required)	`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`
`datasources` (required)	array of `ImportSourceDatasource`
`report` (required)	`ImportReport`
`created_by` (required)	`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`
`created_by` (required)	`Author`
`created_at` (required)	`string` (date-time)

ImportList

Field	Type	Description
`imports` (required)	array of `ImportMeta`
`next_cursor` (required)	`string` or `null`

ImportedDashboard

Field	Type	Description
`dashboard` (required)	`DashboardSummary`
`version` (required)	`Version`
`import` (required)	`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`

Generated from api/openapi.yaml at bac0fe39. Report a problem.