--- title: "Update a dashboard" method: PUT path: "/v1/dashboard/{dashboardId}" tags: ["Dashboard"] --- # Update a dashboard `PUT /v1/dashboard/{dashboardId}` ## Request - Base URL: `https://api.roark.ai` - URL: `https://api.roark.ai/v1/dashboard/{dashboardId}` - Auth: HTTP bearer Edits a dashboard. Omitted fields keep their current value. `widgets`, when sent, replaces the list: widgets are matched by name, so a widget that keeps its name keeps its id; a new name adds a widget and a name no longer listed removes it. To change one widget, PUT /v1/dashboard/{dashboardId}/widget/{widgetId}. ## Path parameters - `dashboardId` string, uuid, required ## Request body - UpdateDashboardInput: Omitted fields keep their current value. `widgets`, when sent, replaces the list: widgets are matched by name, so one that keeps its name keeps its id; a new name adds a widget and a missing one removes it. - `name` string - `description` string - `timeRange` union: The window: LAST n DAYS/WEEKS/MONTHS up to now, a CALENDAR_ALIGNED period (TODAY, YESTERDAY, THIS_WEEK, LAST_WEEK, THIS_MONTH, LAST_MONTH, THIS_YEAR, LAST_YEAR), FIXED from/to, or SINCE a date. At most 731 days (two years). - object - `type` 'LAST', required - `value` integer, required - `unit` 'DAYS' | 'WEEKS' | 'MONTHS', required - object - `type` 'CALENDAR_ALIGNED', required - `period` 'TODAY' | 'YESTERDAY' | 'THIS_WEEK' | 'LAST_WEEK' | 'THIS_MONTH' | 'LAST_MONTH' | 'THIS_YEAR' | 'LAST_YEAR', required - object - `type` 'FIXED', required - `from` string, date-time, required - `to` string, date-time, required - object - `type` 'SINCE', required - `from` string, date-time, required - `filters` object[] - `type` 'METRIC_PROPERTY' | 'CALL_PROPERTY' | 'AGENT_PROPERTY' | 'CALL_ID' | 'MODALITY' | 'DATASET' | 'METRIC_VALUE', required: What the filter narrows on. GET /v1/analytics/schema lists each type. - `property` string: The property to compare. Required for CALL_PROPERTY and METRIC_PROPERTY; may be omitted for AGENT_PROPERTY, DATASET, MODALITY and CALL_ID. - `operator` 'EQUALS' | 'NOT_EQUALS' | 'GREATER_THAN' | 'GREATER_THAN_OR_EQUAL_TO' | 'LESS_THAN' | 'LESS_THAN_OR_EQUAL_TO' | 'CONTAINS' | 'STARTS_WITH' | 'IS_SET' | 'IS_NOT_SET': Defaults to EQUALS. IS_SET / IS_NOT_SET (CALL_PROPERTY only) keep conversations where the property is set, whatever the value, or missing (never sent, sent as null, or removed); they take no value. - `value` union: The value to compare against (an agent id, "call" / "chat", a property value). Required except with IS_SET / IS_NOT_SET. - string - number - boolean - `isDefault` boolean - `widgets` object[] - `measures` object[], required: What to aggregate: 1 to 10 measures. - `type` 'METRIC' | 'CONVERSATION' | 'UPTIME': METRIC (default): a metric's values. CONVERSATION: conversation counts. UPTIME: health-check outcomes. - `metric` string: The metric's slug (e.g. `task_completion`) or id. Required for METRIC. - `aggregation` 'COUNT' | 'AVG' | 'MIN' | 'MAX' | 'SUM' | 'MEDIAN' | 'PERCENTILE' | 'PASS_RATE': Defaults by output type: AVG for numeric metrics, COUNT (split by value) for classification and text, PASS_RATE for thresholds and uptime, COUNT for conversations. - `percentile` integer: Required with PERCENTILE, e.g. 95. - `distinctBy` 'NONE' | 'CALL': CALL (default for metrics) folds each conversation to one value first, so a long call does not outweigh a short one. NONE aggregates every value. - `nestedAggregation` 'COUNT' | 'AVG' | 'MIN' | 'MAX' | 'SUM' | 'MEDIAN' | 'PERCENTILE' | 'PASS_RATE': How each conversation is folded when distinctBy is CALL. Defaults to SUM under SUM, else AVG. - `nestedAggregationPercentile` integer - `passOperator` 'EQUALS' | 'NOT_EQUALS' | 'GREATER_THAN' | 'GREATER_THAN_OR_EQUAL_TO' | 'LESS_THAN' | 'LESS_THAN_OR_EQUAL_TO' | 'CONTAINS' | 'STARTS_WITH' | 'IS_SET' | 'IS_NOT_SET': PASS_RATE condition operator. Omit for a threshold metric: its own condition is used. - `passValue` union: PASS_RATE condition value, e.g. 4 or "resolved". - string - number - boolean - `breakdown` object: Split the measure into one series per value of this dimension (the largest 50 are returned). Ignored while comparisonGroups are set: each group is then one series. - `type` 'METRIC_PROPERTY' | 'CALL_PROPERTY' | 'AGENT_PROPERTY' | 'DATASET', required - `property` string: The property to split by. Required for CALL_PROPERTY and METRIC_PROPERTY. - `filters` object[]: Filters for this measure only, on top of the query's filters. - `type` 'METRIC_PROPERTY' | 'CALL_PROPERTY' | 'AGENT_PROPERTY' | 'CALL_ID' | 'MODALITY' | 'DATASET' | 'METRIC_VALUE', required: What the filter narrows on. GET /v1/analytics/schema lists each type. - `property` string: The property to compare. Required for CALL_PROPERTY and METRIC_PROPERTY; may be omitted for AGENT_PROPERTY, DATASET, MODALITY and CALL_ID. - `operator` 'EQUALS' | 'NOT_EQUALS' | 'GREATER_THAN' | 'GREATER_THAN_OR_EQUAL_TO' | 'LESS_THAN' | 'LESS_THAN_OR_EQUAL_TO' | 'CONTAINS' | 'STARTS_WITH' | 'IS_SET' | 'IS_NOT_SET': Defaults to EQUALS. IS_SET / IS_NOT_SET (CALL_PROPERTY only) keep conversations where the property is set, whatever the value, or missing (never sent, sent as null, or removed); they take no value. - `value` union: The value to compare against (an agent id, "call" / "chat", a property value). Required except with IS_SET / IS_NOT_SET. - string - number - boolean - `isBaseline` boolean: Mark one measure as the baseline: every series also reports its value as a percentage of it. - `color` 'GREEN' | 'RED' | 'ORANGE' | 'PURPLE' | 'GREY' | 'BLUE' | 'PEACH' | 'TEAL' | 'INDIGO' | 'AMBER' | 'ROSE' | 'CYAN': Chart color on a dashboard. - `filters` object[]: Applied to every measure, on top of each measure's own filters. - `type` 'METRIC_PROPERTY' | 'CALL_PROPERTY' | 'AGENT_PROPERTY' | 'CALL_ID' | 'MODALITY' | 'DATASET' | 'METRIC_VALUE', required: What the filter narrows on. GET /v1/analytics/schema lists each type. - `property` string: The property to compare. Required for CALL_PROPERTY and METRIC_PROPERTY; may be omitted for AGENT_PROPERTY, DATASET, MODALITY and CALL_ID. - `operator` 'EQUALS' | 'NOT_EQUALS' | 'GREATER_THAN' | 'GREATER_THAN_OR_EQUAL_TO' | 'LESS_THAN' | 'LESS_THAN_OR_EQUAL_TO' | 'CONTAINS' | 'STARTS_WITH' | 'IS_SET' | 'IS_NOT_SET': Defaults to EQUALS. IS_SET / IS_NOT_SET (CALL_PROPERTY only) keep conversations where the property is set, whatever the value, or missing (never sent, sent as null, or removed); they take no value. - `value` union: The value to compare against (an agent id, "call" / "chat", a property value). Required except with IS_SET / IS_NOT_SET. - string - number - boolean - `interval` 'HOUR' | 'DAY' | 'WEEK' | 'MONTH': Bucket size. Defaults from the window's length and steps coarser when the window would exceed 500 buckets. - `comparisonMode` 'NONE' | 'PREVIOUS_PERIOD': PREVIOUS_PERIOD adds the preceding window of the same length to every series. - `comparisonGroups` object[]: Run every measure once per named filter set, e.g. one group per agent. - `name` string, required: The series label; unique within the query. - `filters` object[], required - `type` 'METRIC_PROPERTY' | 'CALL_PROPERTY' | 'AGENT_PROPERTY' | 'CALL_ID' | 'MODALITY' | 'DATASET' | 'METRIC_VALUE', required: What the filter narrows on. GET /v1/analytics/schema lists each type. - `property` string: The property to compare. Required for CALL_PROPERTY and METRIC_PROPERTY; may be omitted for AGENT_PROPERTY, DATASET, MODALITY and CALL_ID. - `operator` 'EQUALS' | 'NOT_EQUALS' | 'GREATER_THAN' | 'GREATER_THAN_OR_EQUAL_TO' | 'LESS_THAN' | 'LESS_THAN_OR_EQUAL_TO' | 'CONTAINS' | 'STARTS_WITH' | 'IS_SET' | 'IS_NOT_SET': Defaults to EQUALS. IS_SET / IS_NOT_SET (CALL_PROPERTY only) keep conversations where the property is set, whatever the value, or missing (never sent, sent as null, or removed); they take no value. - `value` union: The value to compare against (an agent id, "call" / "chat", a property value). Required except with IS_SET / IS_NOT_SET. - string - number - boolean - `color` 'GREEN' | 'RED' | 'ORANGE' | 'PURPLE' | 'GREY' | 'BLUE' | 'PEACH' | 'TEAL' | 'INDIGO' | 'AMBER' | 'ROSE' | 'CYAN' - `name` string, required: Unique on the dashboard: how the widget is matched on update. - `description` string - `display` 'LINE' | 'NUMBER' | 'RADAR' | 'STACKED_BAR' | 'TABLE': Chart type. Defaults to LINE. - `size` 'SMALL' | 'MEDIUM' | 'LARGE' | 'EXTRA_LARGE': Grid width. Defaults to MEDIUM. ## Response `200` The updated dashboard - object - `data` Dashboard, required - `id` string, uuid, required - `name` string, required - `description` string, nullable, required - `isDefault` boolean, required - `configManaged` boolean, required: Managed by config as code (`kind: dashboard`). A managed dashboard is read-only here: edits return 409; change it in the config file. - `timeRange` union, required: The window: LAST n DAYS/WEEKS/MONTHS up to now, a CALENDAR_ALIGNED period (TODAY, YESTERDAY, THIS_WEEK, LAST_WEEK, THIS_MONTH, LAST_MONTH, THIS_YEAR, LAST_YEAR), FIXED from/to, or SINCE a date. At most 731 days (two years). - object - `type` 'LAST', required - `value` integer, required - `unit` 'DAYS' | 'WEEKS' | 'MONTHS', required - object - `type` 'CALENDAR_ALIGNED', required - `period` 'TODAY' | 'YESTERDAY' | 'THIS_WEEK' | 'LAST_WEEK' | 'THIS_MONTH' | 'LAST_MONTH' | 'THIS_YEAR' | 'LAST_YEAR', required - object - `type` 'FIXED', required - `from` string, date-time, required - `to` string, date-time, required - object - `type` 'SINCE', required - `from` string, date-time, required - `createdAt` string, required - `updatedAt` string, required - `filters` object[], required - `type` 'METRIC_PROPERTY' | 'CALL_PROPERTY' | 'AGENT_PROPERTY' | 'CALL_ID' | 'MODALITY' | 'DATASET' | 'METRIC_VALUE', required: What the filter narrows on. GET /v1/analytics/schema lists each type. - `property` string: The property to compare. Required for CALL_PROPERTY and METRIC_PROPERTY; may be omitted for AGENT_PROPERTY, DATASET, MODALITY and CALL_ID. - `operator` 'EQUALS' | 'NOT_EQUALS' | 'GREATER_THAN' | 'GREATER_THAN_OR_EQUAL_TO' | 'LESS_THAN' | 'LESS_THAN_OR_EQUAL_TO' | 'CONTAINS' | 'STARTS_WITH' | 'IS_SET' | 'IS_NOT_SET': Defaults to EQUALS. IS_SET / IS_NOT_SET (CALL_PROPERTY only) keep conversations where the property is set, whatever the value, or missing (never sent, sent as null, or removed); they take no value. - `value` union: The value to compare against (an agent id, "call" / "chat", a property value). Required except with IS_SET / IS_NOT_SET. - string - number - boolean - `widgets` object[], required - `measures` object[], required: What to aggregate: 1 to 10 measures. - `type` 'METRIC' | 'CONVERSATION' | 'UPTIME': METRIC (default): a metric's values. CONVERSATION: conversation counts. UPTIME: health-check outcomes. - `metric` string: The metric's slug (e.g. `task_completion`) or id. Required for METRIC. - `aggregation` 'COUNT' | 'AVG' | 'MIN' | 'MAX' | 'SUM' | 'MEDIAN' | 'PERCENTILE' | 'PASS_RATE': Defaults by output type: AVG for numeric metrics, COUNT (split by value) for classification and text, PASS_RATE for thresholds and uptime, COUNT for conversations. - `percentile` integer: Required with PERCENTILE, e.g. 95. - `distinctBy` 'NONE' | 'CALL': CALL (default for metrics) folds each conversation to one value first, so a long call does not outweigh a short one. NONE aggregates every value. - `nestedAggregation` 'COUNT' | 'AVG' | 'MIN' | 'MAX' | 'SUM' | 'MEDIAN' | 'PERCENTILE' | 'PASS_RATE': How each conversation is folded when distinctBy is CALL. Defaults to SUM under SUM, else AVG. - `nestedAggregationPercentile` integer - `passOperator` 'EQUALS' | 'NOT_EQUALS' | 'GREATER_THAN' | 'GREATER_THAN_OR_EQUAL_TO' | 'LESS_THAN' | 'LESS_THAN_OR_EQUAL_TO' | 'CONTAINS' | 'STARTS_WITH' | 'IS_SET' | 'IS_NOT_SET': PASS_RATE condition operator. Omit for a threshold metric: its own condition is used. - `passValue` union: PASS_RATE condition value, e.g. 4 or "resolved". - string - number - boolean - `breakdown` object: Split the measure into one series per value of this dimension (the largest 50 are returned). Ignored while comparisonGroups are set: each group is then one series. - `type` 'METRIC_PROPERTY' | 'CALL_PROPERTY' | 'AGENT_PROPERTY' | 'DATASET', required - `property` string: The property to split by. Required for CALL_PROPERTY and METRIC_PROPERTY. - `filters` object[]: Filters for this measure only, on top of the query's filters. - `type` 'METRIC_PROPERTY' | 'CALL_PROPERTY' | 'AGENT_PROPERTY' | 'CALL_ID' | 'MODALITY' | 'DATASET' | 'METRIC_VALUE', required: What the filter narrows on. GET /v1/analytics/schema lists each type. - `property` string: The property to compare. Required for CALL_PROPERTY and METRIC_PROPERTY; may be omitted for AGENT_PROPERTY, DATASET, MODALITY and CALL_ID. - `operator` 'EQUALS' | 'NOT_EQUALS' | 'GREATER_THAN' | 'GREATER_THAN_OR_EQUAL_TO' | 'LESS_THAN' | 'LESS_THAN_OR_EQUAL_TO' | 'CONTAINS' | 'STARTS_WITH' | 'IS_SET' | 'IS_NOT_SET': Defaults to EQUALS. IS_SET / IS_NOT_SET (CALL_PROPERTY only) keep conversations where the property is set, whatever the value, or missing (never sent, sent as null, or removed); they take no value. - `value` union: The value to compare against (an agent id, "call" / "chat", a property value). Required except with IS_SET / IS_NOT_SET. - string - number - boolean - `isBaseline` boolean: Mark one measure as the baseline: every series also reports its value as a percentage of it. - `color` 'GREEN' | 'RED' | 'ORANGE' | 'PURPLE' | 'GREY' | 'BLUE' | 'PEACH' | 'TEAL' | 'INDIGO' | 'AMBER' | 'ROSE' | 'CYAN': Chart color on a dashboard. - `filters` object[]: Applied to every measure, on top of each measure's own filters. - `type` 'METRIC_PROPERTY' | 'CALL_PROPERTY' | 'AGENT_PROPERTY' | 'CALL_ID' | 'MODALITY' | 'DATASET' | 'METRIC_VALUE', required: What the filter narrows on. GET /v1/analytics/schema lists each type. - `property` string: The property to compare. Required for CALL_PROPERTY and METRIC_PROPERTY; may be omitted for AGENT_PROPERTY, DATASET, MODALITY and CALL_ID. - `operator` 'EQUALS' | 'NOT_EQUALS' | 'GREATER_THAN' | 'GREATER_THAN_OR_EQUAL_TO' | 'LESS_THAN' | 'LESS_THAN_OR_EQUAL_TO' | 'CONTAINS' | 'STARTS_WITH' | 'IS_SET' | 'IS_NOT_SET': Defaults to EQUALS. IS_SET / IS_NOT_SET (CALL_PROPERTY only) keep conversations where the property is set, whatever the value, or missing (never sent, sent as null, or removed); they take no value. - `value` union: The value to compare against (an agent id, "call" / "chat", a property value). Required except with IS_SET / IS_NOT_SET. - string - number - boolean - `interval` 'HOUR' | 'DAY' | 'WEEK' | 'MONTH': Bucket size. Defaults from the window's length and steps coarser when the window would exceed 500 buckets. - `comparisonMode` 'NONE' | 'PREVIOUS_PERIOD': PREVIOUS_PERIOD adds the preceding window of the same length to every series. - `comparisonGroups` object[]: Run every measure once per named filter set, e.g. one group per agent. - `name` string, required: The series label; unique within the query. - `filters` object[], required - `type` 'METRIC_PROPERTY' | 'CALL_PROPERTY' | 'AGENT_PROPERTY' | 'CALL_ID' | 'MODALITY' | 'DATASET' | 'METRIC_VALUE', required: What the filter narrows on. GET /v1/analytics/schema lists each type. - `property` string: The property to compare. Required for CALL_PROPERTY and METRIC_PROPERTY; may be omitted for AGENT_PROPERTY, DATASET, MODALITY and CALL_ID. - `operator` 'EQUALS' | 'NOT_EQUALS' | 'GREATER_THAN' | 'GREATER_THAN_OR_EQUAL_TO' | 'LESS_THAN' | 'LESS_THAN_OR_EQUAL_TO' | 'CONTAINS' | 'STARTS_WITH' | 'IS_SET' | 'IS_NOT_SET': Defaults to EQUALS. IS_SET / IS_NOT_SET (CALL_PROPERTY only) keep conversations where the property is set, whatever the value, or missing (never sent, sent as null, or removed); they take no value. - `value` union: The value to compare against (an agent id, "call" / "chat", a property value). Required except with IS_SET / IS_NOT_SET. - string - number - boolean - `color` 'GREEN' | 'RED' | 'ORANGE' | 'PURPLE' | 'GREY' | 'BLUE' | 'PEACH' | 'TEAL' | 'INDIGO' | 'AMBER' | 'ROSE' | 'CYAN' - `name` string, required: Unique on the dashboard: how the widget is matched on update. - `description` string - `display` 'LINE' | 'NUMBER' | 'RADAR' | 'STACKED_BAR' | 'TABLE': Chart type. Defaults to LINE. - `size` 'SMALL' | 'MEDIUM' | 'LARGE' | 'EXTRA_LARGE': Grid width. Defaults to MEDIUM. - `id` string, uuid, required ## Other responses - `400`: Invalid dashboard, or a widget the analytics store cannot answer - `401`: Unauthorized - `403`: Forbidden - `404`: Dashboard, widget or a referenced metric not found - `409`: The dashboard is managed by config as code - `429`: Too Many Requests - `500`: Internal Server Error ## Changes > 188 revisions in range; 1 not diffed. - **2026-10-21** `8913d3b08c7b`: 4 breaking, 10 warning, 14 info - the response property `data/filters/items/value` became optional for the status `200` - the response property `data/widgets/items/comparisonGroups/items/filters/items/value` became optional for the status `200` - the response property `data/widgets/items/filters/items/value` became optional for the status `200` - the response property `data/widgets/items/measures/items/filters/items/value` became optional for the status `200` - …24 more - **2026-10-21** `2e403107d6ec`: 1 info - endpoint added [Operation history](https://skmtc.dev/roarkhq/apis/roark-analytics-api/changes/v1/dashboard/:dashboardId/put.md) --- [API](https://skmtc.dev/roarkhq/apis/roark-analytics-api.md) - [All operations](https://skmtc.dev/roarkhq/apis/roark-analytics-api/llms.txt) - [OpenAPI document](https://skmtc.dev/roarkhq/apis/roark-analytics-api/revisions/efc3377249d1?raw)