Skip to main content
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
      }
    }
  }
}
'
{
  "id": 12
}

​
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

FieldRequiredDescription
codeYesUnique widget code (max 30 chars)
nameYesDisplay name (max 50 chars)
descriptionNoOptional description (max 255 chars)
widget_typeYesChart rendering type. One of: area, bar, funnel, gauge, graph, grid, heatmap, line, pictorial_bar, pie, radar, sankey, scatter, single, sunburst, tree, treemap
report_query_idNoLinked report query that supplies the data
configurationNoChart options — see per-widget-type reference below
dashboard_filtersNoDefault 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

KeyTypeNotes
metricstringField from the report query result to chart (e.g. quantity, count, total_records)
color_palettestringOne of default, vivid, pastel, cool, warm, mono
show_legendbooleanToggle legend visibility (chart types that support a legend)
legend_positionstringOne of top, bottom, left, right
limitinteger5, 10, or 20 — max data points (chart types where limiting applies)

​
Per-type keys

widget_typeType-specific keysExample configuration
barhorizontal (bool), log_scale (bool){ "metric": "quantity", "color_palette": "default", "show_legend": true, "legend_position": "bottom", "horizontal": false, "log_scale": false, "limit": 10 }
linesmooth (bool), log_scale (bool){ "metric": "quantity", "color_palette": "cool", "show_legend": true, "legend_position": "bottom", "smooth": true, "log_scale": false, "limit": 10 }
areasmooth (bool), log_scale (bool){ "metric": "total_records", "color_palette": "pastel", "show_legend": true, "legend_position": "bottom", "smooth": true, "log_scale": false, "limit": 10 }
scatterlog_scale (bool){ "metric": "quantity", "color_palette": "vivid", "show_legend": true, "legend_position": "bottom", "log_scale": false, "limit": 10 }
pictorial_barhorizontal (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 }
piedonut_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" }
funnelfunnel_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 }
gaugegauge_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" }
graphgraph_layout (force | circular){ "metric": "quantity", "color_palette": "cool", "show_legend": true, "legend_position": "bottom", "graph_layout": "force", "limit": 10 }
radarradar_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" }
singlesingle_color (green | blue | orange | purple | red | teal | pink | yellow); no legend/limit{ "metric": "count", "single_color": "green" }
gridTabular data view. No configuration keys are currently consumed by the renderer; supply an empty object{}

Authorizations

​
Authorization
string
header
required

OAuth 2.0 authentication. Use the client credentials or authorization code flow to obtain an access token.

​
X-Clarus-Subdomain
string
header
required

The subdomain/tenant name identifying which tenant's data to access. Required for all API requests.

Body

application/json
​
data
object
required

Response

Dashboard widget created successfully. Response contains the new widget's id.

​
id
integer

Identifier of the created widget