Upsert a dashboard

Server: https://{kibana_url}

PUT /api/dashboards/{id}

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

warn 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

Request

Responses

updated

application/json

created

application/json

400

invalid request

403

forbidden

409

conflict

Examples

The complete updated dashboard state after a full replacement. Note that meta.created_at is not returned in update responses - use the GET endpoint to retrieve it.

Request Console 1 / 2 languages

Console Kibana Dev Tools

PUT kbn:/api/dashboards/3c4b8e10-d57a-11ef-9a52-4f3c2a8d0e1b
{
  "title": "Web logs overview",
  "panels": [
    {
      "grid": {
        "x": 0,
        "y": 0,
        "w": 12,
        "h": 5
      },
      "type": "vis",
      "config": {
        "type": "metric",
        "data_source": {
          "type": "data_view_spec",
          "index_pattern": "kibana_sample_data_logs",
          "time_field": "timestamp"
        },
        "metrics": [
          {
            "type": "primary",
            "operation": "count"
          }
        ]
      }
    },
    {
      "grid": {
        "x": 12,
        "y": 0,
        "w": 12,
        "h": 5
      },
      "type": "vis",
      "config": {
        "type": "metric",
        "data_source": {
          "type": "data_view_spec",
          "index_pattern": "kibana_sample_data_logs",
          "time_field": "timestamp"
        },
        "metrics": [
          {
            "type": "primary",
            "operation": "average",
            "field": "bytes"
          }
        ]
      }
    },
    {
      "grid": {
        "x": 0,
        "y": 8,
        "w": 24,
        "h": 10
      },
      "type": "vis",
      "config": {
        "type": "xy",
        "title": "Requests over time",
        "layers": [
          {
            "type": "line",
            "data_source": {
              "type": "esql",
              "query": "FROM kibana_sample_data_logs | STATS count = COUNT() BY BUCKET(@timestamp, 75, ?_tstart, ?_tend)"
            },
            "x": {
              "column": "BUCKET(@timestamp, 75, ?_tstart, ?_tend)"
            },
            "y": [
              {
                "column": "count"
              }
            ]
          }
        ],
        "axis": {
          "x": {
            "title": {
              "visible": false
            }
          }
        }
      }
    },
    {
      "grid": {
        "x": 24,
        "y": 8,
        "w": 12,
        "h": 5
      },
      "type": "vis",
      "config": {
        "type": "metric",
        "data_source": {
          "type": "data_view_spec",
          "index_pattern": "kibana_sample_data_logs",
          "time_field": "timestamp"
        },
        "metrics": [
          {
            "type": "primary",
            "operation": "unique_count",
            "field": "clientip"
          }
        ]
      }
    }
  ]
}

curl Shell

curl -X PUT "${KIBANA_URL}/api/dashboards/3c4b8e10-d57a-11ef-9a52-4f3c2a8d0e1b" \
  -H "Authorization: ApiKey ${API_KEY}" \
  -H "kbn-xsrf: true" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Web logs overview",
  "panels": [
    {
      "grid": {
        "x": 0,
        "y": 0,
        "w": 12,
        "h": 5
      },
      "type": "vis",
      "config": {
        "type": "metric",
        "data_source": {
          "type": "data_view_spec",
          "index_pattern": "kibana_sample_data_logs",
          "time_field": "timestamp"
        },
        "metrics": [
          {
            "type": "primary",
            "operation": "count"
          }
        ]
      }
    },
    {
      "grid": {
        "x": 12,
        "y": 0,
        "w": 12,
        "h": 5
      },
      "type": "vis",
      "config": {
        "type": "metric",
        "data_source": {
          "type": "data_view_spec",
          "index_pattern": "kibana_sample_data_logs",
          "time_field": "timestamp"
        },
        "metrics": [
          {
            "type": "primary",
            "operation": "average",
            "field": "bytes"
          }
        ]
      }
    },
    {
      "grid": {
        "x": 0,
        "y": 8,
        "w": 24,
        "h": 10
      },
      "type": "vis",
      "config": {
        "type": "xy",
        "title": "Requests over time",
        "layers": [
          {
            "type": "line",
            "data_source": {
              "type": "esql",
              "query": "FROM kibana_sample_data_logs | STATS count = COUNT() BY BUCKET(@timestamp, 75, ?_tstart, ?_tend)"
            },
            "x": {
              "column": "BUCKET(@timestamp, 75, ?_tstart, ?_tend)"
            },
            "y": [
              {
                "column": "count"
              }
            ]
          }
        ],
        "axis": {
          "x": {
            "title": {
              "visible": false
            }
          }
        }
      }
    },
    {
      "grid": {
        "x": 24,
        "y": 8,
        "w": 12,
        "h": 5
      },
      "type": "vis",
      "config": {
        "type": "metric",
        "data_source": {
          "type": "data_view_spec",
          "index_pattern": "kibana_sample_data_logs",
          "time_field": "timestamp"
        },
        "metrics": [
          {
            "type": "primary",
            "operation": "unique_count",
            "field": "clientip"
          }
        ]
      }
    }
  ]
}'

Response

{
  "data": {
    "options": {
      "auto_apply_filters": true,
      "hide_panel_borders": false,
      "hide_panel_titles": false,
      "sync_colors": false,
      "sync_cursor": true,
      "sync_tooltips": false,
      "use_margins": true
    },
    "panels": [
      {
        "config": {
          "content": "## Web logs overview\n\n\u0026nbsp;\n\nCreated with the [Dashboards API](https://www.elastic.co/docs/api/doc/kibana) using the Kibana sample web logs dataset (\u0060kibana_sample_data_logs\u0060). Contains:\n- This markdown panel\n- 2 metrics, showing request count and average response size\n- A line chart based on an ES|QL query\n\n\u0026nbsp;\n\n\u0026nbsp;\n\n[Learn more about dashboards](https://www.elastic.co/docs/explore-analyze/dashboards)"
        },
        "grid": {
          "h": 15,
          "w": 24,
          "x": 0,
          "y": 0
        },
        "id": "a1b2c3d4-0001-4000-8000-000000000001",
        "type": "markdown"
      },
      {
        "config": {
          "data_source": {
            "index_pattern": "kibana_sample_data_logs",
            "time_field": "timestamp",
            "type": "data_view_spec"
          },
          "ignore_global_filters": false,
          "metrics": [
            {
              "empty_as_null": false,
              "operation": "count",
              "type": "primary"
            }
          ],
          "sampling": 1,
          "styling": {
            "primary": {
              "labels": {
                "alignment": "left"
              },
              "position": "bottom",
              "value": {
                "alignment": "right",
                "sizing": "auto"
              }
            }
          },
          "title": "",
          "type": "metric"
        },
        "grid": {
          "h": 5,
          "w": 12,
          "x": 24,
          "y": 0
        },
        "id": "a1b2c3d4-0001-4000-8000-000000000002",
        "type": "vis"
      },
      {
        "config": {
          "data_source": {
            "index_pattern": "kibana_sample_data_logs",
            "time_field": "timestamp",
            "type": "data_view_spec"
          },
          "ignore_global_filters": false,
          "metrics": [
            {
              "field": "bytes",
              "operation": "average",
              "type": "primary"
            }
          ],
          "sampling": 1,
          "styling": {
            "primary": {
              "labels": {
                "alignment": "left"
              },
              "position": "bottom",
              "value": {
                "alignment": "right",
                "sizing": "auto"
              }
            }
          },
          "title": "",
          "type": "metric"
        },
        "grid": {
          "h": 5,
          "w": 12,
          "x": 36,
          "y": 0
        },
        "id": "a1b2c3d4-0001-4000-8000-000000000003",
        "type": "vis"
      },
      {
        "config": {
          "axis": {
            "x": {
              "domain": {
                "rounding": false,
                "type": "fit"
              },
              "grid": {
                "visible": true
              },
              "labels": {
                "orientation": "horizontal"
              },
              "scale": "ordinal",
              "ticks": {
                "visible": true
              },
              "title": {
                "visible": false
              }
            },
            "y": {
              "anchor": "start",
              "domain": {
                "rounding": true,
                "type": "full"
              },
              "grid": {
                "visible": true
              },
              "labels": {
                "orientation": "horizontal"
              },
              "scale": "linear",
              "ticks": {
                "visible": true
              },
              "title": {
                "visible": true
              }
            }
          },
          "layers": [
            {
              "data_source": {
                "query": "FROM kibana_sample_data_logs | STATS count = COUNT() BY BUCKET(@timestamp, 75, ?_tstart, ?_tend)",
                "type": "esql"
              },
              "ignore_global_filters": false,
              "sampling": 1,
              "type": "line",
              "x": {
                "column": "BUCKET(@timestamp, 75, ?_tstart, ?_tend)"
              },
              "y": [
                {
                  "axis_id": "y",
                  "column": "count"
                }
              ]
            }
          ],
          "legend": {
            "layout": {
              "truncate": {
                "max_lines": 1
              },
              "type": "grid"
            },
            "placement": "outside",
            "position": "right",
            "visibility": "hidden"
          },
          "styling": {
            "interpolation": "linear",
            "overlays": {
              "current_time_marker": {
                "visible": false
              },
              "partial_buckets": {
                "visible": false
              }
            },
            "points": {
              "visibility": "auto"
            }
          },
          "title": "Requests over time",
          "type": "xy"
        },
        "grid": {
          "h": 10,
          "w": 24,
          "x": 24,
          "y": 5
        },
        "id": "a1b2c3d4-0001-4000-8000-000000000003",
        "type": "vis"
      },
      {
        "config": {
          "data_source": {
            "index_pattern": "kibana_sample_data_logs",
            "time_field": "timestamp",
            "type": "data_view_spec"
          },
          "ignore_global_filters": false,
          "metrics": [
            {
              "empty_as_null": false,
              "field": "clientip",
              "operation": "unique_count",
              "type": "primary"
            }
          ],
          "sampling": 1,
          "styling": {
            "primary": {
              "labels": {
                "alignment": "left"
              },
              "position": "bottom",
              "value": {
                "alignment": "right",
                "sizing": "auto"
              }
            }
          },
          "title": "Unique visitors",
          "type": "metric"
        },
        "grid": {
          "h": 10,
          "w": 24,
          "x": 24,
          "y": 8
        },
        "id": "a1b2c3d4-0001-4000-8000-000000000004",
        "type": "vis"
      }
    ],
    "pinned_panels": [],
    "title": "Web logs overview"
  },
  "id": "3c4b8e10-d57a-11ef-9a52-4f3c2a8d0e1b",
  "meta": {
    "managed": false,
    "updated_at": "2026-04-13T11:00:00.000Z",
    "version": "WzEwMywxXQ=="
  }
}

{
  "data": {
    "options": {
      "auto_apply_filters": true,
      "hide_panel_borders": false,
      "hide_panel_titles": false,
      "sync_colors": false,
      "sync_cursor": true,
      "sync_tooltips": false,
      "use_margins": true
    },
    "panels": [
      {
        "config": {
          "data_source": {
            "index_pattern": "kibana_sample_data_logs",
            "time_field": "timestamp",
            "type": "data_view_spec"
          },
          "ignore_global_filters": false,
          "metrics": [
            {
              "empty_as_null": false,
              "operation": "count",
              "type": "primary"
            }
          ],
          "sampling": 1,
          "styling": {
            "primary": {
              "labels": {
                "alignment": "left"
              },
              "position": "bottom",
              "value": {
                "alignment": "right",
                "sizing": "auto"
              }
            }
          },
          "title": "",
          "type": "metric"
        },
        "grid": {
          "h": 5,
          "w": 12,
          "x": 0,
          "y": 0
        },
        "id": "a1b2c3d4-0001-4000-8000-000000000001",
        "type": "vis"
      }
    ],
    "pinned_panels": [],
    "title": "Web logs overview"
  },
  "id": "3c4b8e10-d57a-11ef-9a52-4f3c2a8d0e1b",
  "meta": {
    "created_at": "2026-04-13T10:00:00.000Z",
    "managed": false,
    "updated_at": "2026-04-13T10:00:00.000Z",
    "version": "WzEwMiwxXQ=="
  }
}

Path Parameters

Request { access_control , description , esql_approximation , filters , options , panels , pinned_panels , project_routing , query , refresh_interval , tags , time_range , title , }

Responses

Request