Quickstart

By the end of this guide you'll have one of your customers' domains routing through Domainee to your origin, with automatic HTTPS.

1. Sign up and get an API key

1. Create an account.
2. Open the Developers page in your dashboard.
3. Click New key, name it (e.g. production), copy the key — it's shown only once. Format: sk_live_….

export DOMAINEE_API_KEY=sk_live_...

2. Register a domain

Replace shop.acme.com with the customer hostname you want to route, and https://acme.fly.dev with your origin URL (the actual app the traffic should reach).

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"
  }'

You'll get back the domain object plus a list of DNS records the customer needs to publish:

{
  "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": []
}

See Create a domain for every parameter.

3. Tell your customer what to add at their DNS provider

Hand them the single CNAME from the response:

Type:   CNAME
Name:   shop.acme.com
Value:  edge.domainee.dev

That's it — no validation record, no second CNAME for SSL. (If they're on Cloudflare, set the proxy status to DNS only so TLS passes through.)

Apex / root domains

A CNAME can't live at the zone apex. Most providers paper over this with ALIAS, ANAME or CNAME flattening, and where they do, the CNAME above works unchanged at the root.

Where they don't, read dnsRecordOptions on the same response. It carries an a set alongside the cname one:

"dnsRecordOptions": [
  { "method": "cname", "recommended": true,  "records": [ /* the CNAME above */ ] },
  {
    "method": "a",
    "recommended": false,
    "records": [
      { "type": "A", "name": "acme.com", "value": "75.2.52.197",  "purpose": "Traffic Routing" },
      { "type": "A", "name": "acme.com", "value": "3.33.255.144", "purpose": "Traffic Routing" }
    ]
  }
]

These are anycast addresses that route to the nearest edge region, and they stay put across region changes. Tell the customer to add both. One alone still works, but silently leaves them without redundancy.

dnsRecords is unchanged and still carries only the CNAME, so existing integrations that render it directly keep behaving exactly as before.

4. Wait for verification

Within 60 seconds of the customer publishing the CNAME, our DNS monitor detects it and flips status from pending to verified. You can also force an immediate check:

DOMAIN_ID=8f09b47c-b42f-4d14-8395-2989db76e6f8
curl -X POST https://api.domainee.dev/v1/domains/$DOMAIN_ID/check \
  -H "Authorization: Bearer $DOMAINEE_API_KEY"

5. First HTTPS request

curl -i https://shop.acme.com/some/path

The first request takes 10–30 seconds: our TLS edge sees a new SNI, asks our control plane "is this a verified domain?", then provisions a Let's Encrypt cert. After that, every request uses the cached cert (no LE round-trip).

6. Listen for status changes

Subscribe to webhooks so you know when a domain is verified, when DNS breaks, when SSL expires, etc.:

curl -X POST https://api.domainee.dev/v1/webhook-endpoints \
  -H "Authorization: Bearer $DOMAINEE_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/domainee",
    "events": []
  }'

(Empty events array subscribes to all domain events.) See Webhooks for signature verification and the full event list.

What's next

• Domains API reference — every field, every endpoint
• Webhook events — what fires and when
• Errors — monitor_status values, retries, idempotency