[Docs][Visualizations API] Add request and response examples for all 5 endpoints by florent-leborgne · Pull Request #262874 · elastic/kibana

florent-leborgne · 2026-04-13T18:01:49Z

Summary

Adds cURL and Console code samples and inlined response examples to all 5 Visualizations API endpoints.

Code samples (`x-codeSamples`)

Endpoint	Examples
`POST /api/visualizations`	Metric chart (`data_view_spec`); XY line chart; Pie/donut chart; Data table; Metric chart (`data_view_reference`)
`GET /api/visualizations`	Search visualizations
`GET /api/visualizations/{id}`	Get a visualization
`PUT /api/visualizations/{id}`	Update a visualization
`DELETE /api/visualizations/{id}`	Delete a visualization

Each example has a cURL and Console variant. The esql data source is not covered — it is not yet supported by the Visualizations API (returns 400); use the Dashboards API for ES|QL visualizations.

Response examples

Endpoint	Response code	Named examples
`POST /api/visualizations`	201	createMetricVisualizationResponse, createXYVisualizationResponse, createPieVisualizationResponse, createDataTableVisualizationResponse, createDataViewReferenceResponse
`GET /api/visualizations`	200	searchVisualizationsResponse (two items: metric + XY)
`GET /api/visualizations/{id}`	200	getVisualizationResponse (metric)
`PUT /api/visualizations/{id}`	200	updateVisualizationResponse (metric)

All payloads tested against a live Kibana 9.4.0 instance using the Kibana sample logs dataset.

Preview

https://bump.sh/elastic/hub/elastic-apis/doc/visualizations-api-cleanup-intro-get-started/group/endpoint-visualizations

Test plan

Verify code samples appear in the upper-right dropdown for each endpoint
Verify response examples appear in the Responses section with correct named tabs
Confirm all JSON in code samples is fully expanded (no inline objects)

🤖 Generated with Claude Code

teresaalvarezsoler

This looks good to me, thanks @florent-leborgne

elasticmachine · 2026-04-14T10:11:21Z

Pinging @elastic/experience-docs (Team:Docs)

…r all 5 endpoints Adds request code samples (cURL + Console) and response examples to every Visualizations API endpoint, following the same pattern as the Dashboards API: - POST: metric + XY line chart code samples, trimmed 201 response example - GET (search): code sample, paginated response example with 2 items - GET /{id}: code sample, single visualization response example - PUT /{id}: code sample, updated visualization response example - DELETE /{id}: code sample only (204 no body) Response examples are based on live API responses with server-added defaults (sampling, ignore_global_filters, empty_as_null, axis defaults) trimmed for clarity. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

- Reorder metric data fields to match actual API response: title → data_source → type (was incorrectly title → type → data_source in all 4 metric response examples) - PUT response: set created_at equal to updated_at to match actual API behavior, with a note that created_at reflects update time in PUT responses Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

Response examples now match the complete live API output including sampling, ignore_global_filters, empty_as_null, styling (metric), and axis/styling/legend (XY). These are part of the public contract and users need to see them to understand what the API returns. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

Code samples (x-codeSamples): - metric (data_view_spec) — cURL + Console - XY line chart (data_view_spec) — cURL + Console - pie/donut chart (data_view_spec) — cURL + Console - data table (data_view_spec) — cURL + Console - metric (data_view_reference) — cURL + Console Response examples (201): - createMetricVisualizationResponse - createXYVisualizationResponse - createPieVisualizationResponse - createDataTableVisualizationResponse - createDataViewReferenceResponse All payloads tested against a live Kibana 9.4.0 instance. Response examples include full server-populated defaults. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

elasticmachine · 2026-04-20T09:29:45Z

💚 Build Succeeded

Buildkite Build
Commit: d7b9ad3

Metrics [docs]

✅ unchanged

History

💚 Build #429214 succeeded dd2db0c
💛 Build #427205 was flaky e2cceb3

alaudazzi

LGTM

kibanamachine · 2026-04-20T13:30:46Z

Starting backport for target branches: 9.4

https://github.com/elastic/kibana/actions/runs/24669312988

…5 endpoints (elastic#262874) ## Summary Adds cURL and Console code samples and inlined response examples to all 5 Visualizations API endpoints. ### Code samples (`x-codeSamples`) | Endpoint | Examples | |---|---| | `POST /api/visualizations` | Metric chart (`data_view_spec`); XY line chart; Pie/donut chart; Data table; Metric chart (`data_view_reference`) | | `GET /api/visualizations` | Search visualizations | | `GET /api/visualizations/{id}` | Get a visualization | | `PUT /api/visualizations/{id}` | Update a visualization | | `DELETE /api/visualizations/{id}` | Delete a visualization | Each example has a cURL and Console variant. The `esql` data source is not covered — it is not yet supported by the Visualizations API (returns 400); use the Dashboards API for ES|QL visualizations. ### Response examples | Endpoint | Response code | Named examples | |---|---|---| | `POST /api/visualizations` | 201 | createMetricVisualizationResponse, createXYVisualizationResponse, createPieVisualizationResponse, createDataTableVisualizationResponse, createDataViewReferenceResponse | | `GET /api/visualizations` | 200 | searchVisualizationsResponse (two items: metric + XY) | | `GET /api/visualizations/{id}` | 200 | getVisualizationResponse (metric) | | `PUT /api/visualizations/{id}` | 200 | updateVisualizationResponse (metric) | All payloads tested against a live Kibana 9.4.0 instance using the Kibana sample logs dataset. ## Preview https://bump.sh/elastic/hub/elastic-apis/doc/visualizations-api-cleanup-intro-get-started/group/endpoint-visualizations ## Test plan - [ ] Verify code samples appear in the upper-right dropdown for each endpoint - [ ] Verify response examples appear in the Responses section with correct named tabs - [ ] Confirm all JSON in code samples is fully expanded (no inline objects) 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com> (cherry picked from commit 286db8c)

kibanamachine · 2026-04-20T13:39:06Z

💚 All backports created successfully

Status	Branch	Result
✅	9.4

Note: Successful backport PRs will be merged automatically after passing CI.

Questions ?

Please refer to the Backport tool documentation

## Summary Part of the Lens Visualizations API documentation series. **Series:** - PR 1/4: Introduction and get-started overlay — merged (#262595) - **PR 2/4 (this PR):** Endpoint descriptions and field descriptions - PR 3/4: Request code samples and response examples (#262874) - Viz PR B: Chart type schema descriptions (#263571) ## What changed ### Route files — all 5 endpoints Added `description` strings and `since: '9.4.0'` to all five routes. ### `schema/search.ts`, `schema/create.ts`, `schema/common.ts` - `query` search param: description added inline - `id` path param on delete/get/update: improved description - `total` response field: description added inline ### `schema/delete.ts`, `schema/get.ts`, `schema/update.ts` Updated `id` description to reference where the ID comes from. ### Shared package: `@kbn/as-code-shared-schemas` Added `meta.description` to all 7 fields of `asCodeMetaSchema` (`created_at`, `created_by`, `managed`, `owner`, `updated_at`, `updated_by`, `version`). > **Note:** descriptions added to `@kbn/content-management-utils` (`savedObjectSchema.id`, `searchOptionsSchemas.*`, `createOptionsSchemas.overwrite`) were **reverted** per feedback from ThomThomson — content management schemas are not part of the public as-code API surface. Descriptions for `fields`, `search_fields`, `overwrite`, and `id` will be handled via overlay fallback. ## Open items - Two CodeQL findings on `kbn-content-management-utils/src/schema.ts` (unbounded arrays) — pre-existing, not introduced by this PR - davismcphee's architectural question answered: content-management-utils changes reverted 🤖 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>

…ic#263151) ## Summary Part of the Lens Visualizations API documentation series. **Series:** - PR 1/4: Introduction and get-started overlay — merged (elastic#262595) - **PR 2/4 (this PR):** Endpoint descriptions and field descriptions - PR 3/4: Request code samples and response examples (elastic#262874) - Viz PR B: Chart type schema descriptions (elastic#263571) ## What changed ### Route files — all 5 endpoints Added `description` strings and `since: '9.4.0'` to all five routes. ### `schema/search.ts`, `schema/create.ts`, `schema/common.ts` - `query` search param: description added inline - `id` path param on delete/get/update: improved description - `total` response field: description added inline ### `schema/delete.ts`, `schema/get.ts`, `schema/update.ts` Updated `id` description to reference where the ID comes from. ### Shared package: `@kbn/as-code-shared-schemas` Added `meta.description` to all 7 fields of `asCodeMetaSchema` (`created_at`, `created_by`, `managed`, `owner`, `updated_at`, `updated_by`, `version`). > **Note:** descriptions added to `@kbn/content-management-utils` (`savedObjectSchema.id`, `searchOptionsSchemas.*`, `createOptionsSchemas.overwrite`) were **reverted** per feedback from ThomThomson — content management schemas are not part of the public as-code API surface. Descriptions for `fields`, `search_fields`, `overwrite`, and `id` will be handled via overlay fallback. ## Open items - Two CodeQL findings on `kbn-content-management-utils/src/schema.ts` (unbounded arrays) — pre-existing, not introduced by this PR - davismcphee's architectural question answered: content-management-utils changes reverted 🤖 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 c2bbbc4)

…r all 5 endpoints (#262874) (#264416) # Backport This will backport the following commits from `main` to `9.4`: - [[Docs][Visualizations API] Add request and response examples for all 5 endpoints (#262874)](#262874)  ### Questions ? Please refer to the [Backport tool documentation](https://github.com/sorenlouv/backport)  Co-authored-by: Florent LB <florent.leborgne@elastic.co> Co-authored-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

…263151) (#264423) # Backport This will backport the following commits from `main` to `9.4`: - [[Docs][Visualizations API] Add endpoint and field descriptions (#263151)](#263151)  ### Questions ? Please refer to the [Backport tool documentation](https://github.com/sorenlouv/backport)  Co-authored-by: Florent LB <florent.leborgne@elastic.co> Co-authored-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

…pes (Viz PR B) (#263571) ## Summary Part of the Lens Visualizations API documentation series (Viz PR B). Adds descriptions to all 12 chart type schemas and all supporting schemas. **Series:** - PR 1/4: Introduction overlay — merged (#262595) - PR 2/4: Endpoint + field descriptions (#263151) - PR 3/4: Code samples + response examples (#262874) - **Viz PR B (this PR):** Schema descriptions for all 12 chart types + supporting schemas ## Approach Descriptions only — no schema types, validation constraints, or field names changed. Rebased onto main to pick up #262927 (styling alignment restructuring). ## What changed ### Operation schemas - `metric_ops.ts`: object-level descriptions on `metricOperationDefinitionSchema`, `fieldMetricOrFormulaOperationDefinitionSchema` - `bucket_ops.ts`: descriptions on `bucketOperationDefinitionSchema` and all bucket operation fields; `When \`true\`,` pattern applied throughout - `shared.ts`: fixed tautological `collapseBySchema` description; fixed `ignore_global_filters` and `sampling` descriptions; fixed `axisTitleSchemaProps` ### Chart schemas — all 12 types Object-level descriptions on DSL variant, ES|QL variant, and union schema for every chart type. "DSL data source" consistently replaced with "data view". Additional field-level descriptions on chart-specific fields (shape, alignment, icon, palette, etc.). ### Supporting schemas - `color.ts`: descriptions on all color variant schemas; full palette name list on all palette fields with correct defaults per context - `format.ts`: descriptions on all format variant schemas - `filter.ts`: descriptions on `filterSchema` and `filterWithLabelSchema` - `index.ts`: description on `lensApiStateSchema` top-level union - `xy.ts`: `aggregate_first` description fixed ### Style quality pass - All descriptions standardised to noun phrases (no verb-first descriptions) - `A/An` added to concrete countable noun descriptions - Dropped valid enum values restored (alignment, slice label position, donut hole size) - Redundant numeric min/max removed from description text (auto-rendered by OAS) - `may` → `can` throughout ### Reverted Object-level descriptions added to `@kbn/as-code-data-views-schema` (`dataViewReferenceSchema`, `dataViewSpecSchema`, `runtimeFieldSchema`, etc.) were **reverted** — object-level `meta.description` on schema objects in shared packages does not surface in the OAS output. Will use overlay fallback. ## Test plan - [x] Rebased onto main; conflicts from #262927 resolved - [x] Descriptions verified in combined OAS preview on Bump 🤖 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> Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: florent-leborgne <10208282+florent-leborgne@users.noreply.github.com> Co-authored-by: Marco Vettorello <vettorello.marco@gmail.com>

…art types (Viz PR B) (#263571) (#265997) # Backport This will backport the following commits from `main` to `9.4`: - [[Docs][Visualizations API] Add schema descriptions to all 12 chart types (Viz PR B) (#263571)](#263571)  ### Questions ? Please refer to the [Backport tool documentation](https://github.com/sorenlouv/backport)  Co-authored-by: Florent LB <florent.leborgne@elastic.co> Co-authored-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com> Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: florent-leborgne <10208282+florent-leborgne@users.noreply.github.com> Co-authored-by: Marco Vettorello <vettorello.marco@gmail.com>

…pes (Viz PR B) (elastic#263571) ## Summary Part of the Lens Visualizations API documentation series (Viz PR B). Adds descriptions to all 12 chart type schemas and all supporting schemas. **Series:** - PR 1/4: Introduction overlay — merged (elastic#262595) - PR 2/4: Endpoint + field descriptions (elastic#263151) - PR 3/4: Code samples + response examples (elastic#262874) - **Viz PR B (this PR):** Schema descriptions for all 12 chart types + supporting schemas ## Approach Descriptions only — no schema types, validation constraints, or field names changed. Rebased onto main to pick up elastic#262927 (styling alignment restructuring). ## What changed ### Operation schemas - `metric_ops.ts`: object-level descriptions on `metricOperationDefinitionSchema`, `fieldMetricOrFormulaOperationDefinitionSchema` - `bucket_ops.ts`: descriptions on `bucketOperationDefinitionSchema` and all bucket operation fields; `When \`true\`,` pattern applied throughout - `shared.ts`: fixed tautological `collapseBySchema` description; fixed `ignore_global_filters` and `sampling` descriptions; fixed `axisTitleSchemaProps` ### Chart schemas — all 12 types Object-level descriptions on DSL variant, ES|QL variant, and union schema for every chart type. "DSL data source" consistently replaced with "data view". Additional field-level descriptions on chart-specific fields (shape, alignment, icon, palette, etc.). ### Supporting schemas - `color.ts`: descriptions on all color variant schemas; full palette name list on all palette fields with correct defaults per context - `format.ts`: descriptions on all format variant schemas - `filter.ts`: descriptions on `filterSchema` and `filterWithLabelSchema` - `index.ts`: description on `lensApiStateSchema` top-level union - `xy.ts`: `aggregate_first` description fixed ### Style quality pass - All descriptions standardised to noun phrases (no verb-first descriptions) - `A/An` added to concrete countable noun descriptions - Dropped valid enum values restored (alignment, slice label position, donut hole size) - Redundant numeric min/max removed from description text (auto-rendered by OAS) - `may` → `can` throughout ### Reverted Object-level descriptions added to `@kbn/as-code-data-views-schema` (`dataViewReferenceSchema`, `dataViewSpecSchema`, `runtimeFieldSchema`, etc.) were **reverted** — object-level `meta.description` on schema objects in shared packages does not surface in the OAS output. Will use overlay fallback. ## Test plan - [x] Rebased onto main; conflicts from elastic#262927 resolved - [x] Descriptions verified in combined OAS preview on Bump 🤖 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> Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: florent-leborgne <10208282+florent-leborgne@users.noreply.github.com> Co-authored-by: Marco Vettorello <vettorello.marco@gmail.com>

florent-leborgne requested review from ThomThomson, markov00 and teresaalvarezsoler April 13, 2026 18:25

teresaalvarezsoler approved these changes Apr 14, 2026

View reviewed changes

florent-leborgne marked this pull request as ready for review April 14, 2026 10:10

florent-leborgne requested a review from a team as a code owner April 14, 2026 10:10

florent-leborgne added Team:Docs release_note:skip Skip the PR/issue when compiling release notes docs APIDocs backport:version Backport to applied version labels v9.4.0 labels Apr 14, 2026

florent-leborgne and others added 4 commits April 14, 2026 12:24

florent-leborgne force-pushed the lens-api-docs-examples branch from e5b84c5 to e2cceb3 Compare April 14, 2026 10:24

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

dd2db0c

markov00 approved these changes Apr 20, 2026

View reviewed changes

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

d7b9ad3

alaudazzi approved these changes Apr 20, 2026

View reviewed changes

florent-leborgne merged commit 286db8c into main Apr 20, 2026
16 checks passed

florent-leborgne deleted the lens-api-docs-examples branch April 20, 2026 13:30

kibanamachine added the v9.5.0 label Apr 20, 2026

kibanamachine mentioned this pull request Apr 20, 2026

[9.4] [Docs][Visualizations API] Add request and response examples for all 5 endpoints (#262874) #264416

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Docs][Visualizations API] Add request and response examples for all 5 endpoints#262874

[Docs][Visualizations API] Add request and response examples for all 5 endpoints#262874
florent-leborgne merged 6 commits into
mainfrom
lens-api-docs-examples

florent-leborgne commented Apr 13, 2026 •

edited by kibanamachine

Loading

Uh oh!

teresaalvarezsoler left a comment

Uh oh!

elasticmachine commented Apr 14, 2026

Uh oh!

elasticmachine commented Apr 20, 2026

Uh oh!

alaudazzi left a comment

Uh oh!

Uh oh!

kibanamachine commented Apr 20, 2026

Uh oh!

kibanamachine commented Apr 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

Conversation

florent-leborgne commented Apr 13, 2026 • edited by kibanamachine Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Code samples (x-codeSamples)

Response examples

Preview

Test plan

Uh oh!

teresaalvarezsoler left a comment

Choose a reason for hiding this comment

Uh oh!

elasticmachine commented Apr 14, 2026

Uh oh!

elasticmachine commented Apr 20, 2026

💚 Build Succeeded

Metrics [docs]

History

Uh oh!

alaudazzi left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

kibanamachine commented Apr 20, 2026

Uh oh!

kibanamachine commented Apr 20, 2026

💚 All backports created successfully

Questions ?

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

florent-leborgne commented Apr 13, 2026 •

edited by kibanamachine

Loading

Code samples (`x-codeSamples`)