Connect a purchased domain to your app

POST /v1/domain-purchases/:id/connect

After you've bought a domain (without autoConnect), call this to make it actually serve traffic. Two things happen in one shot:

1. The hostname is registered on Domainee's edge (POST /v1/domains is run server-side). TLS is minted on first request.
2. The registrar's routing records for the apex (@) and www are pointed at Domainee's edge, so the domain starts proxying to your origin.

What connect touches, and what it leaves alone

Step 2 is a merge, not a replacement. Connect only rewrites the records that would conflict with routing traffic to us:

At @ and www	What happens
A, AAAA, ALIAS, CNAME, URL, URL301, FRAME	Replaced with our routing records.
MX, TXT (SPF/DKIM/DMARC), CAA, NS, SRV	Left exactly as they are.

Every record at any other name (subdomain A records, _dmarc, selector._domainkey, and so on) is left untouched. The same applies to autoConnect and to calling this endpoint again to repoint the domain, so connecting a domain never takes the customer's email down.

Order no longer matters: you can set MX and TXT records with PUT /:id/dns before or after connecting, and they survive either way.

At an apex we point the root at anycast A records rather than a CNAME. A CNAME at a zone apex is exclusive, so using one there would mean deleting the MX and TXT records sitting alongside it. A records coexist with them, and they keep both edge regions in play (see dnsRecordOptions on GET /v1/domains/:id). Where the deployment has no anycast addresses configured we fall back to a CNAME at the apex.

Request

curl -X POST https://api.domainee.dev/v1/domain-purchases/f8a0c1b9-…/connect \
  -H "Authorization: Bearer $DOMAINEE_API_KEY" \
  -d '{
    "originUrl": "https://janesbakery.acmesites.app",
    "keepHost": false
  }'

Body parameters

Field	Required	Default	Notes
originUrl	✅	—	Where the edge proxies requests to. Must be https://.
keepHost		false	true to forward the customer's original Host header to your origin.

Response — 200 OK

Returns the purchase row with connectedDomainId now populated:

{
  "purchase": {
    "id": "f8a0c1b9-…",
    "hostname": "janesbakery.com",
    "status": "completed",
    "connectedDomainId": "8f09b47c-b42f-4d14-…",
    ...
  }
}

Use connectedDomainId to look up the connected domain via GET /v1/domains/:id for status/cert/monitor details.

Errors

Code	Status	When
not_found	404	Purchase doesn't exist (or belongs to another workspace).
wrong_status	409	Purchase status isn't completed. Only connect a fully-registered domain.
connect_failed	502	Edge provisioning failed (origin unreachable) or DNS update failed. Nothing was charged.

Reconnecting an already-connected domain to a new origin rewrites the routing records again, on the same merge rules as above.

When to use this vs. autoConnect

Scenario	Use
You buy the domain and immediately connect it to your product	autoConnect on POST /v1/domain-purchases — one call.
You bought the domain a while ago, now want to connect (or reconnect to a different origin)	This endpoint.
You want to use the domain for something other than your app (email-only, parking, etc.)	Skip both. Manage DNS directly via PUT /:id/dns.