[Dashboards] Improve API documentation for public release#260969
Closed
florent-leborgne wants to merge 46 commits into
Closed
[Dashboards] Improve API documentation for public release#260969florent-leborgne wants to merge 46 commits into
florent-leborgne wants to merge 46 commits into
Conversation
Contributor
|
🤖 Jobs for this PR can be triggered through checkboxes. 🚧
ℹ️ To trigger the CI, please tick the checkbox below 👇
|
florent-leborgne
force-pushed
the
worktree-dashboards-api-docs
branch
from
8bb393d to
c2355d2
Compare
florent-leborgne
force-pushed
the
worktree-dashboards-api-docs
branch
3 times, most recently
from
7d8c0c8 to
19080b8
Compare
![macroscopeapp[bot]](https://avatars.githubusercontent.com/in/900172?s=60&v=4){kind=small}
florent-leborgne
force-pushed
the
worktree-dashboards-api-docs
branch
from
68fffde to
55ff3b5
Compare
3 tasks
7 tasks
Comment on lines
+25
to
+30
| @node scripts/strip_additional_properties.js oas_docs/output/kibana.yaml | ||
| @node scripts/strip_discriminators.js oas_docs/output/kibana.yaml | ||
| @node scripts/simplify_panel_vis.js oas_docs/output/kibana.yaml | ||
| @node scripts/strip_additional_properties.js oas_docs/output/kibana.serverless.yaml | ||
| @node scripts/strip_discriminators.js oas_docs/output/kibana.serverless.yaml | ||
| @node scripts/simplify_panel_vis.js oas_docs/output/kibana.serverless.yaml |
Contributor
There was a problem hiding this comment.
🔴 Critical oas_docs/makefile:25
The api-docs-postprocess target passes oas_docs/output/kibana.yaml to the Node scripts, but the Makefile runs from the oas_docs/ directory. This causes the scripts to look for oas_docs/oas_docs/output/kibana.yaml, which doesn't exist, resulting in file-not-found errors. The paths should be output/kibana.yaml and output/kibana.serverless.yaml, matching the directory-relative paths used in api-docs-overlay.
- @node scripts/strip_additional_properties.js oas_docs/output/kibana.yaml
- @node scripts/strip_discriminators.js oas_docs/output/kibana.yaml
- @node scripts/simplify_panel_vis.js oas_docs/output/kibana.yaml
- @node scripts/strip_additional_properties.js oas_docs/output/kibana.serverless.yaml
- @node scripts/strip_discriminators.js oas_docs/output/kibana.serverless.yaml
- @node scripts/simplify_panel_vis.js oas_docs/output/kibana.serverless.yaml
+ @node scripts/strip_additional_properties.js output/kibana.yaml
+ @node scripts/strip_discriminators.js output/kibana.yaml
+ @node scripts/simplify_panel_vis.js output/kibana.yaml
+ @node scripts/strip_additional_properties.js output/kibana.serverless.yaml
+ @node scripts/strip_discriminators.js output/kibana.serverless.yaml
+ @node scripts/simplify_panel_vis.js output/kibana.serverless.yaml🚀 Reply "fix it for me" or copy this AI Prompt for your agent:
In file oas_docs/makefile around lines 25-30:
The `api-docs-postprocess` target passes `oas_docs/output/kibana.yaml` to the Node scripts, but the Makefile runs from the `oas_docs/` directory. This causes the scripts to look for `oas_docs/oas_docs/output/kibana.yaml`, which doesn't exist, resulting in file-not-found errors. The paths should be `output/kibana.yaml` and `output/kibana.serverless.yaml`, matching the directory-relative paths used in `api-docs-overlay`.
- Add schema descriptions across dashboard_state_schemas.ts, meta_schemas.ts, and search/schemas.ts (periods, wording, typo fix: Collapsable -> Collapsible) - Add OAS overlay with tag description (get started, panel types, Lens embedding, ES|QL examples, controls, sections, filters, error handling), endpoint summaries, code samples, and examples - Add four YAML example files (create request/response, get, search) - Wire dashboards overlay into makefile for stateful and serverless Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…sion - Add `since: '9.4.0'` to availability in get_route_config.ts - Add per-route `description` to all 5 route handlers - Shorten update route summary; add read-modify-write guidance to description - Add `401: Unauthorized` response to all 5 route handlers - Improve `id` param description to reference create/search endpoints - Add descriptions to `total` and `page` in searchResponseBodySchema Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Update PUT summary from 'Update a dashboard' to 'Upsert dashboard' - Update PUT description to explain create-or-replace behavior Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Add note about Kibana sample datasets with guidance on adapting examples - Add Next steps section linking to Visualizations API and chart docs Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Split 'By value' and 'By reference' into #### sub-headings for scannability Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Override auto-generated schema names (kbn-dashboard-panel-*, kbn-as-code-*, kbn-es-query-*, etc.) with readable titles so oneOf/anyOf tabs in the API reference show 'Lens panel', 'Condition filter', 'Time range', etc. instead of raw package identifiers. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Label each code sample as 'Action - cURL' and 'Action - Console' so the dropdown clearly shows which format each sample uses. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…llout Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…titles - Fix all targets to use Kibana_HTTP_APIs_ prefix that appears in bundled output - Add titles for SLO embeddable schemas Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
The overlay JSONPath cannot target schema names with hyphens (bump-cli limitation). Add a Node.js post-processing script that replaces ugly auto-generated titles (options_list_control, kbn-as-code-meta, etc.) with human-readable ones after the OAS build. Also trim the overlay to only use description-based filter targets for the schemas where that approach works. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- dashboard_state_schemas.ts: generate readable panel titles from type names (e.g. 'options_list_control' → 'Options list control', 'esql_control' → 'ES|QL control'). Fix section title 'section' → 'Section'. - drilldowns/registry.ts: generate readable drilldown titles (e.g. 'dashboard_drilldown' → 'Dashboard drilldown'). - Remove post-processing script (no longer needed). - Trim overlay schema titles to only filter-condition schemas (shared packages where source changes are out of scope). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- filters-schema/filter.ts: replace constant-based titles (is, is_one_of, condition, group, dsl, spatial) with readable ones (Condition: is, Condition filter, Group filter, DSL filter, Spatial filter) - dashboard_state_schemas.ts: generate readable panel titles from type names (options_list_control → Options list control, etc.) - drilldowns/registry.ts: generate readable drilldown titles (dashboard_drilldown → Dashboard drilldown) - Section title: section → Section - Remove overlay schema title overrides (now handled in source) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
These files are regenerated by `make api-docs` and should not be committed. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…ntro These fields are already covered in the Dashboard-level filters section with a code example. Mentioning them before the developer has seen the request body provides no context. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
Adds a commented JSON skeleton showing how panels, sections, pinned_panels, filters, query, and time_range fit together. Gives developers a mental model before reading the detail sections. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
Convert the JSON skeleton to a nested bullet list that defines each top-level field, links to the relevant detail sections and the Create endpoint for a full example. Removes code block visual weight while preserving the structural overview. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
…ists with indented examples
…p additionalProperties - Add 403 Forbidden to error handling - Fix 404 note: specify applies to GET/PUT/DELETE only - Remove Next steps section (wasn't actionable) - Fix 'For a categorical breakdown' to be a bullet item - Strip additionalProperties:false from all schemas in overlay (renders as confusing 'Additional properties NOT allowed' in docs) Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
…r behavior Replace tautological 'Condition: is' descriptions with actionable text explaining what each operator matches. Add operator/value semantics to conditionSchema top-level description. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
…amples - Remove create_dashboard_request.yaml (single metric panel, too simple) - Add create_dashboard_simple_request.yaml: 3 panels (DSL line, ES|QL line, linked-from-library) - Add create_dashboard_complete_request.yaml: 2 metrics, 2 XY, 1 table, 2 sections, controls - Update create_dashboard_response.yaml: matches simple request, shows all default options and meta fields - Update overlay to reference both new examples - Simplify cURL/Console samples to minimal linked-from-library example Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
Replace the full lensApiState $ref with a lightweight description-only object to reduce bundle size for API reference rendering. Links to the Visualizations API for the full schema. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
- Replace kbn-prefixed meta.id values with readable kebab-case IDs across dashboard state, filter, and meta schemas - Add strip_additional_properties.js, strip_discriminators.js, simplify_panel_vis.js to oas_docs/scripts/ - Wire api-docs-postprocess target into makefile after api-docs-overlay Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
Reapply content improvements (descriptions, punctuation, wording) without changing meta.id values — those are internal identifiers that other code may depend on. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
…ansform When the Lens embeddable type is 'vis', the panel schema title transform produces 'Vis'. Add 'vis' → 'Visualization' to the replace chain so the tab label reads 'Visualization' instead. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
florent-leborgne
force-pushed
the
worktree-dashboards-api-docs
branch
from
d8a9c27 to
33de813
Compare
florent-leborgne
added a commit
that referenced
this pull request
Apr 9, 2026
Adds the tag description overlay for the Dashboards API, covering: - When to use this API vs the Visualizations API - Get started section with auth, CSRF, and spaces prerequisites - Runnable curl example using Kibana sample data - Dashboard structure model and grid explanation - Panel types reference table (content panels + observability types) - Embedding visualizations (inline vs linked from library) - ES|QL visualizations section - Makefile wired to apply the overlay in the pipeline Also adds meta.id to discriminated union entries in the controls schemas (controls_group_schema.ts, options_list_schema.ts) to unblock OAS generation for the /api/dashboards routes. This is the first in a series of focused PRs replacing #260969. Subsequent PRs will cover endpoint descriptions, request/response examples, and Bump rendering simplification. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
3 tasks
florent-leborgne
added a commit
that referenced
this pull request
Apr 13, 2026
) ## Summary This is the first in a series of focused PRs documenting the Dashboards API for public release. The initial investigation and content drafting was done in #260969 — this series breaks that work into smaller, reviewable chunks. ### This PR (1/4) — Introduction and get-started overlay Adds \`oas_docs/overlays/dashboards.overlays.yaml\`, which sets the tag description for the \`Dashboards\` API group. The overlay covers: - **When to use this API** vs the Visualizations API - **Get started** — auth, CSRF header, and spaces prerequisites, followed by a runnable \`curl\` example (ES|QL line chart using Kibana sample data) - **Dashboard structure** — data model (\`title\`, \`panels\`, \`pinned_panels\`, \`filters\`/\`query\`/\`time_range\`), 48-column grid explanation, and controls placement (sections vs pinned) - **Panel types** — all panel types in a single table (\`vis\`, \`discover_session\`, \`image\`, \`markdown\`, filter controls), observability types (SLO, Synthetics), and a callout for types not yet supported by the REST API (write operations return \`400\`; read operations strip the panel and return a warning) - **Embedding library items** — inline (full config in \`config\`) vs linked-from-library (\`config.ref_id\`) patterns, with working examples and a link to the Visualizations API for the full vis schema - **ES|QL visualizations** — how to use \`data_source.type: "esql"\` with metric and xy chart examples Also wires the overlay into the makefile pipeline. ### Upcoming PRs in this series | PR | Content | |----|---------| | 2/4 | Improved descriptions and titles for all 5 endpoints and their request/response schemas | | 3/4 | Request/response examples for each endpoint | | 4/4 | Bump rendering simplification (strip \`additionalProperties\`, schema ID cleanup, panel type title transforms) | ## Preview https://bump.sh/elastic/hub/elastic-apis/doc/dashboards-api-cleanup-intro-and-get-started/operation/operation-get-dashboards ## Test plan To preview locally: \`\`\`bash make -C oas_docs merge-api-docs-stateful make -C oas_docs api-docs-overlay make -C oas_docs api-docs-preview \`\`\` - [ ] \`make -C oas_docs merge-api-docs-stateful\` generates \`output/kibana.yaml\` with \`/api/dashboards\` endpoints present - [ ] \`make -C oas_docs api-docs-overlay\` applies the dashboards overlay without errors - [ ] \`make -C oas_docs api-docs-preview\` opens a Bump preview showing the Dashboards tag with the full introduction 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com> Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>
kibanamachine
added a commit
to kibanamachine/kibana
that referenced
this pull request
Apr 13, 2026
…tic#262396) ## Summary This is the first in a series of focused PRs documenting the Dashboards API for public release. The initial investigation and content drafting was done in elastic#260969 — this series breaks that work into smaller, reviewable chunks. ### This PR (1/4) — Introduction and get-started overlay Adds \`oas_docs/overlays/dashboards.overlays.yaml\`, which sets the tag description for the \`Dashboards\` API group. The overlay covers: - **When to use this API** vs the Visualizations API - **Get started** — auth, CSRF header, and spaces prerequisites, followed by a runnable \`curl\` example (ES|QL line chart using Kibana sample data) - **Dashboard structure** — data model (\`title\`, \`panels\`, \`pinned_panels\`, \`filters\`/\`query\`/\`time_range\`), 48-column grid explanation, and controls placement (sections vs pinned) - **Panel types** — all panel types in a single table (\`vis\`, \`discover_session\`, \`image\`, \`markdown\`, filter controls), observability types (SLO, Synthetics), and a callout for types not yet supported by the REST API (write operations return \`400\`; read operations strip the panel and return a warning) - **Embedding library items** — inline (full config in \`config\`) vs linked-from-library (\`config.ref_id\`) patterns, with working examples and a link to the Visualizations API for the full vis schema - **ES|QL visualizations** — how to use \`data_source.type: "esql"\` with metric and xy chart examples Also wires the overlay into the makefile pipeline. ### Upcoming PRs in this series | PR | Content | |----|---------| | 2/4 | Improved descriptions and titles for all 5 endpoints and their request/response schemas | | 3/4 | Request/response examples for each endpoint | | 4/4 | Bump rendering simplification (strip \`additionalProperties\`, schema ID cleanup, panel type title transforms) | ## Preview https://bump.sh/elastic/hub/elastic-apis/doc/dashboards-api-cleanup-intro-and-get-started/operation/operation-get-dashboards ## Test plan To preview locally: \`\`\`bash make -C oas_docs merge-api-docs-stateful make -C oas_docs api-docs-overlay make -C oas_docs api-docs-preview \`\`\` - [ ] \`make -C oas_docs merge-api-docs-stateful\` generates \`output/kibana.yaml\` with \`/api/dashboards\` endpoints present - [ ] \`make -C oas_docs api-docs-overlay\` applies the dashboards overlay without errors - [ ] \`make -C oas_docs api-docs-preview\` opens a Bump preview showing the Dashboards tag with the full introduction 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com> Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com> (cherry picked from commit d1ec64f)
kibanamachine
added a commit
that referenced
this pull request
Apr 13, 2026
…#262396) (#262853) # Backport This will backport the following commits from `main` to `9.4`: - [[Docs][Dashboards API] Add introduction and get-started overlay (#262396)](#262396) <!--- Backport version: 9.6.6 --> ### Questions ? Please refer to the [Backport tool documentation](https://github.com/sorenlouv/backport) <!--BACKPORT [{"author":{"name":"Florent LB","email":"florent.leborgne@elastic.co"},"sourceCommit":{"committedDate":"2026-04-13T16:25:28Z","message":"[Docs][Dashboards API] Add introduction and get-started overlay (#262396)\n\n## Summary\n\nThis is the first in a series of focused PRs documenting the Dashboards\nAPI for public release. The initial investigation and content drafting\nwas done in #260969 — this series breaks that work into smaller,\nreviewable chunks.\n\n### This PR (1/4) — Introduction and get-started overlay\n\nAdds \\`oas_docs/overlays/dashboards.overlays.yaml\\`, which sets the tag\ndescription for the \\`Dashboards\\` API group. The overlay covers:\n\n- **When to use this API** vs the Visualizations API\n- **Get started** — auth, CSRF header, and spaces prerequisites,\nfollowed by a runnable \\`curl\\` example (ES|QL line chart using Kibana\nsample data)\n- **Dashboard structure** — data model (\\`title\\`, \\`panels\\`,\n\\`pinned_panels\\`, \\`filters\\`/\\`query\\`/\\`time_range\\`), 48-column grid\nexplanation, and controls placement (sections vs pinned)\n- **Panel types** — all panel types in a single table (\\`vis\\`,\n\\`discover_session\\`, \\`image\\`, \\`markdown\\`, filter controls),\nobservability types (SLO, Synthetics), and a callout for types not yet\nsupported by the REST API (write operations return \\`400\\`; read\noperations strip the panel and return a warning)\n- **Embedding library items** — inline (full config in \\`config\\`) vs\nlinked-from-library (\\`config.ref_id\\`) patterns, with working examples\nand a link to the Visualizations API for the full vis schema\n- **ES|QL visualizations** — how to use \\`data_source.type: \"esql\"\\`\nwith metric and xy chart examples\n\nAlso wires the overlay into the makefile pipeline.\n\n### Upcoming PRs in this series\n\n| PR | Content |\n|----|---------|\n| 2/4 | Improved descriptions and titles for all 5 endpoints and their\nrequest/response schemas |\n| 3/4 | Request/response examples for each endpoint |\n| 4/4 | Bump rendering simplification (strip \\`additionalProperties\\`,\nschema ID cleanup, panel type title transforms) |\n\n## Preview\n\n\nhttps://bump.sh/elastic/hub/elastic-apis/doc/dashboards-api-cleanup-intro-and-get-started/operation/operation-get-dashboards\n\n## Test plan\n\nTo preview locally:\n\\`\\`\\`bash\nmake -C oas_docs merge-api-docs-stateful\nmake -C oas_docs api-docs-overlay\nmake -C oas_docs api-docs-preview\n\\`\\`\\`\n\n- [ ] \\`make -C oas_docs merge-api-docs-stateful\\` generates\n\\`output/kibana.yaml\\` with \\`/api/dashboards\\` endpoints present\n- [ ] \\`make -C oas_docs api-docs-overlay\\` applies the dashboards\noverlay without errors\n- [ ] \\`make -C oas_docs api-docs-preview\\` opens a Bump preview showing\nthe Dashboards tag with the full introduction\n\n🤖 Generated with [Claude Code](https://claude.com/claude-code)\n\n---------\n\nCo-authored-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>\nCo-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>","sha":"d1ec64fb0ca0d93169a3bd6739c45f41ce02ce64","branchLabelMapping":{"^v9.5.0$":"main","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["Team:Docs","release_note:skip","docs","APIDocs","backport:version","v9.4.0","v9.5.0"],"title":"[Docs][Dashboards API] Add introduction and get-started overlay","number":262396,"url":"https://github.com/elastic/kibana/pull/262396","mergeCommit":{"message":"[Docs][Dashboards API] Add introduction and get-started overlay (#262396)\n\n## Summary\n\nThis is the first in a series of focused PRs documenting the Dashboards\nAPI for public release. The initial investigation and content drafting\nwas done in #260969 — this series breaks that work into smaller,\nreviewable chunks.\n\n### This PR (1/4) — Introduction and get-started overlay\n\nAdds \\`oas_docs/overlays/dashboards.overlays.yaml\\`, which sets the tag\ndescription for the \\`Dashboards\\` API group. The overlay covers:\n\n- **When to use this API** vs the Visualizations API\n- **Get started** — auth, CSRF header, and spaces prerequisites,\nfollowed by a runnable \\`curl\\` example (ES|QL line chart using Kibana\nsample data)\n- **Dashboard structure** — data model (\\`title\\`, \\`panels\\`,\n\\`pinned_panels\\`, \\`filters\\`/\\`query\\`/\\`time_range\\`), 48-column grid\nexplanation, and controls placement (sections vs pinned)\n- **Panel types** — all panel types in a single table (\\`vis\\`,\n\\`discover_session\\`, \\`image\\`, \\`markdown\\`, filter controls),\nobservability types (SLO, Synthetics), and a callout for types not yet\nsupported by the REST API (write operations return \\`400\\`; read\noperations strip the panel and return a warning)\n- **Embedding library items** — inline (full config in \\`config\\`) vs\nlinked-from-library (\\`config.ref_id\\`) patterns, with working examples\nand a link to the Visualizations API for the full vis schema\n- **ES|QL visualizations** — how to use \\`data_source.type: \"esql\"\\`\nwith metric and xy chart examples\n\nAlso wires the overlay into the makefile pipeline.\n\n### Upcoming PRs in this series\n\n| PR | Content |\n|----|---------|\n| 2/4 | Improved descriptions and titles for all 5 endpoints and their\nrequest/response schemas |\n| 3/4 | Request/response examples for each endpoint |\n| 4/4 | Bump rendering simplification (strip \\`additionalProperties\\`,\nschema ID cleanup, panel type title transforms) |\n\n## Preview\n\n\nhttps://bump.sh/elastic/hub/elastic-apis/doc/dashboards-api-cleanup-intro-and-get-started/operation/operation-get-dashboards\n\n## Test plan\n\nTo preview locally:\n\\`\\`\\`bash\nmake -C oas_docs merge-api-docs-stateful\nmake -C oas_docs api-docs-overlay\nmake -C oas_docs api-docs-preview\n\\`\\`\\`\n\n- [ ] \\`make -C oas_docs merge-api-docs-stateful\\` generates\n\\`output/kibana.yaml\\` with \\`/api/dashboards\\` endpoints present\n- [ ] \\`make -C oas_docs api-docs-overlay\\` applies the dashboards\noverlay without errors\n- [ ] \\`make -C oas_docs api-docs-preview\\` opens a Bump preview showing\nthe Dashboards tag with the full introduction\n\n🤖 Generated with [Claude Code](https://claude.com/claude-code)\n\n---------\n\nCo-authored-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>\nCo-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>","sha":"d1ec64fb0ca0d93169a3bd6739c45f41ce02ce64"}},"sourceBranch":"main","suggestedTargetBranches":["9.4"],"targetPullRequestStates":[{"branch":"9.4","label":"v9.4.0","branchLabelMappingKey":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"main","label":"v9.5.0","branchLabelMappingKey":"^v9.5.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/262396","number":262396,"mergeCommit":{"message":"[Docs][Dashboards API] Add introduction and get-started overlay (#262396)\n\n## Summary\n\nThis is the first in a series of focused PRs documenting the Dashboards\nAPI for public release. The initial investigation and content drafting\nwas done in #260969 — this series breaks that work into smaller,\nreviewable chunks.\n\n### This PR (1/4) — Introduction and get-started overlay\n\nAdds \\`oas_docs/overlays/dashboards.overlays.yaml\\`, which sets the tag\ndescription for the \\`Dashboards\\` API group. The overlay covers:\n\n- **When to use this API** vs the Visualizations API\n- **Get started** — auth, CSRF header, and spaces prerequisites,\nfollowed by a runnable \\`curl\\` example (ES|QL line chart using Kibana\nsample data)\n- **Dashboard structure** — data model (\\`title\\`, \\`panels\\`,\n\\`pinned_panels\\`, \\`filters\\`/\\`query\\`/\\`time_range\\`), 48-column grid\nexplanation, and controls placement (sections vs pinned)\n- **Panel types** — all panel types in a single table (\\`vis\\`,\n\\`discover_session\\`, \\`image\\`, \\`markdown\\`, filter controls),\nobservability types (SLO, Synthetics), and a callout for types not yet\nsupported by the REST API (write operations return \\`400\\`; read\noperations strip the panel and return a warning)\n- **Embedding library items** — inline (full config in \\`config\\`) vs\nlinked-from-library (\\`config.ref_id\\`) patterns, with working examples\nand a link to the Visualizations API for the full vis schema\n- **ES|QL visualizations** — how to use \\`data_source.type: \"esql\"\\`\nwith metric and xy chart examples\n\nAlso wires the overlay into the makefile pipeline.\n\n### Upcoming PRs in this series\n\n| PR | Content |\n|----|---------|\n| 2/4 | Improved descriptions and titles for all 5 endpoints and their\nrequest/response schemas |\n| 3/4 | Request/response examples for each endpoint |\n| 4/4 | Bump rendering simplification (strip \\`additionalProperties\\`,\nschema ID cleanup, panel type title transforms) |\n\n## Preview\n\n\nhttps://bump.sh/elastic/hub/elastic-apis/doc/dashboards-api-cleanup-intro-and-get-started/operation/operation-get-dashboards\n\n## Test plan\n\nTo preview locally:\n\\`\\`\\`bash\nmake -C oas_docs merge-api-docs-stateful\nmake -C oas_docs api-docs-overlay\nmake -C oas_docs api-docs-preview\n\\`\\`\\`\n\n- [ ] \\`make -C oas_docs merge-api-docs-stateful\\` generates\n\\`output/kibana.yaml\\` with \\`/api/dashboards\\` endpoints present\n- [ ] \\`make -C oas_docs api-docs-overlay\\` applies the dashboards\noverlay without errors\n- [ ] \\`make -C oas_docs api-docs-preview\\` opens a Bump preview showing\nthe Dashboards tag with the full introduction\n\n🤖 Generated with [Claude Code](https://claude.com/claude-code)\n\n---------\n\nCo-authored-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>\nCo-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>","sha":"d1ec64fb0ca0d93169a3bd6739c45f41ce02ce64"}}]}] BACKPORT--> Co-authored-by: Florent LB <florent.leborgne@elastic.co> Co-authored-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
Member
Author
|
Superseded by a series of smaller PRs |
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
2 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
Improves documentation for the Dashboards API ahead of its public release in 9.4.
Note: The route flip to
access: 'public'is handled separately in #256302. This PR focuses on documentation only.Companion to: elastic/docs-content#5770 (new "Create programmatically" page + tutorial dropdowns)
Related: #259842 (Visualizations API docs, same pattern)
Documentation strategy
Users discovering the Dashboards API will follow one of three paths. Our changes ensure each path leads to success:
Path 1: Start from the API reference
A user lands on the API docs and wants to create a dashboard programmatically — to automate provisioning, build dashboards as code, or embed them in a workflow. The tag intro orients them: what panels are, how to embed visualizations inline or linked from library, how ES|QL visualizations differ from DSL ones, and how controls and sections compose a dashboard. They pick an endpoint, see a concise description, copy a code sample, and it works out of the box with sample data.
Path 2: Start from the narrative docs
A user is reading the "Learn Kibana analytics" tutorial or the "Create dashboard" page and notices a "Create this programmatically" dropdown. They expand it, see the equivalent API payload, and understand they can automate what they just built in the UI. They follow the link to the new "Create dashboards and visualizations programmatically" page, which covers the Dashboards API, the Visualizations API, agent skills, and agent builder tools in one place.
Path 3: Explore the schema
A user browses the request body schema to understand all available fields — panel grid positions, section structure, control types, filter syntax. Every parameter they encounter has a clear, actionable description explaining what it does and how it relates to other fields.
Changes in this PR (Kibana)
API reference intro (overlay)
config.attributes) vs linked from library (saved object ID)data_source) and xy chart (data_sourceinside each layer)pinned_panelsvs inside a section'spanelsarrayEndpoint descriptions and route improvements (route files)
descriptionfield on all 5 endpoints (create, read, search, update, delete)since: '9.4.0'inavailabilityso docs render "Technical Preview; added in 9.4.0" badges401: Unauthorizedresponse on all 5 endpointsidparam description updated to reference create/search endpointsSchema property descriptions (~55 fields across dashboard and shared schemas)
Improved descriptions with trailing periods, defaults, and valid values:
dashboard_state_schemas.ts— trailing periods onpanelGridSchemafields, typo fix (Collapsable→Collapsible), wording improvements (auto_apply_filters,description,filters,panels,project_routing,tags,title), human-readable panel type titlessearch/schemas.ts— descriptions onpage,per_page,query(with ES simple_query_string link),totalas-code/shared-schemas(asCodeMetaSchema) — descriptions on all 7 meta fields:managed,created_at,created_by,updated_at,updated_by,version,owneras-code/filters-schema— ~21 field descriptions improved across filter base properties, range fields, condition values, DSL/spatial types, and union discriminator (with defaults, valid types, and examples)vispanel type alignment"type": "lens"to"type": "vis"per [dashboards as code] rename lens and visualization embeddable types #260040data_sourcerename alignmentdataset→data_source,type: index→type: data_view_spec,index→index_pattern(per [Lens as Code] Use as code dataView schema #260914)/api/dashboards/{id}to/api/dashboardsFilter schema title improvements
titlevalues changed from enum constants to human-readable strings ("Condition: is","Condition filter","DSL filter", etc.) for readable oneOf labels in the API referenceExamples and code samples (overlay + YAML files)
Makefile
Changes in companion PR (elastic/docs-content#5770)
New page: "Create dashboards and visualizations programmatically"
applies_to: { stack: preview 9.4, serverless: preview }"Learn Kibana analytics" tutorial
"Create dashboard" page
Integration test findings and validation scripts
All examples were validated against a Kibana main branch snapshot (with routes temporarily flipped to public locally). Full findings (panel shape, ES|QL support,
access_controlon PUT, controls behavior, null rejection) and validation scripts are in the companion gist:https://gist.github.com/florent-leborgne/0dff866e89ff6c2bfc974ee4d3d2587e
Key items for the team:
config.attributeswrapper is required for inline Lens panels —config.typeorconfig.data_sourcedirectly returns 400metriccharts viaesqlMetricState(verified incharts/metric.ts)xycharts:data_sourcemust be inside eachlayers[]entry, not at the top levelaccess_controlis accepted onPOSTonly — sending it onPUTreturns 400nullvalues are rejected for optional fields — omit them insteadpinned_panelsfor dashboard-wide effect, or inside a section'spanelsarray for section-scoped filteringPreview
Latest combined preview (Dashboards + Visualizations): https://bump.sh/preview/111e0488-c656-40cb-8379-4d50cf4b1554
Checklist