# Create dashboard

Create a new status dashboard dashboard.

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

`POST /app/dashboards`

Creates a new dashboard.

If the organization has a dashboard quota configured (`enabledFeatures.dashboards`), this endpoint returns `403` when the quota is reached or when the dashboards feature is not enabled on the plan. Adding a custom domain also requires the `customDomain` feature to be enabled.

After creation, configure components, groups, and content settings using the [Update dashboard](/docs/api/status-dashboards/dashboards/update) endpoint. Feature-gated fields (`branding`, `customCode`, `widget`, `whitelabelEnabled`) are not accepted on create and must be set via the update endpoint.

***

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

### Request body
| Field           | Type    | Required | Description                                                                                                                                                                                           |
| --------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`          | string  | Yes      | Display name for the dashboard. Maximum 50 characters. Must be unique within the organization (case-insensitive).                                                                                     |
| `subdomain`     | string  | Yes      | Globally unique subdomain slug. Lowercase letters, numbers, and hyphens only. Maximum 63 characters. **Cannot be changed after creation.**                                                       |
| `compact`       | boolean | No       | Whether to use compact display mode. Defaults to `false`.                                                                                                                                             |
| `description`   | string  | No       | Short description shown on the dashboard. Maximum 500 characters.                                                                                                                                     |
| `systemMessage` | string  | No       | Optional message displayed at the top of the status dashboard, below the logo and above the status banner. Rich text field. See [Rich text fields](/docs/api#rich-text-fields). Max 1,000 characters. |
| `customDomain`  | string  | No       | Custom domain for the status dashboard (e.g. `status.acme.com`). Requires `customDomain` feature.                                                                                                     |
| `components`    | object  | No       | Map of `componentId` → `{ displayOrder: number, groupId?: string }`. Defaults to `{}` (no components).                                                                                                |
| `groups`        | object  | No       | Component grouping configuration. See below.                                                                                                                                                          |
| `content`       | object  | No       | Content sections to display. See below.                                                                                                                                                               |

#### `groups` object
| Field             | Type    | Description                                                                                                                                         |
| ----------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled`         | boolean | Whether component grouping is enabled.                                                                                                              |
| `expandByDefault` | boolean | Whether **all** named groups start expanded on initial load. When `false`, all named groups start collapsed. Dashboard-wide setting, not per group. |
| `items`           | array   | Array of group definitions: `{ id: uuid, name: string (max 50 chars), description?: string (max 150 chars), order: number }`.                       |

#### `content` object
All fields are optional booleans unless noted.

| Field                  | Type    | Description                                                   |
| ---------------------- | ------- | ------------------------------------------------------------- |
| `activeIncidents`      | boolean | Show currently active incidents.                              |
| `activeMaintenance`    | boolean | Show ongoing maintenance events.                              |
| `eventHistory`         | boolean | Show past events.                                             |
| `scheduledMaintenance` | boolean | Show scheduled maintenance windows.                           |
| `uptimeHistory`        | object  | `{ enabled: boolean, days: 1–7 }` — show uptime history bars. |

***

## Sample request
```bash
curl -X POST https://api.statusdashboard.com/app/dashboards \
  -H "Authorization: Bearer bcf847abf5c6:def456" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Status",
    "subdomain": "acme",
    "compact": false,
    "components": {}
  }'
```

## Sample response
**Status: `201 Created`**

```json
{
  "dashboard": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Production Status",
    "subdomain": "acme",
    "compact": false,
    "components": {},
    "createdAt": "2026-04-24T15:00:00.000Z",
    "updatedAt": "2026-04-24T15:00:00.000Z"
  }
}
```

The dashboard is immediately accessible at `https://acme.statusdashboard.io`.

***

## Error responses
| Status | When                                                                                                                                          |
| ------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | Validation failure — required field missing, subdomain format invalid, or request body malformed.                                             |
| `403`  | Insufficient permissions, the dashboards feature is not enabled, the dashboard quota is reached, or the custom domain feature is not enabled. |
| `409`  | The requested subdomain or custom domain is already in use, or a dashboard with this name already exists in the organization.                 |