Add Visualizations API examples to Lens chart pages by florent-leborgne · Pull Request #5645 · elastic/docs-content

florent-leborgne · 2026-03-26T13:05:49Z

Summary

Add "Create this chart using the API" collapsible dropdowns to all 13 Lens chart type documentation pages plus an API intro section to the main Lens page. Each dropdown contains a Console + cURL payload that recreates the described chart via `POST /api/visualizations`.

Reviewers: you do not need to validate that the payloads work, rather focus on the content around if you like or on doing spot checks

What is included

43 inline API dropdowns across all 13 chart pages (area, bar, gauge, heat map, line, metric, mosaic, pie, region map, table, tag cloud, treemap, waffle)
Lens overview page (lens.md): new "Create visualizations with the API" section linking to stateful and serverless API docs
All sections gated with `applies_to: stack: preview 9.4 / serverless: preview`
`.github/scripts/verify-lens-api-examples.py`: stdlib-only Python script that extracts every payload from the chart files, POSTs each to `/api/visualizations`, asserts HTTP 201, and cleans up — same pattern as [Dashboards] Recreate the data-exploration tutorial dashboard with the Dashboards API #6337

Verification

43/43 payloads pass against a live Kibana serverless instance with all three sample datasets loaded:

```
KIBANA_URL=… API_KEY=… python3 .github/scripts/verify-lens-api-examples.py
Results: 43/43 passed — all OK
```

Test plan

All 43 JSON payloads parse successfully (0 errors in dry-run)
43/43 payloads create visualizations against a live 9.5.0 serverless instance
Vale linting passes (0 errors, 0 warnings, 0 suggestions)

Visual validation (preview + live Kibana)

github-actions · 2026-03-26T13:07:21Z

🔍 Preview links for changed docs

Vale Linting Results

Summary: 4 warnings, 5 suggestions found

⚠️ Warnings (4)

File	Line	Rule	Message
explore-analyze/visualize/charts/bar-charts.md	420	Elastic.QuotesPunctuation	Place punctuation inside closing quotation marks.
explore-analyze/visualize/charts/heat-map-charts.md	321	Elastic.Latinisms	Latin terms and abbreviations are a common source of confusion. Use 'versus' instead of 'vs'.
explore-analyze/visualize/charts/pie-charts.md	216	Elastic.QuotesPunctuation	Place punctuation inside closing quotation marks.
explore-analyze/visualize/charts/pie-charts.md	216	Elastic.QuotesPunctuation	Place punctuation inside closing quotation marks.

💡 Suggestions (5)

File	Line	Rule	Message
explore-analyze/visualize/charts/bar-charts.md	183	Elastic.WordChoice	Consider using 'efficient' instead of 'easy', unless the term is in the UI.
explore-analyze/visualize/charts/heat-map-charts.md	93	Elastic.WordChoice	Consider using 'efficient' instead of 'easy', unless the term is in the UI.
explore-analyze/visualize/charts/heat-map-charts.md	357	Elastic.WordChoice	Consider using 'efficient' instead of 'easy', unless the term is in the UI.
explore-analyze/visualize/charts/mosaic-charts.md	250	Elastic.WordChoice	Consider using 'efficient' instead of 'easy', unless the term is in the UI.
explore-analyze/visualize/lens.md	60	Elastic.WordChoice	Consider using 'can, might' instead of 'may', unless the term is in the UI.

The Vale linter checks documentation changes against the Elastic Docs style guide.

To use Vale locally or report issues, refer to Elastic style guide for Vale.

Add "Create this chart using the API" collapsible dropdowns after each individual example and advanced scenario across all 13 chart type pages. Each dropdown contains a cURL payload that recreates the described chart via POST /api/visualizations. 50 dropdowns total covering: - 27 chart examples (matching UI-built configurations) - 13 advanced scenarios (time shifts, reference lines, stacked bars, etc.) - Multiple chart types per payload pattern Also adds a Visualizations API intro section to the main Lens page with links to both stateful and serverless API docs. All sections gated with applies_to: stack: preview 9.4 / serverless: preview. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Switch from code block applies_to inside dropdowns to the :applies_to: directive option syntax per docs-builder conventions. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Remove bash-specific quote escaping from JSON payloads in cURL examples. Single quotes inside JSON strings are valid and don't need escaping. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Fixes validated against a 9.4 snapshot with all sample datasets: - Move dataset inside XY layers (area, bar, line charts) - Fix field names: slice_by→group_by, x_axis→x, tags→tag_by, etc. - Remove null values (API rejects nulls for optional fields) - Fix split_metrics_by to be an array - Fix other_bucket to use object format - Fix filters operation structure in group_by - Fix formula quoting (bare single quotes, no shell escaping) 39 of 50 payloads now pass integration tests. The 11 remaining failures are all caused by the same runtime bug: the minMaxAvgMedianStdDevMetricOperation discriminator doesn't resolve, so operations like average/min/max fail validation. These payloads are structurally correct per the spec and will work once the discriminator bug is fixed. Tracked in VISUALIZATIONS_API_DISCREPANCIES.md. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Key fixes: - metric charts: add type:primary/secondary, alignments, icon fields - gauge charts: fix color step structure - line charts: fix moving_average to use nested "of" field - bar charts: fix reference line layer to use thresholds array - tables: fix split_metrics_by to be array All 50 payloads now create visualizations successfully against a live Kibana 9.4 snapshot with sample data loaded. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Un-indent dropdown directives from definition lists to root level and add intro text with code callouts to the 3 example dropdowns. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Un-indent dropdown directives nested inside definition lists in line-charts, area-charts, and tables. Add intro sentences and <N> code callouts to all ~50 API dropdown examples across 12 chart pages. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- terms size → limit across all 12 chart pages - alignments → labels/value with alignment: sub-field in metric-charts.md Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…s all 13 chart pages - Numbered callouts now strictly follow top-to-bottom order in every payload - Added 3 missing <N> markers (waffle OS distribution, treemap bytes/extension, tables custom-ranges) - Renumbered out-of-order markers in 6 dropdowns (bar, gauge, line, pie, treemap, waffle) - Swapped explanation text in 6 dropdowns to match the new marker order - Updated 7 stale "`size: N`" explanation labels to "`limit: N`" to match the renamed API field Co-authored-by: Cursor <cursoragent@cursor.com>

Co-authored-by: Cursor <cursoragent@cursor.com>

…icable When an explanation describes what a whole block does (group_by, group_breakdown_by, filters array, metric), move the callout to the block opener rather than a field nested inside it. Five markers updated across mosaic, waffle, and gauge chart pages. Co-authored-by: Cursor <cursoragent@cursor.com>

…l placement Co-authored-by: Cursor <cursoragent@cursor.com>

…allout proximity - Add color block to filters group_by: green/yellow/red for success/4xx/5xx - Move <2> from adjacent 'filters:' line to the new 'color:' block - Update explanation 2 to describe the color assignment Co-authored-by: Cursor <cursoragent@cursor.com>

…breakdown Co-authored-by: Cursor <cursoragent@cursor.com>

… heat-map examples Callout 2/3 in waffle goal-tracking and callout 3 in heat-map revenue-by-region were placed on label/formula/field lines whose explanations described the containing metric as a whole. Anchored each marker to the corresponding operation line to match what the explanation actually describes, consistent with the gauge fix applied earlier. Co-authored-by: Cursor <cursoragent@cursor.com>

Each UI example that specified a color setting now has the matching API configuration validated against live Kibana 9.5.0: - treemap: gradient #ffc7db on group_by[0] (terms/host.keyword) - tag cloud: gradient default palette on tag_by + orientation: angled - heat map day/hour: Cool sequential palette via legacyColorByValue - heat map sales: Positive sequential palette via legacyColorByValue - pie error distribution: categorical red/yellow/green on group_by filters - bar reference line: static red (#BD271E) + dashed stroke Also notes in mosaic that group_breakdown_by has no color field in the API schema — color mapping for breakdown rows is not configurable. Co-authored-by: Cursor <cursoragent@cursor.com>

Three callouts described the group_by block as a whole (terms grouping, nesting behavior) but were anchored on the fields sub-field. Moved each to the operation line of the relevant terms block, consistent with the fix applied to gauge, mosaic, waffle, heat-map, bar, and line charts. Co-authored-by: Cursor <cursoragent@cursor.com>

- sort: desc on gradient to invert color direction - other_bucket to show the Other segment visible in the screenshot - mode: percentage to match the percentage labels in the UI example Co-authored-by: Cursor <cursoragent@cursor.com>

…s, reversed gradient Co-authored-by: Cursor <cursoragent@cursor.com>

Co-authored-by: Cursor <cursoragent@cursor.com>

- Add includes regex (.+), other_bucket, rank_by metric desc, and increase_accuracy to the Bytes per file extension example - Set styling.values.mode to percentage for Bytes per file extension and Flights by carrier and destination country examples - Add gradient color (sort: desc), other_bucket, and percentage mode to Response status per host example - Move callouts to operation lines throughout; update descriptions to reflect full block context Co-authored-by: Cursor <cursoragent@cursor.com>

Table payloads: - Replace pivot table split field with response.keyword (hour_of_day is a data-view runtime field unavailable via API) - Remove both advanced scenario API dropdowns (pivot, formula) - Add other_bucket, suggested_interval, range labels, alignment, and auto color where missing from examples - Fix weekly sales formula: remove filter field from formula metric (empty filter breaks time shift evaluation in Lens) - Fix bytes per file extension: add includes regex, other_bucket, rank_by, increase_accuracy, and percentage mode Formula metrics (all pages): - Remove "filter": {"expression": ""} from all formula metrics across tables, metric, and pie chart pages — Lens never adds this field to formula metrics and it silently breaks features like time shift Co-authored-by: Cursor <cursoragent@cursor.com>

- Add .github/scripts/verify-lens-api-examples.py: stdlib-only script that extracts every curl payload from the 13 chart files, strips callout markers, POSTs each to /api/visualizations, asserts 201, and deletes the test viz. Verified 43/43 pass against live Kibana. - Add maintenance comment to the examples section of each chart file pointing to the script for future re-verification. - Fix Vale: grey → gray (heat-map), vs → versus (heat-map), punctuation inside closing quotes (bar, pie), repeated "to" (metric, tables), "easy to X" rephrased (bar, heat-map, mosaic x2). Co-authored-by: Cursor <cursoragent@cursor.com>

github-actions · 2026-05-19T21:09:06Z

Elastic Docs AI PR menu

Check the box to run an AI review for this pull request.

Review docs changes (docs-review). Status: not started.

Powered by GitHub Agentic Workflows and docs-actions. For more information, reach out to the docs team.

leemthompo

Approving to unblock, haven't tested the API calls myself. I have two high-level feedbacks:

Ideally we'd have console and curl here particularly because it's Kibana APIs so folks might be more inclined to use the console
I agree with the decision to roll the API calls into dropdowns to save space, but I'd actually use a H3 heading to introduce each one of these so they're a bit more visible, to my eyes they don't stand out as much as they could, and be nice to see 'em in the On this page too

Otherwise, looks 💅

mdbirnstiehl

I think the content looks good, but it is hard to see the drop downs when scanning, especially with the applies_to tags coming first. Maybe there could be a way to use a heading/title so it might be a little more noticeable?

florent-leborgne · 2026-05-21T07:40:40Z

Thanks both! Point taken.

I'll add a console version that's actually quite mandatory IMO
For the visibility, they're not supposed to be that highly visible and rather fold under each example as an FYI. But since the 2 of you made this comment, I'll open an issue to re-consider this as it would actually require changing the structure of my examples a little bit.

Co-authored-by: Cursor <cursoragent@cursor.com>

…ed payload)" This reverts commit d5a5f78.

Each API dropdown now shows a Console tab (default) and a curl tab. Console tab uses `POST kbn://api/visualizations` format for direct use in Kibana Dev Tools. Both tabs carry the same callout annotations (stripped on copy by docs-builder). Dropdown fence bumped to 7 colons, tab-set to 5, tab-items to 4 (safe nesting for :::{note} blocks). Co-authored-by: Cursor <cursoragent@cursor.com>

Console JSON needs no shell-unescaping, simpler regex pattern. 40/40 payloads pass against live serverless 9.5.0. Co-authored-by: Cursor <cursoragent@cursor.com>

Console tab JSON for metric shift= formulas had '\''1w'\'' shell escapes copied from curl. Fixed in add-console-tabs.py (unescape at extraction time) and patched directly in metric-charts.md. 43/43 payloads now pass against live serverless 9.5.0. Co-authored-by: Cursor <cursoragent@cursor.com>

## Summary - Adds a **Console-first tab set** (Console + curl) to the "Recreate this dashboard with one API call" dropdown on the [Kibana data exploration learning tutorial](https://www.elastic.co/docs/explore-analyze/kibana-data-exploration-learning-tutorial) page, mirroring the pattern introduced for Lens chart pages in #5645. - Updates `.github/scripts/verify-dashboards-api-example.py` to extract the JSON payload from the `console` block instead of the `curl` block, consistent with the validation approach used in the Lens API examples script. ## Validation The updated script was run against a live Kibana serverless instance and confirmed that the Console payload creates a valid 11-panel dashboard. ## Test plan - [ ] Check that the dropdown renders with Console tab first and curl tab second - [ ] Check that all 11 callouts appear in both tabs with their numbered descriptions - [ ] Run `verify-dashboards-api-example.py` against a Kibana instance to confirm the Console payload is valid Made with [Cursor](https://cursor.com) Co-authored-by: Cursor <cursoragent@cursor.com>

florent-leborgne force-pushed the lens-api-chart-examples branch from 176d5d8 to b0225f6 Compare March 26, 2026 13:34

This was referenced Mar 26, 2026

[Lens] Improve Visualizations API documentation elastic/kibana#259842

Closed

[Docs][Visualizations API] Improve API reference docs elastic/kibana#236265

Closed

florent-leborgne linked an issue Apr 8, 2026 that may be closed by this pull request

Add Visualizations API payload examples to Lens chart type pages #5821

Closed

This was referenced Apr 16, 2026

Add Visualizations API payload examples to Lens chart type pages #5821

Closed

[Dashboards & Visualizations APIs] Full documentation for tech preview (9.4) #5823

Closed

florent-leborgne and others added 22 commits May 6, 2026 15:42

Use :applies_to: directive option syntax in dropdowns

386eaa4

Switch from code block applies_to inside dropdowns to the :applies_to: directive option syntax per docs-builder conventions. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Fix JSON quoting in formula examples

b382807

Remove bash-specific quote escaping from JSON payloads in cURL examples. Single quotes inside JSON strings are valid and don't need escaping. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Fix broken API dropdowns in metric chart examples

5233e60

Un-indent dropdown directives from definition lists to root level and add intro text with code callouts to the 3 example dropdowns. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

[Lens API] Update examples for size→limit and alignments→labels renames

88ce187

- terms size → limit across all 12 chart pages - alignments → labels/value with alignment: sub-field in metric-charts.md Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

style(lens-api): remove column-80 padding from callout markers

384bbc7

Co-authored-by: Cursor <cursoragent@cursor.com>

fix(lens-api): update waffle callout descriptions to match block-leve…

16c6ce9

…l placement Co-authored-by: Cursor <cursoragent@cursor.com>

fix(lens-api): move color block after filters array in waffle status …

d9ccebd

…breakdown Co-authored-by: Cursor <cursoragent@cursor.com>

Update treemap example UI bullets to reflect other bucket, percentage…

54b8626

…s, reversed gradient Co-authored-by: Cursor <cursoragent@cursor.com>

Fix Flights by carrier treemap: mode percentage, update UI bullets

52404b7

Co-authored-by: Cursor <cursoragent@cursor.com>

florent-leborgne force-pushed the lens-api-chart-examples branch from 7abc621 to 128c384 Compare May 19, 2026 21:08

florent-leborgne marked this pull request as ready for review May 19, 2026 21:11

florent-leborgne requested review from a team as code owners May 19, 2026 21:11

florent-leborgne requested a review from technige May 19, 2026 21:11

florent-leborgne commented May 20, 2026

View reviewed changes

Comment thread explore-analyze/visualize/lens.md

florent-leborgne commented May 20, 2026

View reviewed changes

Comment thread explore-analyze/visualize/lens.md

leemthompo approved these changes May 20, 2026

View reviewed changes

mdbirnstiehl approved these changes May 20, 2026

View reviewed changes

reakaleek approved these changes May 21, 2026

View reviewed changes

florent-leborgne force-pushed the lens-api-chart-examples branch 3 times, most recently from f87d68f to 21e1aed Compare May 21, 2026 12:15

test: add Console+curl tabs to first waffle dropdown (validated payload)

d5a5f78

Co-authored-by: Cursor <cursoragent@cursor.com>

florent-leborgne force-pushed the lens-api-chart-examples branch from 21e1aed to d5a5f78 Compare May 21, 2026 12:22

florent-leborgne and others added 7 commits May 21, 2026 14:35

Revert "test: add Console+curl tabs to first waffle dropdown (validat…

cdd0c55

…ed payload)" This reverts commit d5a5f78.

Merge branch 'main' into lens-api-chart-examples

c3ba7c8

refactor(verify): extract from Console tab instead of curl

53ce5ce

Console JSON needs no shell-unescaping, simpler regex pattern. 40/40 payloads pass against live serverless 9.5.0. Co-authored-by: Cursor <cursoragent@cursor.com>

Merge branch 'main' into lens-api-chart-examples

f46d4d7

Merge branch 'main' into lens-api-chart-examples

3904c5b

florent-leborgne enabled auto-merge (squash) May 21, 2026 13:36

florent-leborgne merged commit 075c16c into elastic:main May 21, 2026
7 checks passed

florent-leborgne mentioned this pull request May 21, 2026

Add Console tab to Dashboards API example (learning tutorial) #6626

Merged

3 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add Visualizations API examples to Lens chart pages#5645

Add Visualizations API examples to Lens chart pages#5645
florent-leborgne merged 41 commits into
elastic:mainfrom
florent-leborgne:lens-api-chart-examples

florent-leborgne commented Mar 26, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Mar 26, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Mar 26, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented May 19, 2026

Uh oh!

Uh oh!

Uh oh!

leemthompo left a comment •

edited

Loading

Uh oh!

mdbirnstiehl left a comment

Uh oh!

florent-leborgne commented May 21, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

florent-leborgne commented Mar 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What is included

Verification

Test plan

Visual validation (preview + live Kibana)

Uh oh!

github-actions Bot commented Mar 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔍 Preview links for changed docs

Uh oh!

github-actions Bot commented Mar 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Vale Linting Results

Uh oh!

github-actions Bot commented May 19, 2026

Elastic Docs AI PR menu

Uh oh!

Uh oh!

Uh oh!

leemthompo left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mdbirnstiehl left a comment

Choose a reason for hiding this comment

Uh oh!

florent-leborgne commented May 21, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

florent-leborgne commented Mar 26, 2026 •

edited

Loading

github-actions Bot commented Mar 26, 2026 •

edited

Loading

github-actions Bot commented Mar 26, 2026 •

edited

Loading

leemthompo left a comment •

edited

Loading