Dashboards API

Dashboards can be created from your own tooling — provisioning a standard dashboard set per service, generating one per tenant, or keeping dashboards in Git and applying them from CI.

This page covers the write (POST / PUT) endpoints for dashboards. For reading logs and traces see the Logs & Traces API; for metrics see the Metrics API; for alert rules see the Alerts API.

Authentication

An API key in the X-API-Key header:

X-API-Key: <your-api-key>

Create one under Settings → API Key Management. See Authentication for details.

API keys are scoped per key: you choose which modules a key may reach when you create it. The endpoints on this page need the dashboard scope — a key without it is rejected for this module regardless of who created it.

Request conventions

Endpoints

Create a dashboard

POST /api/dashboard

curl -s -X POST "https://<your-kubesense-host>/api/dashboard" \
  -H "X-API-Key: $KUBESENSE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Payments overview",
    "description": "Golden signals for the payments service",
    "status": "active",
    "preset": "{\"panels\":[],\"gridLayout\":[]}"
  }'

The response returns the new dashboard's id.

Building the preset

The preset holds the panels, grid layout and template variables. The practical way to get a valid one is to build the dashboard once in the UI and export it, then template the parts you want to vary (cluster name, namespace, service) and re-post it. Hand-writing a preset from scratch is possible but fiddly, and the schema evolves.

Presets are migrated on the way in, so a document exported from an older KubeSense version is upgraded automatically rather than rejected.

Tabs

A preset can carry an optional tabs array. Each tab is {"id", "title", "panels", "gridLayout", "subGrids", "subGridLayout"}, so it holds its own panels, layout and rows. variables and eventOverlays stay at the top level and apply to every tab.

• id matches ^[a-z0-9][a-z0-9-]{0,39}$ and is unique in the dashboard.
• title is 1 to 50 characters after trimming, and unique ignoring case.
• When tabs is non-empty, the top-level panels, gridLayout, subGrids and subGridLayout must be empty.
• Sub-grid ids are unique across all tabs.

An untabbed dashboard omits tabs or sends [].

Update a dashboard

PUT /api/dashboard takes the same body with id set to the dashboard you're updating.

Validate a preset

POST /api/dashboard/validate checks a preset without writing anything — useful in CI before committing a generated dashboard.

It is deliberately not gated behind write permission, so a read-only key can lint.

It accepts the preset in any of three forms, so you can pipe a document straight through without reshaping it:

• the preset object itself ({"panels":[…],"gridLayout":[…]})
• the preset as a JSON string
• the import envelope — an object carrying the stringified preset under preset

curl -s -X POST "https://<your-kubesense-host>/api/dashboard/validate" \
  -H "X-API-Key: $KUBESENSE_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @dashboard.json

Request bodies are capped at 8 MB.

Dashboard lists

Lists group dashboards for navigation. Membership is many-to-many: a dashboard belongs to as many lists as you file it under, and adding it to one never removes it from another. See Dashboard Lists for the concept.

These endpoints reuse the dashboard scope and the dashboard module's permissions — there is no separate list scope to grant. Reads need read access; every other verb needs write access.

Create a list

POST /api/dashboard-lists

curl -s -X POST "https://<your-kubesense-host>/api/dashboard-lists" \
  -H "X-API-Key: $KUBESENSE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production",
    "description": "Dashboards on call refers to"
  }'

The response returns the new list's id. A duplicate name returns 409.

List and fetch

GET /api/dashboard-lists returns every list with a dashboard_count of the live dashboards in it. It is not paginated. GET /api/dashboard-lists/{id} returns one.

Rename a list

PUT /api/dashboard-lists/{id} takes the same body as create. Renaming to a name another live list already holds returns 409.

Add and remove dashboards

# Add
curl -s -X POST "https://<your-kubesense-host>/api/dashboard-lists/$LIST_ID/dashboards" \
  -H "X-API-Key: $KUBESENSE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dashboard_ids": ["<uuid>", "<uuid>"]}'

# Remove
curl -s -X DELETE "https://<your-kubesense-host>/api/dashboard-lists/$LIST_ID/dashboards" \
  -H "X-API-Key: $KUBESENSE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dashboard_ids": ["<uuid>"]}'

Adding a dashboard already in the list is a no-op, not an error, so a batch containing some existing members succeeds rather than failing partway. Adding a dashboard that does not exist returns 400.

Removing only unfiles the dashboard — the dashboard itself is untouched and keeps every other list it belongs to.

Replace a dashboard's membership

PUT /api/dashboard-lists/dashboard/{id} sets the complete set of lists one dashboard belongs to:

curl -s -X PUT "https://<your-kubesense-host>/api/dashboard-lists/dashboard/$DASHBOARD_ID" \
  -H "X-API-Key: $KUBESENSE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"list_ids": ["<uuid>", "<uuid>"]}'

Lists omitted from list_ids are removed, so an empty array unfiles the dashboard entirely. Use this when you know the desired end state; use the add/remove endpoints above when you only want to adjust one membership without reading the current set first.

Delete a list

DELETE /api/dashboard-lists/{id}?strategy=detach

Both strategies run as a single transaction, so a list is never left half-deleted.

Dashboard access

Restricting a dashboard narrows who may reach it. See Dashboard Access for the concept and what each choice means.

The read needs viewer access to the dashboard; both writes are owner only. Module write is necessary but not sufficient — an editor cannot change who else reaches a dashboard.

Read the access state

GET /api/dashboard/{id}/access returns the mode, the owner, and every grant with the addresses resolved:

{
  "restriction_mode": "restricted",
  "default_access": "viewer",
  "owner_id": "…",
  "owner_email": "admin@kubesense.ai",
  "owner_name": "KubeSense Admin",
  "grants": [
    {
      "principal_type": "user",
      "principal_id": "…",
      "email": "karthik@kubesense.ai",
      "name": "Karthik K",
      "access_level": "editor"
    }
  ]
}

Set the access state

PUT /api/dashboard/{id}/access takes the whole grant list, not a delta — the last writer wins cleanly rather than diffing against a list someone else may have changed since:

curl -s -X PUT "https://<your-kubesense-host>/api/dashboard/$DASHBOARD_ID/access" \
  -H "X-API-Key: $KUBESENSE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "restriction_mode": "restricted",
    "default_access": "viewer",
    "grants": [
      { "principal_type": "user", "email": "karthik@kubesense.ai", "access_level": "editor" }
    ]
  }'

Grants are stored against the user id, not the address, so a grant survives someone changing their email.

Transfer ownership

PUT /api/dashboard/{id}/owner takes {"email": "…"}. Owner only. There is no administrator override anywhere in this API, so a dashboard whose owner has left cannot have its access changed by anyone else — transfer it before that happens.

Errors