[Dashboards] Recreate the data-exploration tutorial dashboard with the Dashboards API by florent-leborgne · Pull Request #6337 · elastic/docs-content

florent-leborgne · 2026-05-06T18:41:08Z

Summary

I want to introduce the API in the Kibana analytics learning tutorial. The idea is:
-> new users try kibana, learn about discover, dashboards, and the paths between the 2, they end up with a dashboard that they understand, then we show that this is also all reproducible using the API, once they have the main concepts of dashboards in mind.

Preview: https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/6337/explore-analyze/kibana-data-exploration-learning-tutorial

Closes the remaining checklist items of #5822 by adding an ## (Optional) Recreate the dashboard with the API section to explore-analyze/kibana-data-exploration-learning-tutorial.md. The first checklist item (the Create programmatically overview page) was completed by #5927.

The section is placed after Step 4 (Share), once the four-step tutorial narrative is complete, so it reads as a capstone rather than interrupting the step sequence. It carries applies_to badges (stack: preview 9.4+, serverless: preview) and a two-sentence intro, then collapses the full payload into a Recreate this dashboard with one API call dropdown.

The dropdown contains one curl POST to /api/dashboards that recreates the finished tutorial dashboard, including the optional panels suggested across Step 3 (extra metrics, response size over time, pie, treemap). Eleven explicit <n> code callouts anchor each JSON panel to the tutorial sub-step that introduced it; the numbered list after the curl block highlights the non-obvious API patterns (breakdown_by, reference_lines as a separate layer, ES|QL column references in xy x/y, rows vs metrics in ES|QL data tables, pie/treemap with metrics + group_by).

The page from #5927 already covers the API payload dropdown on the Create dashboard page (item 2 of #5822) via the existing New ways to create dashboards tip, so no edit is needed on create-dashboard.md.

This supersedes #5770, which was drafted before the spec restructure landed.

Verification

The Dashboards API is in technical preview (x-state: Technical Preview; added in 9.4.0), so the embedded payload was rebuilt against the current dashboards-api-spec (commit 84120e3); the old draft used the pre-restructure schema (type: lens, dataset, operation-style x/y) which the API no longer accepts.

The current payload was POSTed end-to-end against a live serverless instance. HTTP 201, 11 panels created, panel set matches a fresh export from a manually-built tutorial dashboard. Schema details verified directly against openapi/kibana-openapi.yaml:

panel-level type vis with config.type (not lens)
data_source with data_view_spec or esql (not dataset)
ES|QL chart layers reference query result columns via x.column / y[].column
xy bar default is bar_stacked (matches Lens)
reference lines as a sibling layer of type reference_lines with thresholds
metric secondary with time_shift + compare
ES|QL data_table with rows (categorical) and metrics (values)

Maintenance

To keep the example honest as the schema evolves, this PR also adds:

An HTML maintenance comment above the dropdown noting the spec source, last-verified commit, and pointer to the verification script.
.github/scripts/verify-dashboards-api-example.py, a stdlib-only Python script that extracts the curl JSON from the markdown, strips <n> callouts, POSTs it against \${KIBANA_URL} with \${API_KEY}, asserts HTTP 201 + the expected panel count, then deletes the test dashboard.

Anyone editing the example can run:

KIBANA_URL=… API_KEY=… python3 .github/scripts/verify-dashboards-api-example.py

The script is designed to be promoted to a workflow_dispatch GitHub Action against a CI Kibana later if we want continuous drift detection.

Test plan

Preview renders the optional section after Step 4, with the dropdown collapsed by default
applies_to badges on the section show preview / 9.4+
Code callouts <1>–<11> render as styled badges aligned with the corresponding panel titles/labels
All links resolve: dashboards/create-dashboards-programmatically.md, the in-page #explore-data-in-discover anchor, the external Dashboards API reference
python3 .github/scripts/verify-dashboards-api-example.py exits 0 against a Kibana 9.4+ instance with the sample logs dataset installed
Vale passes

Adds a collapsible "Recreate this dashboard with one API call" dropdown at the end of Step 3 of the Kibana data exploration learning tutorial. The dropdown contains a single curl POST to /api/dashboards that recreates the finished tutorial dashboard, including the optional panels suggested in each sub-step (extra metrics, response size over time, pie, treemap). Eleven explicit code callouts anchor each panel to the tutorial sub-step that introduced it. The numbered list after the curl block calls out the non-obvious API patterns: breakdown_by for split-by-host, reference_lines as a separate layer, ES|QL column references in xy x/y, rows vs metrics in ES|QL data tables, and pie/treemap with metrics + group_by. The payload is gated at stack: preview 9.4+ / serverless: preview, matching the rest of the Dashboards API documentation. An HTML maintenance comment above the dropdown points editors at the verification script and notes the spec source and date last verified, so the example can be re-checked when the schema evolves. Closes the second and third checklist items of #5822 (API payload on the tutorial). Item one was completed by #5927. Co-authored-by: Cursor <cursoragent@cursor.com>

Adds .github/scripts/verify-dashboards-api-example.py, a stdlib-only Python script that extracts the curl POST payload from the data exploration tutorial, strips docs-builder code callouts, and posts the result against a live Kibana to assert it still creates a dashboard with the expected panel count. The Dashboards API is in technical preview, so its schema can change between releases. The script gives editors a five-second feedback loop for verifying the embedded example before merging payload changes: KIBANA_URL=... API_KEY=... \ python3 .github/scripts/verify-dashboards-api-example.py The script is parameterized on the markdown path and supports a --keep flag for inspecting the resulting dashboard, otherwise the test dashboard is deleted on success. Designed to be promoted to a workflow_dispatch GitHub Action against a CI Kibana later if needed. Co-authored-by: Cursor <cursoragent@cursor.com>

github-actions · 2026-05-06T18:41:42Z

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.

github-actions · 2026-05-06T18:43:20Z

✅ Vale Linting Results

No issues found on modified lines!

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.

github-actions · 2026-05-06T18:43:20Z

🔍 Preview links for changed docs

explore-analyze/kibana-data-exploration-learning-tutorial.md

The repo style guide forbids em dashes (use a comma, a colon, or rewrite). The 11-item list mapping each panel to its tutorial sub-step used the "**Title** — description" pattern, which is more naturally written as "**Title**: description" anyway. Co-authored-by: Cursor <cursoragent@cursor.com>

Each numbered explanation now links the bold sub-step name to the auto-generated anchor on the matching {step} directive, so readers can jump straight from a callout description back to the procedure that introduced the panel. Items 2-4 (the optional metrics dropdown) point at the parent metric step since {dropdown} directives don't have their own anchors. Co-authored-by: Cursor <cursoragent@cursor.com>

Bold + link is visual overkill; the link styling already makes the sub-step name stand out. Co-authored-by: Cursor <cursoragent@cursor.com>

Two changes to the verification script: 1. Each `raise SystemExit` site now has a short comment explaining what condition triggers it and what the error message means, with a numbered cross-reference to a new "Failure modes" section in the module docstring. So an editor reading the script (or hitting a failure) gets the full context without leaving the file. 2. When the API returns 201 but the stored dashboard has a different panel count from the request, the script now identifies which panels the server dropped by their grid position and prints `type` and `config.type` for each. Previously the message reported only the count mismatch, leaving the editor to find the dropped panel by eyeballing 11 visualization configs. Co-authored-by: Cursor <cursoragent@cursor.com>

benironside

Very cool idea, clean execution. I didn't test the API call, and I am not a dashboards expert, but everything makes sense, the links work, and the explanation is clear. Nice use of numbered code references.

Co-authored-by: Benjamin Ironside Goldstein <91905639+benironside@users.noreply.github.com>

Promotes the 'Recreate this dashboard with one API call' dropdown into a proper ## section so it appears in the page TOC. Adds a two-sentence intro and applies_to badges at the section level; the full curl payload and annotated callout list remain inside the collapsed dropdown. Co-authored-by: Cursor <cursoragent@cursor.com>

- Use fenced {applies_to} block (not inline role) for section-level tag - Remove directional "above" — now references "this tutorial" - Add (Optional) to heading to match the page's tutorial conventions Co-authored-by: Cursor <cursoragent@cursor.com>

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

Places the optional API section after the tutorial's four numbered steps are complete, so it reads as a capstone rather than interrupting the Step 3 → Step 4 sequence. Co-authored-by: Cursor <cursoragent@cursor.com>

## 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 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 #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 - [x] All 43 JSON payloads parse successfully (0 errors in dry-run) - [x] 43/43 payloads create visualizations against a live 9.5.0 serverless instance - [x] Vale linting passes (0 errors, 0 warnings, 0 suggestions) ### Visual validation (preview + live Kibana) - [x] Area charts (2 examples) - [x] Bar charts (4 examples) - [x] Gauge charts (4 examples) - [x] Heat map charts (3 examples) - [x] Line charts (2 examples) - [x] Metric charts (5 examples) - [x] Mosaic charts (2 examples) - [x] Pie charts (6 examples) - [x] Region map charts (3 examples) - [x] Table (4 examples) - [x] Tag cloud charts (2 examples) - [x] Treemap charts (3 examples) - [x] Waffle charts (3 examples) --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Co-authored-by: Cursor <cursoragent@cursor.com>

florent-leborgne and others added 2 commits May 6, 2026 20:40

florent-leborgne requested review from a team as code owners May 6, 2026 18:41

florent-leborgne requested a review from Mpdreamz May 6, 2026 18:41

florent-leborgne mentioned this pull request May 6, 2026

[Dashboards] Add programmatic creation docs and API examples #5770

Closed

4 tasks

florent-leborgne and others added 4 commits May 6, 2026 21:06

Remove bold from sub-step links in callout list

d54813e

Bold + link is visual overkill; the link styling already makes the sub-step name stand out. Co-authored-by: Cursor <cursoragent@cursor.com>

florent-leborgne requested review from ThomThomson and teresaalvarezsoler May 8, 2026 09:59

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

Add Dashboards API documentation to dashboards narrative docs #5822

Closed

3 tasks

benironside approved these changes May 12, 2026

View reviewed changes

Comment thread explore-analyze/kibana-data-exploration-learning-tutorial.md

florent-leborgne and others added 2 commits May 12, 2026 14:13

Update explore-analyze/kibana-data-exploration-learning-tutorial.md

7672ec5

Co-authored-by: Benjamin Ironside Goldstein <91905639+benironside@users.noreply.github.com>

Merge branch 'main' into docs-issue-5822-tutorial-api

09e60de

reakaleek approved these changes May 13, 2026

View reviewed changes

florent-leborgne and others added 4 commits May 13, 2026 10:35

Replace em dashes with commas in API section intro

720394f

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

Move API section after Step 4 to complete tutorial narrative

46b1389

Places the optional API section after the tutorial's four numbered steps are complete, so it reads as a capstone rather than interrupting the Step 3 → Step 4 sequence. Co-authored-by: Cursor <cursoragent@cursor.com>

florent-leborgne commented May 13, 2026

View reviewed changes

Comment thread explore-analyze/kibana-data-exploration-learning-tutorial.md Outdated

Apply suggestion from @florent-leborgne

db47b3d

florent-leborgne commented May 13, 2026

View reviewed changes

Comment thread explore-analyze/kibana-data-exploration-learning-tutorial.md Outdated

florent-leborgne added 2 commits May 13, 2026 11:51

Apply suggestion from @florent-leborgne

8d180ab

Merge branch 'main' into docs-issue-5822-tutorial-api

6f8f19a

florent-leborgne enabled auto-merge (squash) May 13, 2026 09:55

florent-leborgne merged commit a3ec929 into main May 13, 2026
11 of 12 checks passed

florent-leborgne deleted the docs-issue-5822-tutorial-api branch May 13, 2026 09:56

github-actions Bot deployed to docs-preview May 13, 2026 09:59 View deployment

florent-leborgne mentioned this pull request May 19, 2026

Add Visualizations API examples to Lens chart pages #5645

Merged

16 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Dashboards] Recreate the data-exploration tutorial dashboard with the Dashboards API#6337

[Dashboards] Recreate the data-exploration tutorial dashboard with the Dashboards API#6337
florent-leborgne merged 15 commits into
mainfrom
docs-issue-5822-tutorial-api

florent-leborgne commented May 6, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented May 6, 2026

Uh oh!

github-actions Bot commented May 6, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented May 6, 2026 •

edited

Loading

Uh oh!

benironside left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

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

Uh oh!

Summary

Verification

Maintenance

Test plan

Uh oh!

github-actions Bot commented May 6, 2026

Elastic Docs AI PR menu

Uh oh!

github-actions Bot commented May 6, 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 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔍 Preview links for changed docs

Uh oh!

benironside left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

florent-leborgne commented May 6, 2026 •

edited

Loading

github-actions Bot commented May 6, 2026 •

edited

Loading

github-actions Bot commented May 6, 2026 •

edited

Loading