Domains

Add a custom domain and start connecting it

Adds one hostname, or an apex and its www together. A nested subdomain of the platform's own site domain is connected at once (200 if it was already on this site, otherwise 201). An external domain needs a paid plan and starts a connect session: the 201 body carries connect, which says what to do next (open a link, or enter DNS records). Re-sending a host already on the site is safe and returns it again without using another slot. Each site and each account has a cap on external hostnames (custom_domain_limit). Then poll refreshCustomDomain until status is connected. Needs the site owner. Editors, viewers, guest tokens (guest_requires_account) and keys scoped to other sites are refused.

post/api/v1/sites/{slug}/custom-domains

Request

  • Base URL: https://api.dotsy.ai
  • URL: https://api.dotsy.ai/api/v1/sites/{slug}/custom-domains
  • Auth: HTTP bearer

Path parameters

slugstring required
Example:acme-studio

Site slug or site id (UUID). An old slug answers 301/308 and a site id 307 to the canonical slug path.

Request body

hostsstring[]

One or two hostnames. Two is only valid as an apex and its www together (they share one connect session). Takes precedence over host.

hoststring

A single hostname — the same as hosts: [host].

Example request

{
  "hosts": [
    "example.com",
    "www.example.com"
  ],
  "host": "www.example.com"
}

Response

That internal host is already on this site.

Example response

{
  "domain": {
    "host": "www.example.com",
    "slug": "acme-studio",
    "kind": "external",
    "status": "pending_dns",
    "isPrimary": false,
    "lastError": null,
    "createdAt": 1760000000000,
    "verifiedAt": 1760000000000,
    "connectSessionId": "cs_3f9a1c2e",
    "lastCheckedAt": 1760000000000,
    "dnsRecords": [
      {
        "type": "CNAME",
        "name": "www",
        "value": "customers.dotsy.site",
        "purpose": "routing",
        "recordStatus": "missing"
      },
      {
        "type": "TXT",
        "name": "_acme-challenge.www",
        "value": "k3Zr1q9Wn0xLpV7sT2uYb8cD4eFgH6jA",
        "purpose": "dcv",
        "recordStatus": "waiting"
      }
    ]
  }
}

Changes

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