--- title: "Update Widget" method: PUT path: "/v1/widgets/{widget_id}" tags: ["Widgets"] --- # Update Widget `PUT /v1/widgets/{widget_id}` Replace a widget's configuration and metrics (full replace; data_type cannot change). ## Path parameters - `widget_id` string, required ## Headers - `X-API-Key` string, required ## Request body - UpdateWidgetBody — Full-replace update (mirrors the dashboard editor): name, chart_type and metrics must always be sent; metrics replace the existing set. data_type is immutable after creation. - `name` string, required - `description` string, nullable - `chart_type` 'line' | 'bar' | 'pie' | 'table' | 'kpi' | 'pivot_table' | 'histogram', required - `chart_mode` 'time_series' | 'categorical', nullable - `bar_mode` 'stacked' | 'side_by_side', nullable - `aggregation` string[] - `time_bucket` 'hour' | 'day' | 'week' | 'month', nullable - `group_by` union - 'agent' | 'labels' | 'tool_call' | 'age' | 'gender' | 'simulation' - string - `simulation_ids` integer[] - `show_indeterminate` boolean - `filters` unknown[], nullable - unknown - `column_visibility` object, nullable - `color_overrides` object, nullable - `center_label` WidgetCenterLabelModel — Pie only: what the donut hole says. - `slice` string, nullable — Slice whose share fills the hole. Omit for the largest slice. - `clamp_pct` number, nullable — Collapses the rounding edges: 1 turns 99.6% into '>99%' and 0.4% into '<1%'. An exact 0 or 100 is left alone. - `label` string, nullable — Caption under the percentage - `show_legend` boolean, nullable - `metrics` WidgetMetricInput[] - `metric` string, required — Metric key, e.g. 'call_count', 'latency', 'custom_metric', 'goal', 'tool_call', 'trace_attribute' - `custom_metric_id` string, nullable — Required when metric='custom_metric': id from the custom metrics API - `goal` string, nullable — Goal text when metric='goal' - `tool_call_id` string, nullable — Required when metric='tool_call' - `metadata_path` string, nullable — Trace attribute path when metric='trace_attribute' - `threshold_operator` 'lt' | 'lte' | 'gt' | 'gte', nullable — With threshold_value: graph the share of conversations meeting the condition instead of the metric's own value - `threshold_value` number, nullable — Compared against the metric's per-conversation value; set together with threshold_operator - `metadata_type` string, nullable — Trace attribute value type when metric='trace_attribute' ## Response `200` Successful Response - WidgetModel - `id` string, required - `organization_id` string, nullable - `name` string, required - `description` string, nullable - `chart_type` string, required - `chart_mode` string, nullable - `data_type` string, required - `applies_to_all_agents` boolean - `bar_mode` string, nullable - `aggregation` string[], nullable - `time_bucket` string, nullable - `group_by` string, nullable - `simulation_ids` integer[], nullable - `show_indeterminate` boolean, nullable - `filters` unknown - `column_visibility` unknown - `color_overrides` object, nullable — The colour the chart draws each series or slice in, keyed by its label lowercased. Written whole when a widget is saved, so it names every label rather than only the ones a person changed. - `center_label` WidgetCenterLabelModel — Pie only: what the donut hole says. - `slice` string, nullable — Slice whose share fills the hole. Omit for the largest slice. - `clamp_pct` number, nullable — Collapses the rounding edges: 1 turns 99.6% into '>99%' and 0.4% into '<1%'. An exact 0 or 100 is left alone. - `label` string, nullable — Caption under the percentage - `show_legend` boolean — Whether the chart draws its colour key - `created_by` string, nullable - `created_at` string, nullable - `updated_at` string, nullable - `widget_metrics` WidgetMetricModel[] - `metric` string, required — Metric key, e.g. 'call_count', 'latency', 'custom_metric', 'goal', 'tool_call', 'trace_attribute' - `custom_metric_id` string, nullable — Required when metric='custom_metric': id from the custom metrics API - `goal` string, nullable — Goal text when metric='goal' - `tool_call_id` string, nullable — Required when metric='tool_call' - `metadata_path` string, nullable — Trace attribute path when metric='trace_attribute' - `threshold_operator` 'lt' | 'lte' | 'gt' | 'gte', nullable — With threshold_value: graph the share of conversations meeting the condition instead of the metric's own value - `threshold_value` number, nullable — Compared against the metric's per-conversation value; set together with threshold_operator - `metadata_type` string, nullable — Trace attribute value type when metric='trace_attribute' - `id` string, nullable - `widget_id` string, nullable - `layout` WidgetLayoutModel — Where a widget sits on a dashboard and how big it is. The field names are older than the grid they describe: x is the row and y is the column, both 1-based. The dashboard is six columns wide, and height is counted in 50px steps, so h=6 is the 300px a widget used to be and the range 2..18 is 100px..900px. - `x` integer, required — Row, 1-based, top to bottom - `y` integer, required — Column within the row, 1..6 - `w` integer, required — Width in columns, 1..6 - `h` integer, required — Height in 50px steps, 2..18 (100px..900px) ## Other responses - `422` — Validation Error ## Changes > 19 revisions in range; 16 could not be searched. - **2026-07-31** `4309a961859b` — 2 info - added the new `distribution` enum value to the request property `aggregation/items/` - added the new `histogram` enum value to the request property `chart_type` - **2026-07-26** `44d183272ce1` — 1 info - endpoint added [Change history](https://skmtc.dev/getbluejay/apis/bluejay-api/changes/v1/widgets/:widget_id/put.md) --- [API](https://skmtc.dev/getbluejay/apis/bluejay-api.md) · [All operations](https://skmtc.dev/getbluejay/apis/bluejay-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/getbluejay/bluejay-api/revisions/bf69ab7268a4/schema)