# Update dashboard components

Replace the component and group configuration for a dashboard.

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

`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](/docs/api) 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
```bash
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`**

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