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 DNS is replaced with two CNAMEs → edge.domainee.dev (apex @ and www) so the domain starts proxying to your origin.

Warning: connect replaces the whole DNS record set

Step 2 is a full replacement, not a merge. Any records already on the domain (MX, TXT/SPF/DKIM/DMARC, subdomain A records) are removed. The same applies to autoConnect and to calling this endpoint again to point the domain at a different origin.

If the domain also needs email or other records, do them after connecting:

1. Connect (this endpoint, or autoConnect on the purchase).
2. GET /:id/dns to read the two CNAMEs we wrote.
3. Append your MX / TXT records to that array and send it back with PUT /:id/dns.

Connect never runs on its own after that, so the records you add survive. Only a new connect call (or a PUT /:id/dns that omits them) removes them.

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 DNS again. See the warning 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.