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 that does work.

Prefer the A records at a root domain anyway. Every one of those mechanisms resolves our hostname once and republishes whatever single address it got back, so the apex ends up pinned to one of our regions with no failover. The anycast A records keep both regions, because the routing happens in the network rather than in DNS.

For an apex hostname, dnsRecordOptions marks the a set as recommended and returns it first:

"dnsRecordOptions": [
  {
    "method": "a",
    "recommended": true,
    "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" }
    ]
  },
  {
    "method": "cname",
    "recommended": false,
    "records": [
      { "type": "CNAME", "name": "acme.com", "value": "edge.domainee.dev", "purpose": "Traffic Routing" }
    ]
  }
]

Tell the customer to add both A records. One alone still works, but silently leaves them without redundancy.

On a subdomain the recommendation flips the other way: cname comes back first, because a real CNAME there does give per-visitor regional routing and follows our infrastructure automatically. Take dnsRecordOptions[0] and you get the right one either way.

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

Our DNS monitor re-checks each domain every 5 minutes. Once it sees the record, it flips status from pending to verified on its own. A brand new domain is picked up on the first sweep after you create it, usually within a minute; after that it settles into the 5 minute cadence. You can also force an immediate check rather than waiting:

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