Update dashboard domains — StatusDashboard Docs

PATCH /app/dashboards/{id}/domains

Updates the subdomain and/or sets a custom domain for a dashboard. Requires admin role. At least one of subdomain or customDomain must be provided.

Custom domain constraint: Once a custom domain is set, it cannot be changed via this endpoint. Use Delete custom domain to clear it first. Changing the subdomain while a custom domain is active does not affect the custom domain.

Path parameters

Parameter	Description
`id`	The UUID of the dashboard.

Request

See API Basics for required headers.

Request body

Field	Type	Description
`subdomain`	string	New subdomain slug. Lowercase letters, numbers, and hyphens only. Must start and end with a letter or number. Maximum 63 characters. Globally unique.
`customDomain`	string	Custom domain to configure (only if no custom domain is already set). Requires the Custom Domain feature entitlement. Must be a valid hostname without a port (e.g. `status.acme.com`). Apex domains are not supported.

Sample request

curl -X PATCH https://api.statusdashboard.com/app/dashboards/a1b2c3d4-e5f6-7890-abcd-ef1234567890/domains \
  -H "Authorization: Bearer bcf847abf5c6:def456" \
  -H "Content-Type: application/json" \
  -d '{
    "subdomain": "acme-prod",
    "customDomain": "status.acme.com"
  }'

Sample response

Status: 200 OK

{
  "subdomain": "acme-prod",
  "customDomain": "status.acme.com",
  "customDomainStatus": "awaiting_dns"
}

After setting a custom domain, use Activate custom domain once the required DNS CNAME record is in place.

Error responses

Status	When
`400`	Validation failure — invalid subdomain format or invalid domain.
`403`	Insufficient permissions.
`404`	Dashboard not found or does not belong to the caller's organization.
`409`	The requested subdomain or custom domain is already in use by another dashboard.