diff --git a/oas_docs/overlays/visualizations.overlays.yaml b/oas_docs/overlays/visualizations.overlays.yaml index 263fcc49526b3..a667ed592daf8 100644 --- a/oas_docs/overlays/visualizations.overlays.yaml +++ b/oas_docs/overlays/visualizations.overlays.yaml @@ -93,3 +93,780 @@ actions: description: Visualizations documentation url: https://www.elastic.co/docs/explore-analyze/visualize/lens x-displayName: Visualizations + + # ────────────────────────────────────────────── + # POST /api/visualizations — examples and code samples + # ────────────────────────────────────────────── + - target: "$.paths['/api/visualizations']['post']" + description: Add examples and code samples to create endpoint + update: + responses: + '201': + content: + application/json: + examples: + createMetricVisualizationResponse: + summary: Create a metric visualization + description: > + Response after creating a metric chart (count of requests) using an + inline data view. Server-populated defaults are included in the response. + value: + id: 1e4f0a30-b3c5-11ef-bd7a-2b6b1a8c0f3d + data: + title: Total requests + data_source: + type: data_view_spec + index_pattern: kibana_sample_data_logs + time_field: timestamp + type: metric + sampling: 1 + ignore_global_filters: false + metrics: + - type: primary + operation: count + empty_as_null: false + styling: + primary: + position: bottom + labels: + alignment: left + value: + sizing: auto + alignment: right + meta: + created_at: "2026-04-13T10:00:00.000Z" + managed: false + updated_at: "2026-04-13T10:00:00.000Z" + version: WzU5LDFd + createXYVisualizationResponse: + summary: Create an XY line chart + description: > + Response after creating an XY line chart. The response includes + server-populated defaults for axis configuration, styling, and legend. + value: + id: 3a7c2e10-b3c5-11ef-bd7a-2b6b1a8c0f3d + data: + title: Log entries over time + type: xy + layers: + - type: line + data_source: + type: data_view_spec + index_pattern: kibana_sample_data_logs + time_field: timestamp + sampling: 1 + ignore_global_filters: false + x: + operation: date_histogram + field: timestamp + suggested_interval: auto + use_original_time_range: false + include_empty_rows: true + drop_partial_intervals: false + y: + - operation: count + empty_as_null: false + axis_id: y + axis: + x: + title: + visible: true + ticks: + visible: true + grid: + visible: true + domain: + type: fit + rounding: false + labels: + orientation: horizontal + y: + anchor: start + title: + visible: true + scale: linear + ticks: + visible: true + grid: + visible: true + domain: + type: full + rounding: true + labels: + orientation: horizontal + styling: + overlays: + partial_buckets: + visible: false + current_time_marker: + visible: false + interpolation: linear + points: + visibility: auto + legend: + visibility: hidden + placement: outside + position: right + layout: + type: grid + truncate: + max_lines: 1 + meta: + created_at: "2026-04-13T10:05:00.000Z" + managed: false + updated_at: "2026-04-13T10:05:00.000Z" + version: WzYwLDFd + createPieVisualizationResponse: + summary: Create a pie/donut chart + description: > + Response after creating a donut chart broken down by response code. + Note that `group_by` items gain a server-populated `rank_by` sort + order, and `legend`, `values`, and `labels` are populated with defaults. + value: + id: 2cac466f-ff49-4d34-8d69-487a93a179c2 + data: + title: Requests by response code + type: pie + metrics: + - operation: count + empty_as_null: false + group_by: + - operation: terms + fields: + - response.keyword + limit: 5 + rank_by: + type: metric + metric_index: 0 + direction: desc + data_source: + type: data_view_spec + index_pattern: kibana_sample_data_logs + time_field: timestamp + legend: + visibility: auto + values: + visible: true + mode: percentage + donut_hole: m + labels: + visible: true + position: outside + meta: + created_at: "2026-04-13T10:10:00.000Z" + managed: false + updated_at: "2026-04-13T10:10:00.000Z" + version: Wzc3LDFd + createDataTableVisualizationResponse: + summary: Create a data table + description: > + Response after creating a data table broken down by response code. + Note that `rows` items gain a server-populated `rank_by` sort order. + value: + id: 83660652-bc77-46a1-8dca-5d512949eba6 + data: + title: Top response codes + type: data_table + data_source: + type: data_view_spec + index_pattern: kibana_sample_data_logs + time_field: timestamp + sampling: 1 + ignore_global_filters: false + metrics: + - operation: count + empty_as_null: false + rows: + - operation: terms + fields: + - response.keyword + limit: 5 + rank_by: + type: metric + metric_index: 0 + direction: desc + meta: + created_at: "2026-04-13T10:15:00.000Z" + managed: false + updated_at: "2026-04-13T10:15:00.000Z" + version: Wzc4LDFd + createDataViewReferenceResponse: + summary: Create a visualization using a library data view + description: > + Response after creating a metric chart that references an existing + saved data view by ID (`ref_id`) instead of defining an inline index pattern. + value: + id: cc44837a-7f20-42ee-b317-9af4f5eacc9c + data: + title: Total requests (library data view) + data_source: + type: data_view_reference + ref_id: 90943e30-9a47-11e8-b64d-95841ca0b247 + type: metric + sampling: 1 + ignore_global_filters: false + metrics: + - type: primary + operation: count + empty_as_null: false + styling: + primary: + position: bottom + labels: + alignment: left + value: + sizing: auto + alignment: right + meta: + created_at: "2026-04-13T10:20:00.000Z" + managed: false + updated_at: "2026-04-13T10:20:00.000Z" + version: Wzc5LDFd + x-codeSamples: + - lang: cURL + label: Create a metric visualization - cURL + source: | + curl -X POST "${KIBANA_URL}/api/visualizations" \ + -H "Authorization: ApiKey ${API_KEY}" \ + -H "kbn-xsrf: true" \ + -H "Content-Type: application/json" \ + -d '{ + "type": "metric", + "title": "Total requests", + "data_source": { + "type": "data_view_spec", + "index_pattern": "kibana_sample_data_logs", + "time_field": "timestamp" + }, + "metrics": [ + { + "type": "primary", + "operation": "count" + } + ] + }' + - lang: Console + label: Create a metric visualization - Console + source: | + POST kbn:/api/visualizations + { + "type": "metric", + "title": "Total requests", + "data_source": { + "type": "data_view_spec", + "index_pattern": "kibana_sample_data_logs", + "time_field": "timestamp" + }, + "metrics": [ + { + "type": "primary", + "operation": "count" + } + ] + } + - lang: cURL + label: Create an XY line chart - cURL + source: | + curl -X POST "${KIBANA_URL}/api/visualizations" \ + -H "Authorization: ApiKey ${API_KEY}" \ + -H "kbn-xsrf: true" \ + -H "Content-Type: application/json" \ + -d '{ + "type": "xy", + "title": "Log entries over time", + "layers": [ + { + "type": "line", + "data_source": { + "type": "data_view_spec", + "index_pattern": "kibana_sample_data_logs", + "time_field": "timestamp" + }, + "x": { + "operation": "date_histogram", + "field": "timestamp" + }, + "y": [ + { + "operation": "count" + } + ] + } + ] + }' + - lang: Console + label: Create an XY line chart - Console + source: | + POST kbn:/api/visualizations + { + "type": "xy", + "title": "Log entries over time", + "layers": [ + { + "type": "line", + "data_source": { + "type": "data_view_spec", + "index_pattern": "kibana_sample_data_logs", + "time_field": "timestamp" + }, + "x": { + "operation": "date_histogram", + "field": "timestamp" + }, + "y": [ + { + "operation": "count" + } + ] + } + ] + } + - lang: cURL + label: Create a pie/donut chart - cURL + source: | + curl -X POST "${KIBANA_URL}/api/visualizations" \ + -H "Authorization: ApiKey ${API_KEY}" \ + -H "kbn-xsrf: true" \ + -H "Content-Type: application/json" \ + -d '{ + "type": "pie", + "title": "Requests by response code", + "donut_hole": "m", + "data_source": { + "type": "data_view_spec", + "index_pattern": "kibana_sample_data_logs", + "time_field": "timestamp" + }, + "metrics": [ + { + "operation": "count" + } + ], + "group_by": [ + { + "operation": "terms", + "fields": [ + "response.keyword" + ], + "limit": 5 + } + ] + }' + - lang: Console + label: Create a pie/donut chart - Console + source: | + POST kbn:/api/visualizations + { + "type": "pie", + "title": "Requests by response code", + "donut_hole": "m", + "data_source": { + "type": "data_view_spec", + "index_pattern": "kibana_sample_data_logs", + "time_field": "timestamp" + }, + "metrics": [ + { + "operation": "count" + } + ], + "group_by": [ + { + "operation": "terms", + "fields": [ + "response.keyword" + ], + "limit": 5 + } + ] + } + - lang: cURL + label: Create a data table - cURL + source: | + curl -X POST "${KIBANA_URL}/api/visualizations" \ + -H "Authorization: ApiKey ${API_KEY}" \ + -H "kbn-xsrf: true" \ + -H "Content-Type: application/json" \ + -d '{ + "type": "data_table", + "title": "Top response codes", + "data_source": { + "type": "data_view_spec", + "index_pattern": "kibana_sample_data_logs", + "time_field": "timestamp" + }, + "metrics": [ + { + "operation": "count" + } + ], + "rows": [ + { + "operation": "terms", + "fields": [ + "response.keyword" + ], + "limit": 5 + } + ] + }' + - lang: Console + label: Create a data table - Console + source: | + POST kbn:/api/visualizations + { + "type": "data_table", + "title": "Top response codes", + "data_source": { + "type": "data_view_spec", + "index_pattern": "kibana_sample_data_logs", + "time_field": "timestamp" + }, + "metrics": [ + { + "operation": "count" + } + ], + "rows": [ + { + "operation": "terms", + "fields": [ + "response.keyword" + ], + "limit": 5 + } + ] + } + - lang: cURL + label: Create a visualization using a library data view - cURL + source: | + curl -X POST "${KIBANA_URL}/api/visualizations" \ + -H "Authorization: ApiKey ${API_KEY}" \ + -H "kbn-xsrf: true" \ + -H "Content-Type: application/json" \ + -d '{ + "type": "metric", + "title": "Total requests (library data view)", + "data_source": { + "type": "data_view_reference", + "ref_id": "90943e30-9a47-11e8-b64d-95841ca0b247" + }, + "metrics": [ + { + "type": "primary", + "operation": "count" + } + ] + }' + - lang: Console + label: Create a visualization using a library data view - Console + source: | + POST kbn:/api/visualizations + { + "type": "metric", + "title": "Total requests (library data view)", + "data_source": { + "type": "data_view_reference", + "ref_id": "90943e30-9a47-11e8-b64d-95841ca0b247" + }, + "metrics": [ + { + "type": "primary", + "operation": "count" + } + ] + } + + # ────────────────────────────────────────────── + # GET /api/visualizations — examples and code samples + # ────────────────────────────────────────────── + - target: "$.paths['/api/visualizations']['get']" + description: Add examples and code samples to search endpoint + update: + responses: + '200': + content: + application/json: + examples: + searchVisualizationsResponse: + summary: Search visualizations response + description: > + Paginated list of visualizations matching the query. Each item includes + the ID, full chart configuration, and metadata. Use the GET endpoint to + retrieve a single visualization by ID. + value: + data: + - id: 1e4f0a30-b3c5-11ef-bd7a-2b6b1a8c0f3d + data: + title: Total requests + data_source: + type: data_view_spec + index_pattern: kibana_sample_data_logs + time_field: timestamp + type: metric + sampling: 1 + ignore_global_filters: false + metrics: + - type: primary + operation: count + empty_as_null: false + styling: + primary: + position: bottom + labels: + alignment: left + value: + sizing: auto + alignment: right + meta: + created_at: "2026-04-13T10:00:00.000Z" + managed: false + updated_at: "2026-04-13T10:00:00.000Z" + version: WzU5LDFd + - id: 3a7c2e10-b3c5-11ef-bd7a-2b6b1a8c0f3d + data: + title: Log entries over time + type: xy + layers: + - type: line + data_source: + type: data_view_spec + index_pattern: kibana_sample_data_logs + time_field: timestamp + sampling: 1 + ignore_global_filters: false + x: + operation: date_histogram + field: timestamp + suggested_interval: auto + use_original_time_range: false + include_empty_rows: true + drop_partial_intervals: false + y: + - operation: count + empty_as_null: false + axis_id: y + axis: + x: + title: + visible: true + ticks: + visible: true + grid: + visible: true + domain: + type: fit + rounding: false + labels: + orientation: horizontal + y: + anchor: start + title: + visible: true + scale: linear + ticks: + visible: true + grid: + visible: true + domain: + type: full + rounding: true + labels: + orientation: horizontal + styling: + overlays: + partial_buckets: + visible: false + current_time_marker: + visible: false + interpolation: linear + points: + visibility: auto + legend: + visibility: hidden + placement: outside + position: right + layout: + type: grid + truncate: + max_lines: 1 + meta: + created_at: "2026-04-13T10:05:00.000Z" + managed: false + updated_at: "2026-04-13T10:05:00.000Z" + version: WzYwLDFd + meta: + page: 1 + per_page: 20 + total: 2 + x-codeSamples: + - lang: cURL + label: Search visualizations - cURL + source: | + curl -X GET "${KIBANA_URL}/api/visualizations?query=requests&per_page=10" \ + -H "Authorization: ApiKey ${API_KEY}" + - lang: Console + label: Search visualizations - Console + source: | + GET kbn:/api/visualizations?query=requests&per_page=10 + + # ────────────────────────────────────────────── + # GET /api/visualizations/{id} — examples and code samples + # ────────────────────────────────────────────── + - target: "$.paths['/api/visualizations/{id}']['get']" + description: Add examples and code samples to get endpoint + update: + responses: + '200': + content: + application/json: + examples: + getVisualizationResponse: + summary: Get visualization response + description: > + The full visualization state including the chart configuration and metadata. + value: + id: 1e4f0a30-b3c5-11ef-bd7a-2b6b1a8c0f3d + data: + title: Total requests + data_source: + type: data_view_spec + index_pattern: kibana_sample_data_logs + time_field: timestamp + type: metric + sampling: 1 + ignore_global_filters: false + metrics: + - type: primary + operation: count + empty_as_null: false + styling: + primary: + position: bottom + labels: + alignment: left + value: + sizing: auto + alignment: right + meta: + created_at: "2026-04-13T10:00:00.000Z" + managed: false + updated_at: "2026-04-13T10:00:00.000Z" + version: WzU5LDFd + x-codeSamples: + - lang: cURL + label: Get a visualization - cURL + source: | + curl -X GET "${KIBANA_URL}/api/visualizations/1e4f0a30-b3c5-11ef-bd7a-2b6b1a8c0f3d" \ + -H "Authorization: ApiKey ${API_KEY}" + - lang: Console + label: Get a visualization - Console + source: | + GET kbn:/api/visualizations/1e4f0a30-b3c5-11ef-bd7a-2b6b1a8c0f3d + + # ────────────────────────────────────────────── + # PUT /api/visualizations/{id} — examples and code samples + # ────────────────────────────────────────────── + - target: "$.paths['/api/visualizations/{id}']['put']" + description: Add examples and code samples to update endpoint + update: + responses: + '200': + content: + application/json: + examples: + updateVisualizationResponse: + summary: Update visualization response + description: > + The complete updated visualization state after a full replacement. PUT + replaces the entire chart configuration — fields omitted from the request + are reset to their defaults. `meta.created_at` reflects the update time + rather than the original creation time. + value: + id: 1e4f0a30-b3c5-11ef-bd7a-2b6b1a8c0f3d + data: + title: Total requests (updated) + data_source: + type: data_view_spec + index_pattern: kibana_sample_data_logs + time_field: timestamp + type: metric + sampling: 1 + ignore_global_filters: false + metrics: + - type: primary + operation: count + empty_as_null: false + styling: + primary: + position: bottom + labels: + alignment: left + value: + sizing: auto + alignment: right + meta: + created_at: "2026-04-13T11:00:00.000Z" + managed: false + updated_at: "2026-04-13T11:00:00.000Z" + version: WzYxLDFd + x-codeSamples: + - lang: cURL + label: Update a visualization - cURL + source: | + curl -X PUT "${KIBANA_URL}/api/visualizations/1e4f0a30-b3c5-11ef-bd7a-2b6b1a8c0f3d" \ + -H "Authorization: ApiKey ${API_KEY}" \ + -H "kbn-xsrf: true" \ + -H "Content-Type: application/json" \ + -d '{ + "type": "metric", + "title": "Total requests (updated)", + "data_source": { + "type": "data_view_spec", + "index_pattern": "kibana_sample_data_logs", + "time_field": "timestamp" + }, + "metrics": [ + { + "type": "primary", + "operation": "count" + } + ] + }' + - lang: Console + label: Update a visualization - Console + source: | + PUT kbn:/api/visualizations/1e4f0a30-b3c5-11ef-bd7a-2b6b1a8c0f3d + { + "type": "metric", + "title": "Total requests (updated)", + "data_source": { + "type": "data_view_spec", + "index_pattern": "kibana_sample_data_logs", + "time_field": "timestamp" + }, + "metrics": [ + { + "type": "primary", + "operation": "count" + } + ] + } + + # ────────────────────────────────────────────── + # DELETE /api/visualizations/{id} — code samples + # ────────────────────────────────────────────── + - target: "$.paths['/api/visualizations/{id}']['delete']" + description: Add code samples to delete endpoint + update: + x-codeSamples: + - lang: cURL + label: Delete a visualization - cURL + source: | + curl -X DELETE "${KIBANA_URL}/api/visualizations/1e4f0a30-b3c5-11ef-bd7a-2b6b1a8c0f3d" \ + -H "Authorization: ApiKey ${API_KEY}" \ + -H "kbn-xsrf: true" + - lang: Console + label: Delete a visualization - Console + source: | + DELETE kbn:/api/visualizations/1e4f0a30-b3c5-11ef-bd7a-2b6b1a8c0f3d