Add a custom domain
Claims hostname for this website and registers it with the Cactal edge. Custom domains must first be enabled for the website (websiteDomains.setEnabled, owner-only — enabling is the billing moment); the request fails with 403 custom_domains_disabled otherwise. Adding or removing domains on an enabled website never changes billing. The domain is created in pending_dns status, and the returned dnsRecords list exactly what to create at your DNS provider: an ownership TXT record on _cactal.<hostname> plus a routing record (a CNAME for subdomains or an A record for apex domains). Hostnames must be lowercase ASCII domains (not IP addresses or Cactal platform hosts), each website can have at most 10 custom domains, and a hostname can be claimed by only one website; claims that never verify expire after 7 days. After creating the records, call the verify endpoint or wait for the automatic re-checks.
Authorizations
Cactal API key. Create one in the dashboard or via POST /apiKeys. The plaintext key is shown once at creation.
Path Parameters
1Body
1Response
The created domain in pending_dns status. Next: create the dnsRecords at your DNS provider, then call websiteDomains.verifyCustomDomain.
Unique domain id.
Fully-qualified lowercase hostname, e.g. blog.example.com.
pending_dns: waiting for the required DNS records; pending_verification: DNS found, waiting for the edge host to become ready; active: serving traffic; failed: verification failed (see failureMessage); removing: being deregistered from the edge; suspended: disabled by Cactal trust & safety. Platform subdomains are always active.
pending_dns, pending_verification, active, failed, removing, suspended Every website automatically gets one platform_subdomain; custom domains are added through this API.
platform_subdomain, custom Whether this is the canonical custom domain that published traffic redirects to. Always false for platform subdomains.
DNS records the domain owner must create for verification to succeed. Empty for platform subdomains.
What the most recent verification check found wrong, including whether ownership is missing, the hostname is unreachable, or traffic reaches a service other than Cactal. null when nothing is wrong.
When DNS and edge status were last checked. null before the first check.
When the domain record was created.