Create dashboard — StatusDashboard Docs

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

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

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