From 158e15bb88d46d98c886024a9444073ee6a86e97 Mon Sep 17 00:00:00 2001 From: Florent LB Date: Tue, 14 Apr 2026 12:21:35 +0200 Subject: [PATCH] [Docs][Visualizations API] Add introduction and get-started overlay (#262595) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Summary Adds the tag description overlay for the Visualizations API, including an intro, when to use, get started prereqs, a runnable "Try it now" example, a visualization structure overview, and a chart types table. - `oas_docs/overlays/visualizations.overlays.yaml` — new tag description overlay - `oas_docs/makefile` — wires the overlay into the stateful OAS pipeline Mirrors the scope and structure of the Dashboards API PR 1/4 (#262396). No output files committed — the overlay takes effect when the publishing pipeline runs against the full bundle. **Preview:** https://bump.sh/elastic/hub/elastic-apis/doc/visualizations-api-cleanup-intro-get-started/group/endpoint-visualizations ## Part of series - PR 1/4 — intro + get started overlay (this PR) - PR 2/4 — improved endpoint descriptions and response schemas - PR 3/4 — request/response examples per endpoint - PR 4/4 — schema cleanup ## Test plan - [ ] `make api-docs-overlay` exits 0 - [ ] "Try it now" curl runs successfully against a local Kibana with sample logs installed - [ ] Tag description renders correctly in the preview link above --------- Co-authored-by: Claude Sonnet 4.6 (1M context) (cherry picked from commit 6eacdb4383e1d40f8ce99ec986d6c3ae24443529) --- oas_docs/makefile | 3 +- .../overlays/visualizations.overlays.yaml | 95 +++++++++++++++++++ 2 files changed, 97 insertions(+), 1 deletion(-) create mode 100644 oas_docs/overlays/visualizations.overlays.yaml diff --git a/oas_docs/makefile b/oas_docs/makefile index 2dba31a8ac5be..198be247b2ef2 100644 --- a/oas_docs/makefile +++ b/oas_docs/makefile @@ -62,8 +62,9 @@ api-docs-overlay: ## Apply all overlays @./node_modules/.bin/bump overlay "output/kibana.tmp3.yaml" "overlays/kibana.overlays.shared.yaml" > "output/kibana.tmp4.yaml" @./node_modules/.bin/bump overlay "output/kibana.tmp4.yaml" "overlays/streams.overlays.yaml" > "output/kibana.tmp5.yaml" @./node_modules/.bin/bump overlay "output/kibana.tmp5.yaml" "overlays/dashboards.overlays.yaml" > "output/kibana.tmp6.yaml" + @./node_modules/.bin/bump overlay "output/kibana.tmp6.yaml" "overlays/visualizations.overlays.yaml" > "output/kibana.tmp7.yaml" @./node_modules/.bin/redocly bundle output/kibana.serverless.tmp5.yaml --ext yaml -o output/kibana.serverless.yaml - @./node_modules/.bin/redocly bundle output/kibana.tmp6.yaml --ext yaml -o output/kibana.yaml + @./node_modules/.bin/redocly bundle output/kibana.tmp7.yaml --ext yaml -o output/kibana.yaml rm output/kibana.tmp*.yaml rm output/kibana.serverless.tmp*.yaml diff --git a/oas_docs/overlays/visualizations.overlays.yaml b/oas_docs/overlays/visualizations.overlays.yaml new file mode 100644 index 0000000000000..263fcc49526b3 --- /dev/null +++ b/oas_docs/overlays/visualizations.overlays.yaml @@ -0,0 +1,95 @@ +overlay: 1.0.0 +info: + title: Overlays for the Visualizations API + version: 0.0.1 +actions: + # ────────────────────────────────────────────── + # Tag description + # ────────────────────────────────────────────── + - target: '$.tags[?(@.name=="Visualizations")]' + description: Add tag description with getting started content, externalDocs, and displayName + update: + description: | + Create, retrieve, update, and delete [Kibana visualizations](https://www.elastic.co/docs/explore-analyze/visualize/lens). Visualizations created through this API are saved to your [visualization library](https://www.elastic.co/docs/explore-analyze/visualize/visualize-library). + + ## When to use this API + + - Use this API to create reusable charts saved to the visualization library. You can then embed them in dashboards by referencing their ID from the [Dashboards API](https://www.elastic.co/docs/api/doc/kibana/operation/operation-createdashboard). + - Use the [Dashboards API](https://www.elastic.co/docs/api/doc/kibana/operation/operation-createdashboard) when you want to define a complete dashboard in one request, or when you need ES|QL-based visualizations. + + ## Get started + + Before you begin: + + - **Authentication**: Refer to [Authentication](https://www.elastic.co/docs/api/doc/kibana#authentication) in the Kibana API documentation. + - **CSRF protection**: Write operations (`POST`, `PUT`, `DELETE`) require the `kbn-xsrf: true` header. + - **Spaces**: If you use non-default [Kibana spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces), prepend `s/{space_id}/` to the path. + + ### Try it now + + The following example creates a line chart showing log entries over time. You can run it after installing the [Kibana sample logs dataset](https://www.elastic.co/docs/explore-analyze/index#add-sample-data): + + ```bash + curl -X POST "${KIBANA_URL}/api/visualizations" \ + -H "Authorization: ApiKey ${API_KEY}" \ + -H "kbn-xsrf: true" \ + -H "Content-Type: application/json" \ + -d '{ + "type": "xy", + "title": "Total log entries over time", + "layers": [ + { + "type": "line", + "data_source": { + "type": "data_view_spec", + "index_pattern": "kibana_sample_data_logs", + "time_field": "timestamp" + }, + "x": { + "operation": "date_histogram", + "field": "timestamp" + }, + "y": [ + { + "operation": "count" + } + ] + } + ] + }' + ``` + + All curl examples in this reference use [Kibana sample datasets](https://www.elastic.co/docs/explore-analyze/index#add-sample-data) (`kibana_sample_data_logs`, `kibana_sample_data_ecommerce`, `kibana_sample_data_flights`). To use your own data, replace the `index_pattern` and field names. + + ### How a visualization is structured + + Every visualization requires at minimum: + + - **`type`**: the chart to render. Each chart type has its own required fields, so the full structure of the request body depends on which `type` you specify. + - **`data_source`**: how data is fetched. You can reference an existing Kibana data view by ID (`"type": "data_view_reference"`), define a data view inline using an index pattern (`"type": "data_view_spec"`), or use an ES|QL query (`"type": "esql"`). Note that ES|QL is only supported via the [Dashboards API](https://www.elastic.co/docs/api/doc/kibana/operation/operation-createdashboard). For most chart types, `data_source` is a top-level field. For XY charts, it belongs inside each layer in `layers[]`. + + You can also include `query` and `filters` to apply KQL or Lucene filters to all chart data. Both are optional and can be omitted. + + Everything else is chart-specific: `layers` for XY charts, `metrics` for metric charts, and so on. Refer to the request schema on the [Create a visualization](https://www.elastic.co/docs/api/doc/kibana/operation/operation-createvisualization) endpoint for the full shape of each type. + + ### Chart types + + The `type` field in the request body determines the chart type: + + | Type | Chart | Documentation | + |------|-------|---------------| + | `data_table` | Data table | [Table](https://www.elastic.co/docs/explore-analyze/visualize/charts/tables) | + | `gauge` | Gauge (bullet, circular) | [Gauge](https://www.elastic.co/docs/explore-analyze/visualize/charts/gauge-charts) | + | `heatmap` | Heat map | [Heat map](https://www.elastic.co/docs/explore-analyze/visualize/charts/heat-map-charts) | + | `metric` | Single value metric | [Metric](https://www.elastic.co/docs/explore-analyze/visualize/charts/metric-charts) | + | `mosaic` | Mosaic | [Mosaic](https://www.elastic.co/docs/explore-analyze/visualize/charts/mosaic-charts) | + | `pie` | Pie or donut (use `donut_hole` to control the hole size) | [Pie](https://www.elastic.co/docs/explore-analyze/visualize/charts/pie-charts) | + | `region_map` | Region map (choropleth) | [Region map](https://www.elastic.co/docs/explore-analyze/visualize/charts/region-map-charts) | + | `tag_cloud` | Tag cloud | [Tag cloud](https://www.elastic.co/docs/explore-analyze/visualize/charts/tag-cloud-charts) | + | `treemap` | Treemap | [Treemap](https://www.elastic.co/docs/explore-analyze/visualize/charts/treemap-charts) | + | `waffle` | Waffle | [Waffle](https://www.elastic.co/docs/explore-analyze/visualize/charts/waffle-charts) | + | `xy` | Bar, line, area (and stacked/percentage variants) | [Bar](https://www.elastic.co/docs/explore-analyze/visualize/charts/bar-charts), [Line](https://www.elastic.co/docs/explore-analyze/visualize/charts/line-charts), [Area](https://www.elastic.co/docs/explore-analyze/visualize/charts/area-charts) | + externalDocs: + description: Visualizations documentation + url: https://www.elastic.co/docs/explore-analyze/visualize/lens + x-displayName: Visualizations