/kibana-dashboards

name: kibana-dashboards
description: >
  Create and manage Kibana Dashboards and Lens visualizations. Use when you need to
  define dashboards and visualizations declaratively, version control them, or automate
  their deployment.
metadata:
  author: elastic
  version: 0.3.0
  universal: true
compatibility: Kibana 9.4 or later (Dashboards and Visualizations APIs) with matching
  Elasticsearch, self-managed, Elastic Cloud Hosted, or Elastic Cloud Serverless.
  Requires the `elastic` CLI ≥ 0.3 with `stack kb` support (dedicated `dashboards`
  and `visualizations` commands).

Kibana Dashboards and Lens Visualizations

Create, update, and delete Kibana dashboards and standalone Lens visualizations using the Kibana 9.4+ Dashboards and Visualizations APIs. Produce minimal, diffable JSON bodies; prefer inline panel definitions over library references; and choose the correct dataset type (data view vs ES|QL) before writing metrics or chart layers.

<!-- begin-partial: preamble -->

Environment Configuration

This skill executes Elasticsearch operations through the `elastic` CLI. If the [`elastic` CLI](https://github.com/elastic/cli#configuration) is not installed, tell the user what it is needed for. Do not guess credentials, call the HTTP API directly, or attempt other workarounds.

This skill references operations in HTTP-shorthand form (e.g., `GET /`, `GET /_cat/indices`, `GET /{index}/_mapping`, `GET /{index}/_settings/index.mode`, `POST /_query`). The [Operations](#operations) table at the end of this document maps each shorthand to the equivalent `elastic` CLI command — always use the CLI rather than calling the HTTP API directly.

<!-- end-partial: preamble -->

Prerequisites

**Version requirement:** Kibana 9.4+ (Dashboards and Visualizations APIs).

**ES|QL placement:**

• Standalone library charts: `PUT kbn:/api/visualizations/{id}` with `data_source.type: "esql"`.
• ES|QL panels embedded in a dashboard: inline `vis` panel `config` with `data_source.type: "esql"` via

`PUT kbn:/api/dashboards/{id}`.

• Do not use `data_source.type: "data_view_reference"` or index-pattern aggregations when the user explicitly requests

ES|QL — the persisted Lens state must use a text-based ES|QL datasource (`textBased` / `esql`), not a data-view count operation.

Process

1. **Verify Kibana connectivity.** Call `GET kbn:/api/status`. If the call fails, stop and surface the error — do not guess endpoints or credentials. Read `version.number` to confirm the cluster meets the 9.4+ requirement.

2. **Classify the task.** Decide whether the user needs a **dashboard** (collection of panels, optional time range), a **standalone Lens visualization** (library item referenced by id or used alone), or **both**. Determine whether a deterministic saved-object id was supplied — when given, use upsert (`PUT`) with that id rather than `POST` (which auto-generates ids).

3. **Choose the dataset type before building metrics or layers.**

| User intent | Dataset | Metric / axis pattern | | ------------------------------------------------ | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | Simple count or aggregation on a saved data view | `data_source.type: "data_view_reference"` with `ref_id` | `metrics: [{ type: "primary", operation: "count" }]` (or other aggregation operations) | | Ad-hoc index pattern | `data_source.type: "data_view_spec"` with `index_pattern` and `time_field` | Same aggregation `operation` fields | | ES\|QL query (explicit or complex logic) | `data_source.type: "esql"` with `query` | `metrics: [{ type: "primary", column: "<alias>" }]` or layer axes `{ column: "<alias>" }` — **never** `operation: "count"` on the metric |

Write the aggregation in the ES|QL query (`STATS count = COUNT()`), then reference the resulting column by name.

4. **Build a dashboard body when creating or updating dashboards.** The request body is flat — `title`, `panels`, and optional `time_range` at the root. Do not wrap in `{ data: ... }` on write. Required fields:

• `title` — exact string the user requested.
• `panels` — array; use `[]` when the user asks for an empty dashboard (do not omit the key or invent panels).
• `time_range` — when the user specifies a default time filter, set `{ "from": "<expr>", "to": "<expr>" }` (for

example `{ "from": "now-7d", "to": "now" }`). Supplying `time_range` persists the dashboard time filter on open (equivalent to enabling time restore in the UI).

**Upsert with a deterministic id:**

   {
     "title": "Sales Overview",
     "panels": [],
     "time_range": { "from": "now-7d", "to": "now" }
   }

Call `PUT kbn:/api/dashboards/eval-sales-overview` with the body above when the user supplies that id.

**Inline ES|QL metric panel example** (inside `panels`):

   {
     "type": "vis",
     "id": "total-requests",
     "grid": { "x": 0, "y": 0, "w": 12, "h": 6 },
     "config": {
       "title": "Total Requests",
       "type": "metric",
       "data_source": {
         "type": "esql",
         "query": "FROM logs* | STATS count = COUNT()"
       },
       "metrics": [{ "type": "primary", "column": "count" }]
     }
   }

Prefer inline `config` properties over `config.ref_id` for portable dashboards. Read [Dashboard API Reference](references/dashboard-ap