Create a dashboard widget
curl --request POST \
--url https://clarus-api.com/api/dashboard_widgets \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'X-Clarus-Subdomain: <api-key>' \
--data '
{
"data": {
"type": "dashboard_widgets",
"attributes": {
"code": "tasks-by-type",
"name": "Tasks by Type",
"description": "Open tasks grouped by task type",
"widget_type": "bar",
"report_query_id": 4,
"configuration": {
"metric": "total_records",
"color_palette": "default",
"show_legend": true,
"legend_position": "bottom",
"horizontal": false,
"log_scale": false,
"limit": 10
},
"dashboard_filters": {
"warehouse_id": 1
}
}
}
}
'import requests
url = "https://clarus-api.com/api/dashboard_widgets"
payload = { "data": {
"type": "dashboard_widgets",
"attributes": {
"code": "tasks-by-type",
"name": "Tasks by Type",
"description": "Open tasks grouped by task type",
"widget_type": "bar",
"report_query_id": 4,
"configuration": {
"metric": "total_records",
"color_palette": "default",
"show_legend": True,
"legend_position": "bottom",
"horizontal": False,
"log_scale": False,
"limit": 10
},
"dashboard_filters": { "warehouse_id": 1 }
}
} }
headers = {
"Authorization": "Bearer <token>",
"X-Clarus-Subdomain": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
Authorization: 'Bearer <token>',
'X-Clarus-Subdomain': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
data: {
type: 'dashboard_widgets',
attributes: {
code: 'tasks-by-type',
name: 'Tasks by Type',
description: 'Open tasks grouped by task type',
widget_type: 'bar',
report_query_id: 4,
configuration: {
metric: 'total_records',
color_palette: 'default',
show_legend: true,
legend_position: 'bottom',
horizontal: false,
log_scale: false,
limit: 10
},
dashboard_filters: {warehouse_id: 1}
}
}
})
};
fetch('https://clarus-api.com/api/dashboard_widgets', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"id": 12
}{
"error": "<string>"
}{
"errors": [
{
"code": 123,
"symbol": "<string>",
"details": "<string>",
"source": "<string>",
"context": {}
}
]
}Dashboard Widgets
Create a dashboard widget
Create a new dashboard widget. A widget is a chart component bound to a report query; the widget_type selects the chart rendering and configuration provides per-chart options (legend, palette, metric field, type-specific keys). The widget becomes visible to users only once it has been placed on a dashboard via the dashboard’s widget placement endpoint.
POST
/
api
/
dashboard_widgets
Create a dashboard widget
curl --request POST \
--url https://clarus-api.com/api/dashboard_widgets \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'X-Clarus-Subdomain: <api-key>' \
--data '
{
"data": {
"type": "dashboard_widgets",
"attributes": {
"code": "tasks-by-type",
"name": "Tasks by Type",
"description": "Open tasks grouped by task type",
"widget_type": "bar",
"report_query_id": 4,
"configuration": {
"metric": "total_records",
"color_palette": "default",
"show_legend": true,
"legend_position": "bottom",
"horizontal": false,
"log_scale": false,
"limit": 10
},
"dashboard_filters": {
"warehouse_id": 1
}
}
}
}
'import requests
url = "https://clarus-api.com/api/dashboard_widgets"
payload = { "data": {
"type": "dashboard_widgets",
"attributes": {
"code": "tasks-by-type",
"name": "Tasks by Type",
"description": "Open tasks grouped by task type",
"widget_type": "bar",
"report_query_id": 4,
"configuration": {
"metric": "total_records",
"color_palette": "default",
"show_legend": True,
"legend_position": "bottom",
"horizontal": False,
"log_scale": False,
"limit": 10
},
"dashboard_filters": { "warehouse_id": 1 }
}
} }
headers = {
"Authorization": "Bearer <token>",
"X-Clarus-Subdomain": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
Authorization: 'Bearer <token>',
'X-Clarus-Subdomain': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
data: {
type: 'dashboard_widgets',
attributes: {
code: 'tasks-by-type',
name: 'Tasks by Type',
description: 'Open tasks grouped by task type',
widget_type: 'bar',
report_query_id: 4,
configuration: {
metric: 'total_records',
color_palette: 'default',
show_legend: true,
legend_position: 'bottom',
horizontal: false,
log_scale: false,
limit: 10
},
dashboard_filters: {warehouse_id: 1}
}
}
})
};
fetch('https://clarus-api.com/api/dashboard_widgets', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"id": 12
}{
"error": "<string>"
}{
"errors": [
{
"code": 123,
"symbol": "<string>",
"details": "<string>",
"source": "<string>",
"context": {}
}
]
}Request Structure
{
"data": {
"type": "dashboard_widgets",
"attributes": {
"code": "tasks-by-type",
"name": "Tasks by Type",
"description": "Open tasks grouped by task type",
"widget_type": "bar",
"report_query_id": 4,
"configuration": {
"metric": "total_records",
"color_palette": "default",
"show_legend": true,
"legend_position": "bottom",
"horizontal": false,
"log_scale": false,
"limit": 10
},
"dashboard_filters": {
"warehouse_id": 1
}
}
}
}
Key Fields
| Field | Required | Description |
|---|---|---|
code | Yes | Unique widget code (max 30 chars) |
name | Yes | Display name (max 50 chars) |
description | No | Optional description (max 255 chars) |
widget_type | Yes | Chart rendering type. One of: area, bar, funnel, gauge, graph, grid, heatmap, line, pictorial_bar, pie, radar, sankey, scatter, single, sunburst, tree, treemap |
report_query_id | No | Linked report query that supplies the data |
configuration | No | Chart options — see per-widget-type reference below |
dashboard_filters | No | Default filter values applied to the report query when the widget renders, e.g. { "warehouse_id": 1 } |
configuration reference
The configuration JSON object’s keys vary by widget_type. All keys are snake_case.
Common keys
| Key | Type | Notes |
|---|---|---|
metric | string | Field from the report query result to chart (e.g. quantity, count, total_records) |
color_palette | string | One of default, vivid, pastel, cool, warm, mono |
show_legend | boolean | Toggle legend visibility (chart types that support a legend) |
legend_position | string | One of top, bottom, left, right |
limit | integer | 5, 10, or 20 — max data points (chart types where limiting applies) |
Per-type keys
widget_type | Type-specific keys | Example configuration |
|---|---|---|
bar | horizontal (bool), log_scale (bool) | { "metric": "quantity", "color_palette": "default", "show_legend": true, "legend_position": "bottom", "horizontal": false, "log_scale": false, "limit": 10 } |
line | smooth (bool), log_scale (bool) | { "metric": "quantity", "color_palette": "cool", "show_legend": true, "legend_position": "bottom", "smooth": true, "log_scale": false, "limit": 10 } |
area | smooth (bool), log_scale (bool) | { "metric": "total_records", "color_palette": "pastel", "show_legend": true, "legend_position": "bottom", "smooth": true, "log_scale": false, "limit": 10 } |
scatter | log_scale (bool) | { "metric": "quantity", "color_palette": "vivid", "show_legend": true, "legend_position": "bottom", "log_scale": false, "limit": 10 } |
pictorial_bar | horizontal (bool) | { "metric": "total_records", "color_palette": "vivid", "show_legend": true, "legend_position": "bottom", "horizontal": false, "limit": 10 } |
heatmap | — (common keys only, no legend) | { "metric": "quantity", "color_palette": "mono", "limit": 10 } |
pie | donut_hole (integer, 0–80), pie_label_content (name | value | percent | name_percent | name_value); no limit | { "metric": "count", "color_palette": "default", "show_legend": true, "legend_position": "bottom", "donut_hole": 36, "pie_label_content": "name_percent" } |
funnel | funnel_ascending (bool), funnel_min_size (integer, 0–50) | { "metric": "total_records", "color_palette": "warm", "show_legend": true, "legend_position": "bottom", "funnel_ascending": false, "funnel_min_size": 20, "limit": 10 } |
gauge | gauge_min (integer), gauge_max (integer), gauge_thresholds (none | traffic_light | reverse_traffic_light), gauge_format (number | percentage); no legend/limit | { "metric": "count", "color_palette": "default", "gauge_min": 0, "gauge_max": 100, "gauge_thresholds": "traffic_light", "gauge_format": "percentage" } |
graph | graph_layout (force | circular) | { "metric": "quantity", "color_palette": "cool", "show_legend": true, "legend_position": "bottom", "graph_layout": "force", "limit": 10 } |
radar | radar_max (integer; 0 = inferred from data) | { "metric": "quantity", "color_palette": "cool", "show_legend": true, "legend_position": "bottom", "radar_max": 100 } |
sankey | — (color + metric only) | { "metric": "quantity", "color_palette": "default" } |
sunburst | — (legend + color, no limit) | { "metric": "total_records", "color_palette": "pastel", "show_legend": true, "legend_position": "bottom" } |
tree | — (color + metric only, no legend/limit) | { "metric": "quantity", "color_palette": "default" } |
treemap | — (color + metric only, no legend/limit) | { "metric": "quantity", "color_palette": "cool" } |
single | single_color (green | blue | orange | purple | red | teal | pink | yellow); no legend/limit | { "metric": "count", "single_color": "green" } |
grid | Tabular data view. No configuration keys are currently consumed by the renderer; supply an empty object | {} |
Authorizations
OAuth 2.0 authentication. Use the client credentials or authorization code flow to obtain an access token.
The subdomain/tenant name identifying which tenant's data to access. Required for all API requests.
Body
application/json
Show child attributes
Show child attributes
Response
Dashboard widget created successfully. Response contains the new widget's id.
Identifier of the created widget
⌘I