Add Custom Domain to Status Page
Adds a custom hostname to an existing status page and returns the DNS TXT record needed for verification. Organization-wide: admin or editor; customer-bound: by the page's ownership class.
POST /api/status-pages/domains
Access: Organization-wide callers need the role admin or editor (organization-wide readonly stays read-only). Customer-bound users (also with the role readonly) and customer-bound API tokens follow the page's ownership class instead: allowed on self_service pages, on managed pages only with the customer's canEditManaged exception, otherwise 403 with data.code: managed_by_organization.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
statusPageId | number | string | Yes | The status page ID or publicId |
hostname | string | Yes | The custom hostname (e.g. status.deinkunde.com) |
Example (cURL)
curl -X POST "$BASE_URL/api/status-pages/domains" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"statusPageId": 1,
"hostname": "status.deinkunde.com"
}'Response
{
"domain": {
"id": 42,
"hostname": "status.deinkunde.com",
"status": "pending",
"role": "status_page",
"verificationToken": "abc123-def456-ghi789",
"verifiedAt": null,
"lastVerificationError": null,
"lastVerificationErrorAt": null,
"createdAt": "2026-05-01T11:00:00.000Z",
"updatedAt": "2026-05-01T11:00:00.000Z",
"statusPageId": 1
},
"dns": {
"txtName": "_verify-status.status.deinkunde.com",
"txtValue": "abc123-def456-ghi789"
}
}Same shape as Get Status Page Domain: domain.statusPageId is the numeric id of the status page the domain was added to, also when the request named it by publicId.
Common errors
401 Unauthorizedwhen not authenticated403 Forbiddenwhen you are an organization-wide caller without the role admin or editor403 Forbidden(managed_by_organization) when you are customer-bound (user, also with the rolereadonly, or token) and the page ismanagedwithout the customer'scanEditManagedexception404 Not foundwhen the status page does not exist409 Conflictwhen the status page already has a domain (domainAlreadyExists) or your organization already has a row for this hostname (hostnameAlreadyInUse)400 Bad Requestwhen the hostname is invalid (invalidHostname) or reserved (hostnameReserved: the platform's own hosts and anything underuptimeify.io)
A hostname is only claimed once it is verified or active. Another organization's unverified request does not block yours; the claim is decided at Verify Status Page Domain. A pending request that is never verified is removed after 7 days.