Skip to main content
All status domain endpoints (except canIssueTls) require authentication.

​
requestVerification

Initiate custom domain verification for a status page. Returns DNS records that must be configured.

​
Input Parameters

​
statusPageId
string
required
ID of the status page to configure a custom domain for
​
hostname
string
required
Custom domain hostname. Must start with status. (e.g., status.example.com)

​
Response

​
statusPageId
string
Status page ID
​
hostname
string
The hostname being verified
​
verificationStatus
enum
Current verification status: "PENDING", "VERIFIED", or "FAILED"
​
cnameRecordName
string
DNS CNAME record name to configure
​
cnameRecordValue
string
DNS CNAME record value to configure
​
txtRecordName
string
DNS TXT record name to configure for verification
​
txtRecordValue
string
DNS TXT record value containing the verification token
const result = await trpc.statusDomain.requestVerification.mutate({
  statusPageId: "clx1234567890",
  hostname: "status.example.com"
});

console.log("Configure these DNS records:");
console.log(`CNAME: ${result.cnameRecordName} -> ${result.cnameRecordValue}`);
console.log(`TXT: ${result.txtRecordName} -> ${result.txtRecordValue}`);

​
DNS Configuration

After receiving the response, configure the following DNS records:
  1. CNAME Record: Points your custom domain to the Better Uptime status page service
    • Name: status.example.com
    • Value: status.betteruptime.app
  2. TXT Record: Proves domain ownership
    • Name: _betteruptime-verify.status.example.com
    • Value: The verification token provided

​
Error Codes

  • NOT_FOUND - Status page not found or doesn’t belong to user
  • CONFLICT - Hostname is already claimed by another status page

​
verify

Verify DNS configuration and activate the custom domain.

​
Input Parameters

​
statusPageId
string
required
Status page ID
​
hostname
string
required
Hostname to verify (must match the one from requestVerification)

​
Response

​
statusPageId
string
Status page ID
​
hostname
string
The hostname being verified
​
verificationStatus
enum
Updated verification status: "VERIFIED" on success, "FAILED" if DNS records are not correctly configured
​
txtVerified
boolean
Whether the TXT record verification passed
​
cnameVerified
boolean
Whether the CNAME record verification passed
​
cnameRecordName
string
Expected CNAME record name
​
cnameRecordValue
string
Expected CNAME record value
​
txtRecordName
string
Expected TXT record name
​
txtRecordValue
string
Expected TXT record value
​
verifiedAt
date | null
Timestamp when the domain was verified (null if not verified)
const result = await trpc.statusDomain.verify.mutate({
  statusPageId: "clx1234567890",
  hostname: "status.example.com"
});

if (result.verificationStatus === "VERIFIED") {
  console.log("Domain verified successfully!");
} else {
  console.log("Verification failed:");
  console.log(`TXT verified: ${result.txtVerified}`);
  console.log(`CNAME verified: ${result.cnameVerified}`);
}

​
Verification Process

The endpoint checks DNS records using multiple public DNS resolvers (Cloudflare and Google DNS) to ensure proper propagation. Both the CNAME and TXT records must be correctly configured for verification to pass.

​
Error Codes

  • NOT_FOUND - Domain mapping not found or doesn’t belong to user

​
canIssueTls

Check if TLS certificate issuance is allowed for a hostname. This is a public endpoint used by the TLS certificate automation system.
This endpoint does not require authentication and is intended for internal infrastructure use.

​
Input Parameters

​
hostname
string
required
Hostname to check TLS eligibility for

​
Response

​
allowed
boolean
Whether TLS certificate issuance is allowed for this hostname
const result = await trpc.statusDomain.canIssueTls.query({
  hostname: "status.example.com"
});

if (result.allowed) {
  console.log("TLS certificate issuance is allowed");
} else {
  console.log("TLS certificate issuance is not allowed");
}

​
Conditions for TLS Issuance

TLS certificate issuance is allowed when:
  • The hostname has a verified domain mapping
  • The associated status page is published
  • DNS verification has passed

Build docs developers (and LLMs) love

Get started for freeTalk to us