CustomDomain Docs
DNS and serving

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 recordCNAME to edge.customdomain.aiCNAME to your hostname
Root recordALIAS/ANAME/flattened CNAME to the edge, or A records to the edge's addressesALIAS-style record to your hostname, or A records to the addresses you list
TLS certificatesIssued and renewed by the edge on first requestYours to issue (your load balancer, TLS proxy or CDN)
Root to www redirectServed by the edgeYours to serve
PlansPower (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_target must be a hostname, not an IP address and not the edge itself. A hostname that is a CNAME to the edge, or resolves to one of its addresses, is refused too. So is an edge address in apex_ipv4. Domains pointed there would verify but never be served. Send "" to point the application back at the edge.
  • The response carries warnings when the hostname does not resolve yet, or when you sent no apex_ipv4. Both are saved anyway; create the hostname before your first customer connects.
  • Without apex_ipv4, a root domain at a provider with no ALIAS-style record cannot be pointed at you. The pre-flight says so up front (apex_strategy: "unsupported"). The widget steers that customer to www or a subdomain. POST /v1/connections refuses the root with 422 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 of apex_ipv4.
  • Traffic never passes through the edge in this mode, so certificates and the root to www redirect are yours to serve. www_redirect: true still adds the www record. validate_caa adds 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:check reports rails.domain_connect as unavailable with the reason custom_routing, and POST /v1/connections/{id}/domainconnect:start answers 422 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 pending and is checked straight away. If its DNS already names the new place, status is live again. 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.

On this page