Set a custom domain

Assigns a custom domain, optionally moving it from another page, and returns verification and health details.

PUT https://app.upfour.io/v1/status-pages/{pageID}/custom-domain

A real request. Sending it changes data in your up4 account.

Authorization

AuthorizationA pls_ key. It stays in this browser tab. Needs status_page.write.

Path

pageIDpath · requiredPart of the request path.

Body

domainrequired

More fields1

move_from_page_id Take the domain over from another status page of the same company.

Sent directly from your browser to https://app.upfour.io/v1. Mutating calls get an automatic Idempotency-Key when the field is empty.

Request

Responsenot sent yet

Fill in a key and press Send request (⌘↵).
The answer appears here.

scope status_page.write stable returns 200

Parameters

Field	Type	Description
`pageID` required	uuid	path parameter

Body

application/json required 2 fields

domainstringrequired

All other fields1 fields

move_from_page_iduuid

Take the domain over from another status page of the same company.

Returns

A successful request returns 200 with application/json.

Response fields 1 top-level fields

Field Type Description

data StatusPageDomainDetails

StatusPageDomainDetails · 101 fields

Field Type Description

page StatusPage · nullable

StatusPage · 61 fields

Field Type Description

accent_color string

announcement string

appearance StatusPageAppearanceResponse · nullable null until a layout was chosen; the page then renders the default design (essential layout, paper ground).

StatusPageAppearanceResponse · 5 fields

Field	Type	Description
`ground`	string one of`paperwhitecool`	Empty is stored as paper.
`header_dark`	string	#RRGGBB or empty for the platform default.
`header_light`	string	#RRGGBB or empty for the platform default.
`layout`	string one of`essentialbrandoverview`
`version`	integer	Must be 1.

automatic_reports boolean

automatic_reports_notify boolean

company_name string

company_url string

contact_url string

created_at string (date-time)

custom_css string

custom_domain string

custom_domain_certificate_status string one ofnonependingissuedfailedunknown

custom_domain_status string one ofnonepending_dnsqueuedprovisioningactivefaileddisabledconflict_requires_review

custom_js string Not supported: always empty.

default_language string · nullable Language of the page's own communication; null inherits from the client, then the company default.

design string No effect since Plan 82; accepted and stored only.

google_tag_id string Not supported: always empty.

header_layout string No effect since Plan 82; accepted and stored only.

hide_from_search_engines boolean

history_days integer

id uuid

is_published boolean

logo_url string

minimum_incident_length integer

organization_id uuid

password_protected boolean

remove_branding boolean

show_not_monitored_as_green boolean

subdomain string

subscribable boolean

theme string

timezone string

updated_at string (date-time)

uptime_decimals integer

access_restricted boolean Whether any visitor gate (password, e-mail codes, IP allowlist or access token) is on. Only in GET /status-pages.

auto_report_open_template_id uuid

auto_report_resolve_template_id uuid

client_id uuid

custom_domain_attempts integer

custom_domain_cleanup_requested_at string (date-time)

custom_domain_dns_target string

custom_domain_error string

custom_domain_last_checked_at string (date-time)

custom_domain_next_retry_at string (date-time)

custom_domain_pending_expires_at string (date-time)

custom_domain_ploi_tenant string

custom_domain_provisioned_at string (date-time)

custom_domain_verification_token string Value of the up4-status-verification TXT record that proves ownership of the domain.

custom_domain_verified_at string (date-time)

favicon_url string

logo_asset_url string

logo_dark_asset_url string

platform_url string

public_url string Where the page is reachable: the custom domain once active, else the platform address.

reply_to_email string

subscriber_count integer Confirmed, active subscribers. Only in GET /status-pages.

platform_url string The page's address under the platform domain.

public_url string

challenge StatusPageDomainChallenge

StatusPageDomainChallenge · 14 fields

Field	Type	Description
`created_at`	string (date-time)
`domain`	string
`id`	uuid
`organization_id`	uuid
`pending_expires_at`	string (date-time)
`status`	string one of`pending_dnsconflict_requires_review`
`status_page_id`	uuid
`updated_at`	string (date-time)
`error`	string
`incumbent_organization_id`	uuid
`incumbent_status_page_id`	uuid
`last_checked_at`	string (date-time)
`verification_token`	string
`verified_at`	string (date-time)

cname_name string

cname_target string

entitlement StatusPageDomainEntitlement

StatusPageDomainEntitlement · 10 fields

Field	Type	Description
`can_purchase`	boolean
`limit`	integer
`metered`	boolean
`over_limit`	boolean
`pack_slots`	integer
`paid_slots`	integer
`plan_included`	integer
`unit_price_cents`	integer
`used`	integer
`renew_at`	string (date-time)

health StatusPageDomainHealth

StatusPageDomainHealth · 5 fields

Field	Type	Description
`status`	string one of`unknownhealthyunhealthy`
`checked_at`	string (date-time)
`error`	string
`error_code`	string one of`dns_invalidrouting_uncheckedrouting_changedcertificate_uncheckedcertificate_not_readyhttps_unreachableunknown`
`next_check_at`	string (date-time)

problem_code string one ofdns_not_foundtxt_not_foundhosting_setup_failedhosting_routing_failedhttps_pendinghttps_unreachablepublic_page_mismatchpublic_page_unreachableremoval_delayedclaim_releasedunknown

txt_name string

txt_value string

Errors

Only the errors this operation can return. Every error uses the same envelope.

Status	Code	Meaning
400	`bad_request`	The request is malformed or fails validation.
409	`domain_claimed`	The domain is in use by another Company. When: Setting a custom domain on a status page when another Company already holds it; details.domain names it. Fix: Prove control of the domain with the TXT record shown for the page, or use a different domain.
409	`domain_move_stale`	The page named as the domain's current holder is not the holder any more. When: Moving a domain with move_from_page_id set to a page that does not hold it; details.page names the real holder. Fix: Read the domain's current holder and send the move again with that page.
409	`domain_on_other_page`	The domain is used by another status page in the same Company. When: Setting a custom domain that another page of the Company already holds; details.page names that page. Fix: Move the domain on purpose by sending the holder's page id as the page to move from, or choose another domain.
409	`domain_removal_pending`	The domain is still being disconnected from its previous status page. When: Setting a domain right after it was removed from another page, before the disconnect finished. Fix: Try again in a few minutes.
409	`domain_used_in_company`	The domain is used by a status page in the Company that the caller cannot see. When: Setting a custom domain held by a page outside the caller's client scope; the page is not named. Fix: Ask someone with access to that page to move or remove the domain, or choose another domain.
400	`invalid_move_source`	The page to move the domain from is not valid. When: Setting a domain with a move-from page id that is not a status page the caller can use. Fix: Send the id of the status page that holds the domain.
404	`not_found`	The requested resource does not exist or is outside the caller's scope.
402	`payment_required`	The account does not have the credit or plan required for this action.
403	`permission_denied`	The credentials do not permit this action.

Every call can also return unauthorized (401), rate_limit_exceeded (429) or internal_error (500 / 502). See Responses and errors.

curl -s -X PUT "https://app.upfour.io/v1/status-pages/00000000-0000-4000-8000-000000000001/custom-domain" \ -H "Authorization: Bearer $UP4_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "domain": "status.example.com" }'

const res = await fetch("https://app.upfour.io/v1/status-pages/00000000-0000-4000-8000-000000000001/custom-domain", { method: "PUT", headers: { Authorization: `Bearer ${process.env.UP4_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ domain: "status.example.com", }), }); console.log(res.status, await res.json());

import os import requests res = requests.put( "https://app.upfour.io/v1/status-pages/00000000-0000-4000-8000-000000000001/custom-domain", headers={"Authorization": f"Bearer {os.environ['UP4_API_KEY']}"}, json={ "domain": "status.example.com", }, ) print(res.status_code, res.json())

package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { payload := strings.NewReader(`{ "domain": "status.example.com" }`) req, _ := http.NewRequest("PUT", "https://app.upfour.io/v1/status-pages/00000000-0000-4000-8000-000000000001/custom-domain", payload) req.Header.Set("Authorization", "Bearer "+os.Getenv("UP4_API_KEY")) req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() out, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(out)) }

<?php $payload = <<<'JSON' { "domain": "status.example.com" } JSON; $ch = curl_init("https://app.upfour.io/v1/status-pages/00000000-0000-4000-8000-000000000001/custom-domain"); curl_setopt_array($ch, [ CURLOPT_CUSTOMREQUEST => "PUT", CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("UP4_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => $payload, ]); $response = curl_exec($ch); echo curl_getinfo($ch, CURLINFO_RESPONSE_CODE), " ", $response, "\n"; curl_close($ch);

{ "data": { "cname_name": "status.example.com", "cname_target": "pages.example.test", "entitlement": { "can_purchase": false, "limit": 10, "metered": false, "over_limit": false, "pack_slots": 0, "paid_slots": 0, "plan_included": 10, "unit_price_cents": 200, "used": 1 }, "page": { "accent_color": "", "announcement": "Planned maintenance on Sunday from 02:00 to 03:00 UTC.", "appearance": null, "automatic_reports": false, "automatic_reports_notify": false, "company_name": "Acme GmbH", "company_url": "", "contact_url": "", "created_at": "2026-10-27T09:00:00Z", "custom_css": "", "custom_domain": "status.example.com", "custom_domain_certificate_status": "none", "custom_domain_dns_target": "pages.example.test", "custom_domain_next_retry_at": "2026-10-27T09:00:00Z", "custom_domain_pending_expires_at": "2026-11-10T09:00:00Z", "custom_domain_status": "pending_dns", "custom_domain_verification_token": "••••", "custom_js": "", "default_language": null, "design": "v2", "google_tag_id": "", "header_layout": "vertical", "hide_from_search_engines": false, "history_days": 90, "id": "00000000-0000-4000-8000-000000000001", "is_published": false, "logo_url": "", "minimum_incident_length": 0, "organization_id": "00000000-0000-4000-8000-000000000002", "password_protected": false, "platform_url": "https://example.com", "public_url": "https://example.com", "remove_branding": false, "show_not_monitored_as_green": false, "subdomain": "acme-status", "subscribable": false, "theme": "light", "timezone": "UTC", "updated_at": "2026-10-27T09:00:00Z", "uptime_decimals": 0 }, "platform_url": "https://example.com", "public_url": "https://example.com", "txt_name": "_up4-status.status.example.com", "txt_value": "up4-status-verification=721378bc96ef2ddece4a66b447ba60d6a1266860d9cb23f4" } }