Where domains point
Serve domains through our edge or your own servers.
Every connection's records point somewhere. An application sets where its
domains point, and each connection's routing field says where that domain
points. The default record set, verification and the live DNS diagnosis follow
the domain's own routing. So the records your customers see are always the ones
that will work, even after you change the application's.
| Through the edge (default) | Your own infrastructure | |
|---|---|---|
| Subdomain record | CNAME to edge.customdomain.ai | CNAME to your hostname |
| Root record | ALIAS/ANAME/flattened CNAME to the edge, or A records to the edge's addresses | ALIAS-style record to your hostname, or A records to the addresses you list |
| TLS certificates | Issued and renewed by the edge on first request | Yours to issue (your load balancer, TLS proxy or CDN) |
Root to www redirect | Served by the edge | Yours to serve |
| Plans | Power (Growth and up) | Every plan |
In the console both live under Routing, the page titled Where domains point. Going through the edge is what the console calls Edge serving.
Through the edge
The edge terminates TLS and proxies each request to your origin, passing the
customer's hostname in X-Forwarded-Host so one origin can serve every
customer. Set that origin once for the whole application:
curl -X PUT https://api.customdomain.ai/v1/applications/<APP_ID>/power:default \
-H "Authorization: Bearer cd_live_..." \
-H "Content-Type: application/json" \
-d '{ "default_origin": "https://app.example.com" }'A connection can override it with its own origin. Use POST /v1/connections/{id}/power with { "application_url": "https://..." }, or
application_url when it is created. Serving through the edge is part of the
Growth plan and up. On a plan without it, the default origin, a connection's
origin and an application_url at create are all refused with 402 plan_upgrade_required. The edge uses the connection's origin first, then the
application default. With neither, it answers 421, so set the default before
your first customer connects. Send "default_origin": "" to clear the default.
Reverse-proxy hosting is part of edge serving, which the Growth, Premium and
Enterprise plans include. On Starter and Startup, the power:default and
/power calls are refused with 402 and the code plan_upgrade_required.
Pointing at your own infrastructure below is not
plan gated.
Routing in the console checks the default origin for you. It sends one
request to / from our server when you save it, and again when you choose
Check again. It says whether the origin answered, could not be reached,
showed a certificate we do not accept, took too long, or points at a private
address. A 404 or 401 for a bare request to / counts as up, since an
origin that serves by X-Forwarded-Host often answers that way. A 5xx is
reported as an error. The check is advice and never stops you saving. It only
reaches ports 80 and 443 on public addresses. It comes from our network, so an
origin that accepts only some source addresses can read as unreachable. See
What the origin check
sends.
Your own infrastructure
Name your own destination with a connection target. Customer subdomains get a
CNAME to cname_target; roots get an ALIAS-style record to it where the
DNS provider has one, and otherwise A records to each address in apex_ipv4
(up to four public IPv4 addresses):
curl -X PUT https://api.customdomain.ai/v1/applications/<APP_ID>/connect-target \
-H "Authorization: Bearer cd_live_..." \
-H "Content-Type: application/json" \
-d '{ "cname_target": "customers.example.com", "apex_ipv4": ["203.0.113.10"] }'cname_targetmust be a hostname, not an IP address and not the edge itself. A hostname that is aCNAMEto the edge, or resolves to one of its addresses, is refused too. So is an edge address inapex_ipv4. Domains pointed there would verify but never be served. Send""to point the application back at the edge.- The response carries
warningswhen the hostname does not resolve yet, or when you sent noapex_ipv4. Both are saved anyway; create the hostname before your first customer connects. - Without
apex_ipv4, a root domain at a provider with noALIAS-style record cannot be pointed at you. The pre-flight says so up front (apex_strategy: "unsupported"). The widget steers that customer towwwor a subdomain.POST /v1/connectionsrefuses the root with422 apex_not_supported, so it never creates a connection that could not go live. - A root on an
ALIAS-style record answers with addresses, not with your hostname. It is found (at setup, on a recheck and by the drift monitor) when those addresses are your hostname's, or include one ofapex_ipv4. - Traffic never passes through the edge in this mode, so certificates and the
root to
wwwredirect are yours to serve.www_redirect: truestill adds thewwwrecord.validate_caaadds no Let's Encrypt CAA records, and the pre-flight raises no CAA warning, because the certificate authority is yours to choose. - One-click Domain Connect setup is not offered: its templates point domains
at the edge.
POST /v1/domains:checkreportsrails.domain_connectas unavailable with the reasoncustom_routing, andPOST /v1/connections/{id}/domainconnect:startanswers422 custom_routing. Provider sign-in, a provider API key and manual records all work.
Changing where domains point
A change reaches two kinds of domain differently:
- Domains still waiting for DNS (pending or failed, with no records supplied or written for them) take the new routing. Nothing serves them yet, so their customers are shown the new records.
- Connected domains keep pointing where they do. The edge keeps serving the ones on the edge, and nothing changes for those customers until you move their domain.
The response says how many of each it reached:
"existing_domains": { "moved": 3, "kept": 12 }moved counts the waiting domains that took the new routing. kept counts
every other domain the change reaches, all left where they are. That covers
connected domains, domains whose records were supplied or written, and waiting
domains already on the new routing. So saving the same target twice moves
nothing the second time and counts every domain as kept. The audit log entry
records the same counts as domains_moved and domains_kept. The entry is
app.routing_set, or app.routing_cleared for a return to the edge.
In the console, Routing asks before it saves a target on your own
infrastructure. The confirmation reads "Point customer domains at
customers.example.com?". It lists the records customers will add and says what
happens to the application's domains, for example "3 domains waiting for DNS
will follow. 12 domains stay where they are." Nothing is saved until you
confirm. The console counts those from the application's domain list before the
save. The response's existing_domains is the exact count.
Each connection's routing says where it points:
"routing": { "mode": "custom", "cname_target": "customers.example.com", "apex_ipv4": ["203.0.113.10"], "set_at": "2026-10-14T18:00:00Z" }Move one connected domain to the application's current routing with
POST /v1/connections/{id}:retarget, or Move this domain on its DNS page in
the console. It needs a server-side API key; a widget token is refused. The
response lists the records the domain needs from now on. It does not change
the customer's DNS:
- The domain goes back to
pendingand is checked straight away. If its DNS already names the new place,statusisliveagain. Otherwise it waits for the customer's new records, and no drift is reported meanwhile. customer_action_required: true: the customer has to replace the old records with the new ones before the domain works on the new routing.stops_edge_serving: true: the domain was live on the edge and the edge stops serving it now, so have the new records ready first.moved: false: the domain already pointed there.
Moved a domain off the edge by mistake? Send {"to": "edge"} to move it back to
the edge whatever the application's routing (Undo: back to the edge in the
console). If its DNS still names the edge it is live again at once.
Some domains had their records written through a connected provider account that
still holds a usable key. Such a domain can be moved by rewriting the records,
when that is switched on for your account. The response carries rewriting: true and customer_action_required: false. The new records are written in the
background, and the domain is verified on them. If the write fails twice, the
customer is told, as for any other Move.
A domain whose records your backend supplied (PUT /v1/connections/{id}/records) is refused with 409. Send it new records
instead. Some domains had their records written during setup by a rail that
cannot rewrite them. Those are refused too: disconnect and connect them again to
move them.
Every Move that needs new records from the customer sends the
connection.records_outdated webhook. It also emails your owners and admins,
and can email the end user too. See End user
notices.
GET /v1/applications/{id}/connect-target returns the current mode
(edge or custom), the target, and what the edge mode would point at, so a
settings screen can show both.
See also Root domains and Verify and go live.