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"
}
]
}
}
}{
"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": "INVALID_ARGUMENT",
"message": "Invalid request parameter",
"details": [
{
"field": "<string>",
"description": "<string>"
}
]
}
}{
"error": {
"code": "INTERNAL",
"message": "Internal server error",
"details": [
{
"description": "An unexpected error occurred"
}
]
}
}Widgets
Create widget
Create a new widget on a dashboard.
POST
/
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"
}
]
}
}
}{
"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": "INVALID_ARGUMENT",
"message": "Invalid request parameter",
"details": [
{
"field": "<string>",
"description": "<string>"
}
]
}
}{
"error": {
"code": "INTERNAL",
"message": "Internal server error",
"details": [
{
"description": "An unexpected error occurred"
}
]
}
}Authorizations
API key for authentication
Path Parameters
Dashboard resource ID (22-character ShortUUID)
Body
application/json
Human-readable widget name
Required string length:
1 - 255Widget type. Optional; defaults to chart when omitted.
Available options:
chart, table, text Example:
"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 created successfully
Widget resource
Show child attributes
Show child attributes
Was this page helpful?
⌘I