Reference

HTTP API

Base URL, authentication, errors and every endpoint of the SlashObserve HTTP API.

Every path is relative to /api/v1 on your SlashObserve server, and every request and response body is JSON unless an endpoint says otherwise.

Authentication

Scheme	How	Description
`sessionCookie`	`cookie so_session`	Opaque session token set by the OIDC callback. The cookie is named `__Host-so_session` when the public URL is https.
`bearerKey`	`Authorization: Bearer`	Service-account key issued by the keys endpoint, prefixed `sok_`.

Every endpoint accepts either scheme unless its section says it needs no authentication.

Errors

Errors return an Error body; validation errors return ValidationError.

Status	Meaning
`400`	The request is malformed or fails validation.
`401`	Authentication is missing or invalid.
`403`	The caller is not allowed to perform the request; a role that is too low is code `forbidden_role`.
`404`	The resource does not exist.
`409`	The request conflicts with existing state.
`500`	The server failed to handle the request.
`413`	The request body exceeds the size limit.
`422`	The Spec fails validation or one of its queries fails; every problem is listed in `issues`.
`409`	The parent version is no longer the latest; `latest_version` names the current one.
`429`	The caller already has the maximum number of query requests in flight, or the server’s shared upstream call slots stayed busy for 5 seconds.
`422`	The query or its variables cannot run, or its result exceeds a limit.
`502`	The datasource is unavailable.
`504`	The datasource did not answer within the query timeout.

Endpoints

Endpoint	Summary
`GET /auth/login`	Start the OIDC sign-in and redirect to the identity provider.
`GET /auth/callback`	Complete the OIDC sign-in and redirect to the local return path.
`POST /auth/logout`	End the current session and clear its cookie.
`GET /auth/session`	Report whether the request carries a valid session.
`GET /me`	Return the authenticated caller.
`GET /instance`	Return the server’s public and MCP URLs and its sign-in settings; never a secret.

Service accounts

Endpoint	Summary
`GET /service-accounts`	List service accounts.
`POST /service-accounts`	Create a service account.
`PATCH /service-accounts/{id}`	Change the role a service account’s keys act with.
`GET /service-accounts/{id}/keys`	List the keys of a service account without their secrets.
`POST /service-accounts/{id}/keys`	Issue a key for a service account.
`DELETE /service-accounts/{id}/keys/{keyId}`	Revoke a key of a service account.

People

Endpoint	Summary
`GET /users`	List everyone who has signed in, newest first.
`PATCH /users/{id}`	Set or clear the role an Admin chose for a person.
`DELETE /users/{id}/sessions`	Delete every session of a person.

Outbound domains

Endpoint	Summary
`GET /outbound-domains`	List the domains the server may fetch content from.
`POST /outbound-domains`	Allow a domain.
`DELETE /outbound-domains/{domain}`	Stop allowing a domain.

Saved prompts

Endpoint	Summary
`GET /prompts`	List the saved prompts the caller may run.
`POST /prompts`	Save a prompt.
`PATCH /prompts/{id}`	Change a saved prompt.
`DELETE /prompts/{id}`	Delete a saved prompt.

Datasources

Endpoint	Summary
`GET /datasources`	Report the health and dashboard usage of every configured datasource, never its connection details.

Folders

Endpoint	Summary
`GET /folders`	List the folders the caller can see.
`POST /folders`	Create a folder.
`GET /folders/{id}`	Get a folder.
`PATCH /folders/{id}`	Rename a folder.
`DELETE /folders/{id}`	Delete an empty folder.
`GET /folders/{id}/permissions`	List who a folder is restricted to.
`PUT /folders/{id}/permissions`	Replace the people and groups a folder is restricted to.

Dashboards

Endpoint	Summary
`GET /dashboards`	List the dashboards the caller can see, most recently updated first or grouped by folder.
`POST /dashboards`	Create a dashboard from a Spec, validating it and running every panel query.
`GET /dashboards/tags`	List every dashboard tag with its dashboard count, by tag name.
`GET /dashboards/{id}`	Get a dashboard with its latest version.
`PATCH /dashboards/{id}`	Move a dashboard to another folder.
`DELETE /dashboards/{id}`	Delete a dashboard with every version, comment, agent request and import record.
`GET /dashboards/{id}/versions`	List the versions of a dashboard without their Specs, newest first.
`POST /dashboards/{id}/versions`	Save a new version on top of the version the caller last saw, validating the Spec and running every panel query.
`GET /dashboards/{id}/versions/{version}`	Get one version of a dashboard with its Spec.
`POST /dashboards/{id}/versions/{version}/restore`	Save a copy of an earlier version as a new version.
`POST /dashboards/{id}/duplicate`	Save the latest version as version 1 of a new dashboard.
`GET /dashboards/{id}/diff`	List the structural changes between two versions of a dashboard.

Grafana imports

Endpoint	Summary
`GET /dashboards/{id}/import`	Get how a dashboard was imported from Grafana.
`POST /imports/preview`	Convert a Grafana dashboard without saving it or running any query.
`GET /imports`	List imports, newest first.
`POST /imports`	Import a Grafana dashboard as version 1 of a new dashboard.

Actions

Endpoint	Summary
`POST /dashboards/{id}/actions`	Run an action that is saved in the dashboard’s latest version.

Live events

Endpoint	Summary
`GET /dashboards/{id}/events`	Stream live events for one dashboard as Server-Sent Events.

Comments

Endpoint	Summary
`GET /dashboards/{id}/comments`	List the comments of a dashboard across all versions, oldest first.
`POST /dashboards/{id}/comments`	Comment on a panel or the whole dashboard, or reply to a thread.
`PATCH /dashboards/{id}/comments/{comment_id}`	Resolve or reopen a comment.

Panel and variable data

Endpoint	Summary
`GET /dashboards/{id}/versions/{version}/panels/{panel_id}/data`	Run the saved queries of one panel in one dashboard version and return their frames.
`GET /dashboards/{id}/versions/{version}/variables/{name}/values`	List the values of one variable in one dashboard version.
`POST /datasources/{uid}/lint`	Parse a query for a datasource and return diagnostics, without executing it or returning data.

Draft panel preview

Endpoint	Summary
`POST /datasources/{uid}/preview`	Run an unsaved data panel placed into a saved dashboard version and return its frames.

Metric and label names

Endpoint	Summary
`GET /datasources/{uid}/metrics`	List the metric names of a datasource, up to a limit.
`GET /datasources/{uid}/labels`	List the label names of a datasource, or its OpenTelemetry attribute keys on ClickHouse, up to a limit.
`GET /datasources/{uid}/labels/{name}/values`	List the values of one label of a datasource, up to a limit.

Revision requests

Endpoint	Summary
`GET /dashboards/{id}/revisions`	List the agent requests of a dashboard, newest first, including the new-dashboard request that created it.
`POST /dashboards/{id}/revisions`	Ask the agent to revise a dashboard with a follow-up prompt.
`GET /dashboards/{id}/revisions/{revision_id}`	Read one revision request.

Panel suggestions

Endpoint	Summary
`POST /dashboards/{id}/suggestions`	Ask the agent to propose a change to one panel without saving anything.
`GET /dashboards/{id}/suggestions/{suggestion_id}`	Read one panel suggestion.

Agent requests

Endpoint	Summary
`GET /agent`	Tell whether an agent is configured and which provider and model it uses.
`GET /observe`	List the caller’s own agent requests, newest first.
`POST /observe`	Ask the agent to build a new dashboard, or to revise an existing one with a follow-up prompt.
`GET /observe/{id}`	Read one agent request with its progress steps and usage.

News feeds

Endpoint	Summary
`GET /news`	Fetch an RSS or Atom feed through the server and return its items as plain text.

Assets

Endpoint	Summary
`GET /assets/image`	Fetch a remote image through the server and return it.
`GET /assets/geojson`	Fetch a remote GeoJSON file through the server and return it as JSON.

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