Verify a custom domain

curl --request POST \
  --url https://api.cactal.ai/v1/websites/{websiteId}/domains/{domainId}/verify \
  --header 'Authorization: Bearer <token>'

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.cactal.ai/v1/websites/{websiteId}/domains/{domainId}/verify', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.cactal.ai/v1/websites/{websiteId}/domains/{domainId}/verify"

headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, headers=headers)

print(response.text)

{
  "id": "<string>",
  "hostname": "<string>",
  "status": "pending_dns",
  "kind": "platform_subdomain",
  "isPrimary": true,
  "dnsRecords": [
    {
      "type": "TXT",
      "name": "<string>",
      "value": "<string>",
      "purpose": "ownership"
    }
  ],
  "failureMessage": "<string>",
  "lastCheckedAt": "2023-11-07T05:31:56Z",
  "createdAt": "2023-11-07T05:31:56Z"
}

{
  "kind": "validation",
  "message": "<string>",
  "suggestion": "<string>",
  "validValues": [
    "<string>"
  ]
}

{
  "kind": "validation",
  "message": "<string>",
  "suggestion": "<string>",
  "validValues": [
    "<string>"
  ]
}

{
  "kind": "validation",
  "message": "<string>",
  "suggestion": "<string>",
  "validValues": [
    "<string>"
  ]
}

{
  "kind": "validation",
  "message": "<string>",
  "suggestion": "<string>",
  "validValues": [
    "<string>"
  ]
}

{
  "kind": "validation",
  "message": "<string>",
  "suggestion": "<string>",
  "validValues": [
    "<string>"
  ]
}

{
  "kind": "validation",
  "message": "<string>",
  "suggestion": "<string>",
  "validValues": [
    "<string>"
  ]
}

Domains

Verify a custom domain

Re-checks the ownership TXT record, edge readiness, and whether an HTTPS request to the hostname reaches this Cactal domain, then returns the updated status. A customer CDN or reverse proxy in front is supported when it forwards the verification request to Cactal. failureMessage distinguishes a missing ownership record, an unreachable hostname, and a hostname served somewhere else. DNS propagation can take minutes to hours, so this endpoint is safe to poll; Cactal also re-checks pending domains automatically (every minute for the first 2 hours, every 5 minutes for the first day, then every 15 minutes). The first custom domain to become active is promoted to primary automatically.

POST

websites

{websiteId}

domains

{domainId}

verify

Verify a custom domain

curl --request POST \
  --url https://api.cactal.ai/v1/websites/{websiteId}/domains/{domainId}/verify \
  --header 'Authorization: Bearer <token>'

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.cactal.ai/v1/websites/{websiteId}/domains/{domainId}/verify', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.cactal.ai/v1/websites/{websiteId}/domains/{domainId}/verify"

headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, headers=headers)

print(response.text)

{
  "id": "<string>",
  "hostname": "<string>",
  "status": "pending_dns",
  "kind": "platform_subdomain",
  "isPrimary": true,
  "dnsRecords": [
    {
      "type": "TXT",
      "name": "<string>",
      "value": "<string>",
      "purpose": "ownership"
    }
  ],
  "failureMessage": "<string>",
  "lastCheckedAt": "2023-11-07T05:31:56Z",
  "createdAt": "2023-11-07T05:31:56Z"
}

{
  "kind": "validation",
  "message": "<string>",
  "suggestion": "<string>",
  "validValues": [
    "<string>"
  ]
}

{
  "kind": "validation",
  "message": "<string>",
  "suggestion": "<string>",
  "validValues": [
    "<string>"
  ]
}

{
  "kind": "validation",
  "message": "<string>",
  "suggestion": "<string>",
  "validValues": [
    "<string>"
  ]
}

{
  "kind": "validation",
  "message": "<string>",
  "suggestion": "<string>",
  "validValues": [
    "<string>"
  ]
}

{
  "kind": "validation",
  "message": "<string>",
  "suggestion": "<string>",
  "validValues": [
    "<string>"
  ]
}

{
  "kind": "validation",
  "message": "<string>",
  "suggestion": "<string>",
  "validValues": [
    "<string>"
  ]
}

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

domainId

string

required

Minimum string length: 1

Response

The domain with its freshly checked status. When not yet active, failureMessage explains whether ownership, reachability, routing, or edge readiness needs attention.

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.

Show child attributes

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.

Getting started

Documentation

Feedback

Websites

Website editors

API keys

Source code

Publishing

CMS collections

CMS fields

CMS items

Domains

Assets

Project context

Analytics

Organizations

Audit log

Billing

Verify a custom domain

Authorizations

Path Parameters

Response