---
title: "HTTP API"
description: "Base URL, authentication, errors and every endpoint of the SlashObserve 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.

# 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`](/docs/reference/api/schemas/#error) body; validation errors return [`ValidationError`](/docs/reference/api/schemas/#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

### Sign-in and session

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

### Service accounts

| Endpoint | Summary |
| --- | --- |
| [`GET /service-accounts`](/docs/reference/api/service-accounts/) | List service accounts. |
| [`POST /service-accounts`](/docs/reference/api/service-accounts/) | Create a service account. |
| [`PATCH /service-accounts/{id}`](/docs/reference/api/service-accounts/) | Change the role a service account's keys act with. |
| [`GET /service-accounts/{id}/keys`](/docs/reference/api/service-accounts/) | List the keys of a service account without their secrets. |
| [`POST /service-accounts/{id}/keys`](/docs/reference/api/service-accounts/) | Issue a key for a service account. |
| [`DELETE /service-accounts/{id}/keys/{keyId}`](/docs/reference/api/service-accounts/) | Revoke a key of a service account. |

### People

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

### Outbound domains

| Endpoint | Summary |
| --- | --- |
| [`GET /outbound-domains`](/docs/reference/api/outbound-domains/) | List the domains the server may fetch content from. |
| [`POST /outbound-domains`](/docs/reference/api/outbound-domains/) | Allow a domain. |
| [`DELETE /outbound-domains/{domain}`](/docs/reference/api/outbound-domains/) | Stop allowing a domain. |

### Saved prompts

| Endpoint | Summary |
| --- | --- |
| [`GET /prompts`](/docs/reference/api/prompts/) | List the saved prompts the caller may run. |
| [`POST /prompts`](/docs/reference/api/prompts/) | Save a prompt. |
| [`PATCH /prompts/{id}`](/docs/reference/api/prompts/) | Change a saved prompt. |
| [`DELETE /prompts/{id}`](/docs/reference/api/prompts/) | Delete a saved prompt. |

### Datasources

| Endpoint | Summary |
| --- | --- |
| [`GET /datasources`](/docs/reference/api/datasources/) | Report the health and dashboard usage of every configured datasource, never its connection details. |

### Folders

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

### Dashboards

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

### Grafana imports

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

### Actions

| Endpoint | Summary |
| --- | --- |
| [`POST /dashboards/{id}/actions`](/docs/reference/api/actions/) | Run an action that is saved in the dashboard's latest version. |

### Live events

| Endpoint | Summary |
| --- | --- |
| [`GET /dashboards/{id}/events`](/docs/reference/api/events/) | Stream live events for one dashboard as Server-Sent Events. |

### Comments

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

### Panel and variable data

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

### Draft panel preview

| Endpoint | Summary |
| --- | --- |
| [`POST /datasources/{uid}/preview`](/docs/reference/api/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`](/docs/reference/api/names/) | List the metric names of a datasource, up to a limit. |
| [`GET /datasources/{uid}/labels`](/docs/reference/api/names/) | List the label names of a datasource, or its OpenTelemetry attribute keys on ClickHouse, up to a limit. |
| [`GET /datasources/{uid}/labels/{name}/values`](/docs/reference/api/names/) | List the values of one label of a datasource, up to a limit. |

### Revision requests

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

### Panel suggestions

| Endpoint | Summary |
| --- | --- |
| [`POST /dashboards/{id}/suggestions`](/docs/reference/api/suggestions/) | Ask the agent to propose a change to one panel without saving anything. |
| [`GET /dashboards/{id}/suggestions/{suggestion_id}`](/docs/reference/api/suggestions/) | Read one panel suggestion. |

### Agent requests

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

### News feeds

| Endpoint | Summary |
| --- | --- |
| [`GET /news`](/docs/reference/api/news/) | Fetch an RSS or Atom feed through the server and return its items as plain text. |

### Assets

| Endpoint | Summary |
| --- | --- |
| [`GET /assets/image`](/docs/reference/api/assets/) | Fetch a remote image through the server and return it. |
| [`GET /assets/geojson`](/docs/reference/api/assets/) | Fetch a remote GeoJSON file through the server and return it as JSON. |

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