Add Custom Domain to Status Page

POST /api/status-pages/domains

Adds a custom hostname to an existing status page and returns the DNS TXT record needed for verification. Admin-only.

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.example.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.example.com"
  }'

Response

{
  "domain": {
    "id": 42,
    "hostname": "status.example.com",
    "status": "pending",
    "role": "status_page",
    "verificationToken": "abc123-def456-ghi789",
    "verifiedAt": null,
    "createdAt": "2026-05-01T11:00:00.000Z",
    "updatedAt": "2026-05-01T11:00:00.000Z"
  },
  "dns": {
    "txtName": "_uptimeify-verify.status.example.com",
    "txtValue": "abc123-def456-ghi789"
  }
}

Common errors

401 Unauthorized when not authenticated
403 Forbidden when not an admin
404 Not found when the status page does not exist
409 Conflict when the hostname is already in use
422 Unprocessable Entity when the hostname is reserved or invalid