curl --request PATCH \
--url https://api.coval.dev/v1/dashboards/{dashboard_id}/widgets/{widget_id} \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"display_name": "Updated Widget Name"
}
'{
"widget": {
"created_at": "2023-11-07T05:31:56Z",
"created_by": "<string>",
"updated_at": "2023-11-07T05:31:56Z",
"updated_by": "<string>",
"name": "dashboards/abc123def456ghi789jklm/widgets/wgt456xyz789abc012defg",
"type": "chart",
"create_time": "2025-10-14T12:00:00Z",
"update_time": "2025-10-15T14:30:00Z",
"display_name": "Response Time Chart",
"grid_x": 123,
"grid_y": 123,
"grid_w": 123,
"grid_h": 123,
"config": {
"metricId": "<string>",
"visualizationType": "line",
"conversation_source": "UPLOADED",
"aggregation": "avg",
"metricOutputType": "float",
"bucketInterval": "15 minutes",
"stacked": true,
"grouped": true,
"showAsPercentage": true,
"groupBy": "agent",
"groupByMetadataKey": "<string>",
"customColorMap": {},
"xAxisLabel": "<string>",
"yAxisLabel": "<string>",
"customSeriesNames": {},
"hiddenSeries": [
"<string>"
],
"precision": 1,
"units": "<string>",
"showCount": true,
"showRange": true,
"showStdDev": true,
"showBoxPlot": true,
"showTargetZone": true,
"filters": {
"metricIds": [
"<string>"
],
"agentIds": [
"<string>"
],
"agentMutationIds": [
"<string>"
],
"personaIds": [
"<string>"
],
"templateNames": [
"<string>"
],
"testSetIds": [
"<string>"
],
"metadata": [
{}
],
"tagFilters": [
"<string>"
]
},
"metricFilter": [
{
"metricId": "<string>",
"operator": ">=",
"value": 123,
"metricOutputType": "float"
}
]
}
}
}{
"error": {
"code": "INVALID_ARGUMENT",
"message": "Invalid request body",
"details": [
{
"field": "display_name",
"description": "display_name must be between 1 and 255 characters"
}
]
}
}{
"error": {
"code": "UNAUTHENTICATED",
"message": "Authentication failed",
"details": [
{
"field": "X-API-Key",
"description": "Invalid or missing API key"
}
]
}
}{
"error": {
"code": "NOT_FOUND",
"message": "Resource not found",
"details": [
{
"field": "dashboard_id",
"description": "Dashboard not found or not accessible by your organization"
}
]
}
}{
"error": {
"code": "INTERNAL",
"message": "Internal server error",
"details": [
{
"description": "An unexpected error occurred"
}
]
}
}Update widget
Update a widget.
curl --request PATCH \
--url https://api.coval.dev/v1/dashboards/{dashboard_id}/widgets/{widget_id} \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"display_name": "Updated Widget Name"
}
'{
"widget": {
"created_at": "2023-11-07T05:31:56Z",
"created_by": "<string>",
"updated_at": "2023-11-07T05:31:56Z",
"updated_by": "<string>",
"name": "dashboards/abc123def456ghi789jklm/widgets/wgt456xyz789abc012defg",
"type": "chart",
"create_time": "2025-10-14T12:00:00Z",
"update_time": "2025-10-15T14:30:00Z",
"display_name": "Response Time Chart",
"grid_x": 123,
"grid_y": 123,
"grid_w": 123,
"grid_h": 123,
"config": {
"metricId": "<string>",
"visualizationType": "line",
"conversation_source": "UPLOADED",
"aggregation": "avg",
"metricOutputType": "float",
"bucketInterval": "15 minutes",
"stacked": true,
"grouped": true,
"showAsPercentage": true,
"groupBy": "agent",
"groupByMetadataKey": "<string>",
"customColorMap": {},
"xAxisLabel": "<string>",
"yAxisLabel": "<string>",
"customSeriesNames": {},
"hiddenSeries": [
"<string>"
],
"precision": 1,
"units": "<string>",
"showCount": true,
"showRange": true,
"showStdDev": true,
"showBoxPlot": true,
"showTargetZone": true,
"filters": {
"metricIds": [
"<string>"
],
"agentIds": [
"<string>"
],
"agentMutationIds": [
"<string>"
],
"personaIds": [
"<string>"
],
"templateNames": [
"<string>"
],
"testSetIds": [
"<string>"
],
"metadata": [
{}
],
"tagFilters": [
"<string>"
]
},
"metricFilter": [
{
"metricId": "<string>",
"operator": ">=",
"value": 123,
"metricOutputType": "float"
}
]
}
}
}{
"error": {
"code": "INVALID_ARGUMENT",
"message": "Invalid request body",
"details": [
{
"field": "display_name",
"description": "display_name must be between 1 and 255 characters"
}
]
}
}{
"error": {
"code": "UNAUTHENTICATED",
"message": "Authentication failed",
"details": [
{
"field": "X-API-Key",
"description": "Invalid or missing API key"
}
]
}
}{
"error": {
"code": "NOT_FOUND",
"message": "Resource not found",
"details": [
{
"field": "dashboard_id",
"description": "Dashboard not found or not accessible by your organization"
}
]
}
}{
"error": {
"code": "INTERNAL",
"message": "Internal server error",
"details": [
{
"description": "An unexpected error occurred"
}
]
}
}Authorizations
API key for authentication
Headers
Workspace that scopes this operation. When omitted, the organization's active default workspace is used when one can be resolved.
1 - 26Path Parameters
Dashboard resource ID (22-character ShortUUID)
Widget resource ID (22-character ShortUUID)
Body
All fields optional (PATCH semantics). Unlike the dashboard-level config, which is replaced, config is MERGED into the stored blob one key at a time: a key you send replaces its stored value and a key you omit keeps its stored value. Three exceptions are worth knowing before you rely on that. Null-valued keys are dropped before the merge, so they do not clear anything -- and if dropping them leaves the object empty, the result is an empty object, which clears the whole blob. Sending "type": "table" validates config as a table widget, whose metricIds defaults to an empty list, so any table-widget PATCH that omits metricIds overwrites it with []; omitting "type" validates against the chart shape instead and leaves metricIds alone. Clearing a single key requires sending an empty value for it (for example "metricFilter": []), which is only possible for the list- and object-valued keys -- scalar keys such as metricId, aggregation or groupByMetadataKey have no empty value and cannot be individually cleared. To clear the whole blob, send an empty object.
Updated widget name
1 - 255Type of widget.
- chart: Visualization widget (line, bar, area, pie, histogram, statistic, top-list)
- table: Tabular data widget with multiple metrics
- text: Free-form text/markdown widget
chart, table, text, assignee_call_volume, assignee_call_history "chart"
Grid column position
Grid row position
Grid column span
Grid row span
Widget configuration, structure depends on widget type
- Option 1
- Option 2
- Option 3
Show child attributes
Show child attributes
Response
Widget updated successfully
Widget resource
Show child attributes
Show child attributes
Was this page helpful?