Create a domain

POST /v1/domains

Registers a customer hostname for proxying or redirecting through our edge. Counts toward your domain quota immediately.

Request

curl -X POST https://api.domainee.dev/v1/domains \
  -H "Authorization: Bearer $DOMAINEE_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "hostname": "shop.acme.com",
    "originUrl": "https://acme.fly.dev",
    "mode": "proxy",
    "keepHost": false,
    "redirectWww": true
  }'

Body parameters

Field	Required	Default	Notes
hostname	✅	—	RFC 1123 hostname. Lowercased + dot-trimmed automatically.
originUrl	✅	—	Must be https:// or http://. We block private/loopback IPs (see SSRF protection).
mode		"proxy"	"proxy" (reverse-proxy) or "redirect" (301/302).
keepHost		false	proxy mode only — forward original Host header.
redirectWww		false	Also serve and 301 the www variant.
redirectStatus		301	301 (permanent) or 302 (temporary).
metadata		{}	Opaque object. We store and return it untouched.

Response — 201 Created

{
  "domain": {
    "id": "8f09b47c-b42f-4d14-8395-2989db76e6f8",
    "hostname": "shop.acme.com",
    "originUrl": "https://acme.fly.dev",
    "status": "pending",
    "mode": "proxy",
    "dnsRecords": [
      {
        "type": "CNAME",
        "name": "shop.acme.com",
        "value": "edge.domainee.dev",
        "purpose": "Traffic Routing"
      }
    ]
  },
  "warnings": []
}

warnings is always present, possibly empty. Non-fatal preflight findings (e.g. the hostname doesn't resolve yet, the origin is unreachable) appear here without blocking creation.

Errors

Status	Code	When
400	bad_request	Invalid hostname, invalid URL, reserved suffix
400	preflight_failed	CAA blocks LE, origin SSRF
402	billing_required	Free tier exhausted (50 domains or 100 GB) and no card on file
409	conflict	Hostname already in use

Idempotency

Send Idempotency-Key: <key> to make retries safe — see Idempotency.