Update dashboard widget — StatusDashboard Docs

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 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

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

{
  "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.