Skip to main content
POST
Add a custom domain

Authorizations

Authorization
string
header
required

Cactal API key. Create one in the dashboard or via POST /apiKeys. The plaintext key is shown once at creation.

Path Parameters

websiteId
string
required
Minimum string length: 1

Body

application/json
hostname
string
required
Minimum string length: 1

Response

The created domain in pending_dns status. Next: create the dnsRecords at your DNS provider, then call websiteDomains.verifyCustomDomain.

id
string
required

Unique domain id.

hostname
string
required

Fully-qualified lowercase hostname, e.g. blog.example.com.

status
enum<string>
required

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.

Available options:
pending_dns,
pending_verification,
active,
failed,
removing,
suspended
kind
enum<string>
required

Every website automatically gets one platform_subdomain; custom domains are added through this API.

Available options:
platform_subdomain,
custom
isPrimary
boolean
required

Whether this is the canonical custom domain that published traffic redirects to. Always false for platform subdomains.

dnsRecords
object[]
required

DNS records the domain owner must create for verification to succeed. Empty for platform subdomains.

failureMessage
string | null
required

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.

lastCheckedAt
string<date-time> | null
required

When DNS and edge status were last checked. null before the first check.

createdAt
string<date-time>
required

When the domain record was created.