What it does
Connect a custom domain (such as www.example.com or example.com) to a site. It stays pending until verify_site_domain passes. domain.dns.records holds the DNS records the owner adds at their DNS host: a TXT record proving they own the domain, and a CNAME (or A and AAAA for an apex). role: primary serves the site and is the default for its first domain; redirect sends visitors to the primary address. Apex and www are two separate domains. Needs can_custom_domains.
Plans
Needs a paid plan: Basic, Pro or Ultra. On other plans your agent gets an error that says so. See Limits for what each plan includes.
Parameters
| Name | Type | About |
|---|---|---|
site_idrequired | string | The id of the site. list_sites gives the ids of your sites. |
hostnamerequired | string | The domain to connect, such as www.example.com. The apex and www are separate domains. |
role | one of: primary, redirect | primary serves the site; redirect sends visitors to the primary address. The first domain is primary by default. |
idempotency_key | string | Any unique string (1-200 printable ASCII). A retry with the same key and arguments returns the first call's result instead of running again. Same as the Idempotency-Key header. |
Example
Call add_site_domain with these arguments:
{
"site_id": "01a1…",
"hostname": "www.example.com"
}
Ids like 01a1… stand for your own. list_sites and list_tables give you the real ones.
Related guides
- Use your own domainServe a site on www.example.com instead of pagehive.space.
- LimitsHow much a Hive holds on each plan.