[Docs][Dashboards] Add 'Create programmatically' overview page#5927
Merged
Conversation
Contributor
🔍 Preview links for changed docs |
Contributor
Vale Linting ResultsSummary: 1 warning found
|
| File | Line | Rule | Message |
|---|---|---|---|
| explore-analyze/dashboards/create-dashboard.md | 19 | Elastic.QuotesPunctuation | Place punctuation inside closing quotation marks. |
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.
Member
FYI renaming that to |
5 tasks
leemthompo
reviewed
Apr 16, 2026
This was referenced Apr 16, 2026
Adds a new overview page to help users choose between the Dashboards API, Lens Visualizations API, Agent Builder chat, and the Kibana dashboards agent skill when creating dashboards outside the UI. Replaces the link-farm approach with a decision table and substantive per-option guidance including use cases, output types, and key limitations. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
- Remove 'Lens' branding throughout; use 'Visualizations API' and 'visualizations' - Fix em dashes: use commas or new sentences instead - Remove 'currently', 'straightforward', 'out of the box', 'choose to save' - Fix ambiguous pronoun antecedent in agent skill section - Fix 'without touching the UI' → 'produce dashboards from natural language instructions' - Fix in-memory sentence structure (em dash → two sentences) Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
- Fix two broken internal links: /explore-analyze/query-your-data-with-esql.md
→ /explore-analyze/query-filter/languages/esql-kibana.md
- Replace bare 'Kibana' with {{product.kibana}} substitution (Vale warning)
Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
… fix applies_to syntax - Rename create-programmatically.md → create-dashboards-programmatically.md for a clearer URL - Update page anchor, toc.yml, and building.md link accordingly - Fix applies_to syntax: preview 9.4 → preview 9.4+ (explicit "and later" form) Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
building.md: - Remove standalone 'Create programmatically' section; replace with a single inline sentence pointing to the new page — the page now leads naturally to both UI and programmatic paths without the section feeling bolted on create-dashboards-programmatically.md: - Rewrite intro: lead with benefit, not "this is useful when..." - Table: rename columns to 'When to choose this' / 'What you get'; tighten row descriptions from the user's perspective; clarify agent skill output; add MCP server to Agent Builder row - Prose: active voice throughout; remove padding; fold in MCP server mention for Agent Builder; cleaner Visualizations API section intro Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
- Two 'via' → 'using' (Elastic.Latinisms rule)
- Two bare 'Kibana' → '{{product.kibana}}' substitution (table row + section heading)
- Remove 'chatbot' (Elastic.Spelling flag) — simplified to 'AI application'
Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
florent-leborgne
force-pushed
the
dashboards-create-programmatically
branch
from
92ce310 to
f40d67f
Compare
leemthompo
reviewed
Apr 16, 2026
Co-authored-by: Liam Thompson <leemthompo@gmail.com>
leemthompo
approved these changes
Apr 16, 2026
Co-authored-by: Liam Thompson <leemthompo@gmail.com>
- building.md: add 3-path decision table (UI / programmatic / AI); type: overview - create-dashboard.md: rename to 'Create a dashboard from the UI'; add navigation_title, type: how-to; replace agent-skill callout with a 9.4+/serverless tip linking to the two new creation paths - create-dashboards-programmatically.md: scope to APIs only (Dashboards API + Visualizations API); move AI content to new page; add navigation_title - create-dashboards-using-ai.md: new overview page for Agent Builder and the Kibana dashboards agent skill (content split from programmatic page) - toc.yml: add create-dashboards-using-ai.md under building.md Made-with: Cursor
Made-with: Cursor
Member
Author
|
@leemthompo thx for your earlier reviews - I updated the structure after chatting with Teresa - so feel free to take another look |
leemthompo
approved these changes
Apr 20, 2026
Member
leemthompo
left a comment
leemthompo
left a comment
There was a problem hiding this comment.
IA refactor makes sense! Looks even better to me.
…cs host Made-with: Cursor
Contributor
Elastic Docs AI PR menuCheck the box to run an AI review for this pull request.
Powered by GitHub Agentic Workflows and docs-actions. For more information, reach out to the docs team. |
… dashboards-api-spec
This was referenced May 6, 2026
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
3 participants
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
Restructures the dashboard creation docs into three focused pages under a unified Building dashboards section landing.
Before: A single "Create programmatically" page covering APIs and AI tools together, with no overview linking all creation paths.
After:
building.md— Section landing with a 3-path decision table (UI / programmatic / AI), helping users choose the right approach before they dive in. Each row links to a dedicated page.create-dashboard.md— Renamed to "Create a dashboard from the UI". Adds `navigation_title: Create from the UI` for a shorter nav label, `type: how-to`, and a 9.4+/serverless tip surfacing the two new paths for users who land here out of habit.create-dashboards-programmatically.md— Scoped to REST APIs only (Dashboards API + Visualizations API). AI content moved to the new page. Adds `navigation_title: Create programmatically`.create-dashboards-using-ai.md— New overview page for Agent Builder (chat UI, Chat API, MCP server) and the Kibana dashboards agent skill. Adds `navigation_title: Create using AI`.toc.yml— Adds the new AI page under `building.md`.Design rationale
Each page now matches a single user intent: UI builders, API/DevOps engineers, and AI tool builders each land on content written for them. The decision table in `building.md` serves explorers who aren't sure which path to take. Cross-references between pages are symmetric: each child page tips to the other path.
Files changed
Test plan