POST /v1/sites/:id/domains

Attach a domain you already own to a deployed site. Warpweb provisions an SSL cert, updates routing, and serves the site at the new domain. The free subdomain (<slug>.warpweb.app) keeps working as a fallback.

Attaching a custom domain promotes the site to the paid hosting tier: $10/site/month, always-on, no weekly refresh required. Stripe starts billing on successful attach.

Cost: 5 credits one-time, plus $10/month per active paid site.

Request

curl -X POST https://api.warpweb.ai/v1/sites/8f3c2a1b/domains \
  -H "Authorization: Bearer wwk_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "brooksideplumbing.com"
  }'

Body

DNS setup

Calling this endpoint reserves the domain for your site and returns the CNAME target you need to point DNS at. The workflow:

1. Call this endpoint with your domain. The response includes cname_target and ready-to-copy instructions.
2. Copy the cname_target (and the instructions block) into your registrar’s DNS UI.
3. Update your DNS records as instructed.
4. Warpweb verifies automatically. No second API call needed — our verification poller picks up DNS propagation and provisions SSL in the background. Status flips from dns_pending to active once both DNS and SSL land; track it via GET /v1/sites/:id.

If your registrar doesn’t allow CNAME on the apex (root) domain, set an A record per the returned instructions plus a CNAME for www. We’ll redirect apex traffic accordingly. (Registrars that support apex CNAME via flattening: Cloudflare, Namecheap, DNSimple. Registrars that don’t: GoDaddy, Bluehost, most legacy hosting providers — use the A-record path on those.)

SSL provisioning typically completes within 2–10 minutes after DNS propagates — the actual time depends on TTL on the prior records and your registrar’s propagation behavior. If your domain hasn’t gone active within 30 minutes, contact support@warpweb.ai with the site_id.

Response

{
  "success": true,
  "domain": "brooksideplumbing.com",
  "cname_target": "brookside-plumbing-a1b2c3.pages.dev",
  "instructions": {
    "apex": { "type": "CNAME", "name": "@", "value": "brookside-plumbing-a1b2c3.pages.dev" },
    "www":  { "type": "CNAME", "name": "www", "value": "brookside-plumbing-a1b2c3.pages.dev" },
    "note": "Some registrars don't allow CNAME on the apex (root) domain. If yours doesn't, set an A record per the returned instructions plus a CNAME for www."
  },
  "status": "dns_pending"
}

If you don’t own a domain yet, use POST /v1/domains/register — Warpweb buys it, configures DNS, and attaches in one call.

Errors