Attach DNS (NS delegation)

Put a portfolio domain under Fat Heron DNS control while it stays at the customer registrar.

Required scopes: domains:write · Base https://api.fatheron.dev

Steps

1. 1. Start delegation

   POST /v1/portfolio/domains/{domain_id}/dns/start-delegation
   X-API-Key: fh_live_…
   Content-Type: application/json
   
   {
     "force_nameserver_push": false
   }

   Returns name_servers[]. If nameserver_push.ok, registrar was updated. Otherwise set NS manually.

2. 2. Verify nameservers

   POST /v1/portfolio/domains/{domain_id}/dns/verify-ns
   X-API-Key: fh_live_…

   Poll until dns_ready / dns_delegation_status is ns_active. Auto catch-up also runs every 5m.

3. 3. Read DNS status

   GET /v1/portfolio/domains/{domain_id}/dns
   X-API-Key: fh_live_…

Failure remediation

• domain_not_found

  Use a curated domain_id owned by this account.

• nameserver_push_blocked

  Fix DNS backup/capture first, or retry with force_nameserver_push: true after review.

• nameservers_not_issued

  Re-run start-delegation so Cloudflare NS are stored on the domain.

• dns_provider_cannot_create_zone

  Ops: DNS provider credentials/config on the control plane.

All agent recipes