# Update dashboard domains

Update the subdomain or set an initial custom domain for a dashboard.

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

`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](/docs/api/status-dashboards/dashboards/domains/custom-domain/delete) 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](/docs/api) 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
```bash
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`**

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

After setting a custom domain, use [Activate custom domain](/docs/api/status-dashboards/dashboards/domains/custom-domain/activate) 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. |