> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getbluejay.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /v1/widgets

> Create a widget.

Creates a widget on a dashboard.- `metrics` is required unless `chart_type` is `table`.
- `simulation_ids` must not be empty when `group_by` is `simulation`.
- `color_overrides` maps a label to a `#rrggbb` color. Labels match without case.## Headers

\<table><thead><tr><th>Name</th>
            \<th>Type</th>
            \<th>Required</th>
            \<th>Description</th></tr></thead>
        \<tbody /></table>

## Request body

\<table><thead><tr><th>Name</th>
            \<th>Type</th>
            \<th>Required</th>
            \<th>Description</th></tr></thead>
        \<tbody /></table>

## Response

\<table><thead><tr><th>Name</th>
            \<th>Type</th>
            \<th>Required</th>
            \<th>Description</th></tr></thead>
        \<tbody /></table>

## Status codes| Status | Meaning |
| - | - |
| `200` | Successful Response |
| `422` | Validation Error |## Example request```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
curl --request POST \
  --url https://api.getbluejay.ai/v1/widgets \
  --header 'X-API-Key: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "<string>",
    "description": "<string>",
    "chart_type": "line",
    "chart_mode": "time_series",
    "data_type": "observability",
    "bar_mode": "stacked",
    "aggregation": [
      "count"
    ],
    "time_bucket": "hour",
    "group_by": "agent",
    "simulation_ids": [
      123
    ],
    "show_indeterminate": false,
    "filters": [
      null
    ],
    "column_visibility": {
      "key": true
    },
    "color_overrides": {
      "key": "<string>"
    },
    "center_label": {
      "slice": "<string>",
      "clamp_pct": 1.5,
      "label": "<string>",
      "benchmark": 1.5,
      "compare_previous": true,
      "unit": "<string>"
    },
    "show_legend": true,
    "metrics": [
      {
        "metric": "<string>",
        "custom_metric_id": "<string>",
        "goal": "<string>",
        "tool_call_id": "<string>",
        "metadata_path": "<string>",
        "threshold_operator": "lt",
        "threshold_value": 1.5,
        "metadata_type": "<string>"
      }
    ],
    "dashboard_id": "<string>"
  }'
```## Example response```json 200 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "id": "<string>",
  "organization_id": "<string>",
  "name": "<string>",
  "description": "<string>",
  "chart_type": "<string>",
  "chart_mode": "<string>",
  "data_type": "<string>",
  "applies_to_all_agents": true,
  "bar_mode": "<string>",
  "aggregation": [
    "<string>"
  ],
  "time_bucket": "<string>",
  "group_by": "<string>",
  "simulation_ids": [
    123
  ],
  "show_indeterminate": true,
  "filters": null,
  "column_visibility": null,
  "color_overrides": {
    "key": "<string>"
  },
  "center_label": {
    "slice": "<string>",
    "clamp_pct": 1.5,
    "label": "<string>",
    "benchmark": 1.5,
    "compare_previous": true,
    "unit": "<string>"
  },
  "show_legend": true,
  "created_by": "<string>",
  "created_at": "<string>",
  "updated_at": "<string>",
  "widget_metrics": [],
  "layout": {
    "x": 123,
    "y": 123,
    "w": 123,
    "h": 123
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.