[Dashboards] Add programmatic creation docs and API examples#5770
Closed
florent-leborgne wants to merge 9 commits into
Closed
[Dashboards] Add programmatic creation docs and API examples#5770florent-leborgne wants to merge 9 commits into
florent-leborgne wants to merge 9 commits into
Conversation
4 tasks
Contributor
Contributor
✅ Vale Linting ResultsNo 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. |
3 tasks
7 tasks
6 tasks
Member
Author
|
Superseded by #6337. The original draft on this branch was based on the pre-restructure layout of the dashboards programmatic-creation docs and used the old API schema ( |
florent-leborgne
added a commit
that referenced
this pull request
May 13, 2026
…e Dashboards API (#6337) ## 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: 1. An HTML maintenance comment above the dropdown noting the spec source, last-verified commit, and pointer to the verification script. 2. `.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: ```bash 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 --------- Co-authored-by: Cursor <cursoragent@cursor.com> Co-authored-by: Benjamin Ironside Goldstein <91905639+benironside@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR adds documentation for creating Kibana dashboards and visualizations programmatically, as a companion to elastic/kibana#259842 (Visualizations API) and the pending Dashboards API Kibana PR.
New page:
explore-analyze/dashboards/create-programmatically.md— covers the Dashboards API, the Lens Visualizations API, the kibana-dashboards agent skill, and the upcoming Agent Builder dashboard tools. All API content is gated atpreview 9.4.Updated pages:
explore-analyze/dashboards/building.md— adds a pointer to the new programmatic pageexplore-analyze/dashboards/create-dashboard.md— adds a collapsible API dropdown after the agent-skill calloutexplore-analyze/kibana-data-exploration-learning-tutorial.md— adds a forward link in Step 3 and a full API dropdown at the end of the step, so learners can discover the API without skipping the manual tutorialNotes
applies_to: stack: preview 9.4 / serverless: previewkibana-dashboardsagent skill is already linked fromcreate-dashboard.mdvia the{agent-skill}directive; this PR adds a dedicated section in the new overview pageTest plan
applies_tobadges render correctly on all modified pagescreate-programmatically.mdin the nav