# Update dashboard widget

Replace the widget configuration for a dashboard.

Source: https://statusdashboard.com/docs/api/status-dashboards/dashboards/widget/update

`PUT /app/dashboards/{id}/widget`

Replaces the embeddable widget configuration for a dashboard. This is a full replacement. Requires the **Widget** feature entitlement.

***

## Path parameters
| Parameter | Description                |
| --------- | -------------------------- |
| `id`      | The UUID of the dashboard. |

***

## Request
See [API Basics](/docs/api) for required headers.

### Request body
| Field             | Type                         | Description                                                                                                                                                                                                                                          |
| ----------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled`         | boolean                      | Whether the widget endpoints are active.                                                                                                                                                                                                             |
| `mode`            | `badge` \| `panel` \| `both` | Widget render mode. `badge` — floating pill always visible. `panel` — inline panel rendered inside a `data-sd-widget` target element. `both` — floating badge always visible; also renders an inline panel if a `data-sd-widget` element is present. |
| `title`           | string                       | Custom title shown in the widget header. Maximum 80 characters.                                                                                                                                                                                      |
| `components`      | string\[]                    | Component UUIDs to surface in the widget. Absent or empty = all dashboard components. Maximum 200 items.                                                                                                                                             |
| `theme`           | object                       | Widget theme configuration.                                                                                                                                                                                                                          |
| `pollingInterval` | integer                      | Seconds between status re-fetches. Minimum `30`, maximum `3600`.                                                                                                                                                                                     |

#### `theme` object
| Field             | Type   | Description                                                                                                       |
| ----------------- | ------ | ----------------------------------------------------------------------------------------------------------------- |
| `primaryColor`    | string | Hex primary accent color (e.g. `#2d7a7b`). When omitted, inherits from dashboard branding, then platform default. |
| `backgroundColor` | string | Hex background color override (e.g. `#ffffff`).                                                                   |
| `textColor`       | string | Hex text color override (e.g. `#111827`).                                                                         |

***

## Sample request
```bash
curl -X PUT https://api.statusdashboard.com/app/dashboards/a1b2c3d4-e5f6-7890-abcd-ef1234567890/widget \
  -H "Authorization: Bearer bcf847abf5c6:def456" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "mode": "badge",
    "title": "System Status",
    "components": [],
    "theme": {
      "primaryColor": "#2d7a7b",
      "backgroundColor": "#ffffff",
      "textColor": "#111827"
    },
    "pollingInterval": 60
  }'
```

## Sample response
**Status: `200 OK`**

```json
{
  "enabled": true,
  "mode": "badge",
  "title": "System Status",
  "components": [],
  "theme": {
    "primaryColor": "#2d7a7b",
    "backgroundColor": "#ffffff",
    "textColor": "#111827"
  },
  "pollingInterval": 60
}
```

***

## Error responses
| Status | When                                                                                     |
| ------ | ---------------------------------------------------------------------------------------- |
| `400`  | Validation failure — invalid mode, pollingInterval out of range, or too many components. |
| `403`  | Insufficient permissions, or the Widget feature is not enabled.                          |
| `404`  | Dashboard not found or does not belong to the caller's organization.                     |