Custom Domains

Attach a custom domain to a site

Validates the hostname, registers a Cloudflare Custom Hostname under our SaaS zone, and returns the row in pending_dns. The customer completes setup by adding a single CNAME record.

post/sites/{siteId}/custom-domains

Request

  • Base URL: https://api.nippy.host
  • URL: https://api.nippy.host/sites/{siteId}/custom-domains
  • Auth: bearer (a scheme the document does not define)

Path parameters

siteIdstring required

Site UUID

Request body

hostnamestring required

Domain to attach. Apex (example.com) and subdomain (www.example.com) forms are both accepted. The www. companion is auto-attached for apex inputs.

Example request

{
  "hostname": "example.com"
}

Response

idstring required
hostnamestring required
status'pending_dns' | 'pending_ssl' | 'active' | 'failed' | 'disabled' required

pending_dns: waiting on customer to add CNAME. pending_ssl: CNAME good, certificate provisioning. active: serving public traffic. failed: terminal — see failureReason. disabled: user-disabled, retained for re-enable.

failureReasonstring nullable

Stable machine-readable failure code when status=failed; null otherwise. Examples: hostname_in_use, cert_validation_failed, timeout.

publicUrlstring required
expectedCnamestring required

CNAME instructions to surface to the customer. Same value for every domain on the platform — set once at the zone level.

dnsRecordNamestring required

The "Host"/"Name" value to enter in the CNAME record at the DNS provider — the label(s) left of the registrable domain. "@" marks the root for an apex. Many providers want this rather than the full hostname, so the UI shows it alongside hostname as a fallback.

verifiedAtstring date-time nullable
createdAtstring date-time required
updatedAtstring date-time required
parentDomainIdstring nullable

When this row was auto-created (the www. companion of an apex), this is the apex row id; users can manage both via the apex.

Example response

{
  "hostname": "example.com",
  "publicUrl": "https://example.com",
  "dnsRecordName": "www",
  "dnsPreflight": {
    "expectedTarget": "cname.nippy.site"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.