Update 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": {
    "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",
      "monitoring": "Monitoring",
      "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": [
          {}
        ]
      },
      "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"
      }
    ]
  }
}

PATCH

dashboards

{dashboard_id}

widgets

{widget_id}

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": {
    "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",
      "monitoring": "Monitoring",
      "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": [
          {}
        ]
      },
      "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

X-API-Key

string

header

required

API key for authentication

Path Parameters

dashboard_id

string

required

Dashboard resource ID (22-character ShortUUID)

Widget resource ID (22-character ShortUUID)

Body

application/json

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.

display_name

string

Updated widget name

Required string length: 1 - 255

type

enum<string>

Type 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

Available options:

chart,

table,

text

Example:

"chart"

grid_x

integer | null

Grid column position

grid_y

integer | null

Grid row position

grid_w

integer | null

Grid column span

grid_h

integer | null

Grid row span

config

object

Widget configuration, structure depends on widget type

Option 1
Option 2
Option 3

Show child attributes

Response

Widget updated successfully

Widget resource

Show child attributes

API

Runs

Simulations

Conversations

Agents

Mutations

Test Sets

Test Cases

Personas

Metrics

Run Templates

Scheduled Runs

Reviews

Dashboards

Alerts

Reports

Tags

Webhooks

Traces

Conversations Config

API Keys

Integrations

Authorizations

Path Parameters

Body

Response