Type to search.

Upsert a dashboard

Base URL
https://{kibana_url}
  • PUT /api/dashboards/{id}
Auth The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Generally available since 9.5 This functionality is generally available and ready for production usage. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes.

Creates a new dashboard with the given ID if none exists, or replaces the complete state of an existing one.

Warning

This is a full replacement. Any panels not included in the request body are permanently removed. To make targeted changes, retrieve the current state first with GET /api/dashboards/{id}, apply your changes, and submit the full updated object.

You can optionally include access_control.access_mode to change the dashboard access mode. If the authenticated user is not authorized to change access mode for the target dashboard, the request returns a 403 response with a descriptive message.

Path parameters

id string required

The unique ID of the dashboard to be created or updated

Header parameters

kbn-xsrf string required

A required header to protect against CSRF attacks

Request body

description string

A short description of the dashboard.

esql_approximation boolean

When true, ES|QL visualizations that use STATS run with approximate execution for faster, estimated results.

filters union oneOf[] · max items: 500

Filters applied across all panels, including pinned panels.

One of:

A filter that evaluates a single field condition such as equality, range, or existence.

type enum required
Values: condition
condition union oneOf required

A filter condition with strict operator/value type matching.

One of: (determined by operator)
operator: is

Matches documents where field equals a single specified value.

operator enum required
Values: is
field string required

Name of the document field the condition evaluates.

negate boolean

When true, the filter is negated and matches documents that do NOT satisfy the condition. Defaults to false.

value union string | number | boolean required

Single value to compare against the field.

controlled_by string

Identifier of the panel that manages this filter. When set, the filter is treated as owned by that panel.

data_view_id string

Identifier of the data view used as context for this filter.

disabled boolean

When true, the filter is inactive and does not affect query results. Defaults to false.

is_multi_index boolean

When true, the filter can be applied across multiple indices. Defaults to false.

label string

Human-readable label for the filter, used for display purposes.

negate boolean

When true, the filter is negated and matches documents that do NOT satisfy the condition. Defaults to false.

panels union anyOf[] · max items: 1000

Panels and sections in the dashboard. Each entry is either a panel (with a type and config) or a collapsible section (with a title, collapsed state, and nested panels).

Any of:
config object required

Anomaly Charts embeddable

description string

A short description of the panel.

hide_border boolean

When true, the panel border is hidden. Defaults to false.

hide_title boolean

When true, the panel title is hidden. Defaults to false.

job_ids string[] · min items: 1 · max items: 10000 required

Anomaly detection job or group IDs whose results are shown in the charts.

max_series_to_plot number · min: 1 · max: 50

Maximum number of anomaly series to plot.

severity_threshold union anyOf[] · max items: 5

Severity threshold ranges used to filter anomaly results.

Any of:
min enum required
Values: 0
max enum required
Values: 3
title string

The panel title.

grid object required

The position and size of the panel on the dashboard grid.

h number · min: 1 · default: 15

The height of the panel in grid units. Minimum 1. Defaults to 15.

w number · min: 1 · max: 48 · default: 24

The width of the panel in grid units. Minimum 1, maximum 48. Defaults to 24.

x number required

The x coordinate of the panel in grid units.

y number required

The y coordinate of the panel in grid units.

id string

The unique ID of the panel.

type enum required
Values: ml_anomaly_charts
pinned_panels union oneOf[] · max items: 100

An array of control panels and their state in the control group.

One of:

An ES|QL variable control whose selected value is injected into ES|QL visualizations using the ?variable_name syntax. Options can come from a fixed list or an ES|QL query. Define the options source in config.

type enum required
Values: esql_control
config union oneOf required
Same options as config in ES|QL variable control
grow boolean · default: false

When true, the control expands to fill any available horizontal space. Defaults to false.

id string

The unique ID of the control

width enum · default: medium

Minimum width of the control panel.

Values: small medium large
project_routing string

Controls cross-project search behavior for this dashboard (Serverless only). Set to _alias:_origin to scope data to the current project, or _alias:* to search across all projects. When omitted, the space default applies.

tags string[] · max items: 1000 · default: []

Tag IDs to associate with this dashboard.

title string · min length: 1 required

A human-readable title for the dashboard.

Responses

updated

application/json
data object required
description string

A short description of the dashboard.

esql_approximation boolean

When true, ES|QL visualizations that use STATS run with approximate execution for faster, estimated results.

filters union oneOf[] · max items: 500

Filters applied across all panels, including pinned panels.

Same options as filters
panels union anyOf[] · max items: 1000

Panels and sections in the dashboard. Each entry is either a panel (with a type and config) or a collapsible section (with a title, collapsed state, and nested panels).

Same options as panels
pinned_panels union oneOf[] · max items: 100

An array of control panels and their state in the control group.

Same options as pinned_panels
project_routing string

Controls cross-project search behavior for this dashboard (Serverless only). Set to _alias:_origin to scope data to the current project, or _alias:* to search across all projects. When omitted, the space default applies.

tags string[] · max items: 1000 · default: []

Tag IDs to associate with this dashboard.

title string · min length: 1 required

A human-readable title for the dashboard.

id string required

The unique ID of the dashboard, as returned by the create or search endpoints.

meta object required
created_at string

Timestamp when the object was created (ISO 8601).

created_by string

User profile ID of the user who created the object.

managed boolean

When true, the object is managed by Kibana and cannot be edited by users.

owner string

Identifier of the plugin or team that owns this object.

updated_at string

Timestamp when the object was last updated (ISO 8601).

updated_by string

User profile ID of the user who last updated the object.

version string

Internal version identifier for optimistic concurrency control.

400

invalid request

403

forbidden

409

conflict