Skip to main content
POST
/
v1
/
dashboards
/
{dashboard_id}
/
widgets
curl --request POST \
  --url https://api.coval.dev/v1/dashboards/{dashboard_id}/widgets \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "display_name": "Response Time Trend",
  "type": "chart",
  "grid_x": 0,
  "grid_y": 0,
  "grid_w": 6,
  "grid_h": 4,
  "config": {
    "metricId": "metric_response_time",
    "visualizationType": "line",
    "monitoring": "Monitoring",
    "aggregation": "avg",
    "metricOutputType": "float",
    "bucketInterval": "1 hour",
    "yAxisLabel": "Seconds",
    "units": "s",
    "precision": 2
  }
}
'
{
  "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",
      "stacked": true,
      "grouped": true,
      "showAsPercentage": true,
      "groupBy": "agent",
      "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"
        }
      ]
    }
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.coval.dev/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
X-API-Key
string
header
required

API key for authentication

Path Parameters

​
dashboard_id
string
required

Dashboard resource ID (22-character ShortUUID)

Body

application/json
​
display_name
string
required

Human-readable widget name

Required string length: 1 - 255
​
type
enum<string>
required

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

Response

Widget created successfully

​
widget
object
required

Widget resource