Update dashboard components — StatusDashboard Docs

PUT /app/dashboards/{id}/components

Replaces the component display settings and group configuration for a dashboard. This is a full replacement — the entire components map and groups object are overwritten.

Path parameters

Parameter	Description
`id`	The UUID of the dashboard.

Request

See API Basics for required headers.

Request body

Field	Type	Description
`compact`	boolean	Use a more compact layout when many components are displayed.
`components`	object	Full replacement map of `componentId` → `{ displayOrder: number, groupId?: string }`. All component IDs must belong to the caller's organization.
`groups`	object	Component grouping configuration.

`groups` object

Field	Type	Description
`enabled`	boolean	Whether component groups are displayed on the status dashboard.
`expandByDefault`	boolean	Whether all named groups start expanded when a visitor loads the page. When `false`, all named groups start collapsed. Applies dashboard-wide, not per group. Ungrouped components are not auto-expanded.
`items`	array	Ordered list of group definitions. Each item requires `id` (UUID), `name` (max 50 chars), and `order` (integer). Optional `description` (max 150 chars) shown under the group name on the public dashboard.

Sample request

curl -X PUT https://api.statusdashboard.com/app/dashboards/a1b2c3d4-e5f6-7890-abcd-ef1234567890/components \
  -H "Authorization: Bearer bcf847abf5c6:def456" \
  -H "Content-Type: application/json" \
  -d '{
    "compact": false,
    "groups": {
      "enabled": true,
      "expandByDefault": true,
      "items": [
        { "id": "d4e5f6a7-b8c9-0123-def0-234567890123", "name": "Infrastructure", "order": 1 }
      ]
    },
    "components": {
      "a1b2c3d4-e5f6-7890-abcd-ef1234567891": { "displayOrder": 1 },
      "f6a7b8c9-d0e1-2345-f012-456789012345": { "displayOrder": 2, "groupId": "d4e5f6a7-b8c9-0123-def0-234567890123" }
    }
  }'

Sample response

Status: 200 OK

{
  "compact": false,
  "groups": {
    "enabled": true,
    "expandByDefault": true,
    "items": [
      { "id": "d4e5f6a7-b8c9-0123-def0-234567890123", "name": "Infrastructure", "order": 1 }
    ]
  },
  "components": {
    "a1b2c3d4-e5f6-7890-abcd-ef1234567891": { "displayOrder": 1 },
    "f6a7b8c9-d0e1-2345-f012-456789012345": { "displayOrder": 2, "groupId": "d4e5f6a7-b8c9-0123-def0-234567890123" }
  }
}

Error responses

Status	When
`400`	Validation failure — invalid component IDs, duplicate display orders, or group reference errors.
`403`	Insufficient permissions.
`404`	Dashboard not found or does not belong to the caller's organization.