# Where domains point

> Serve domains through our edge or your own servers.

Source: https://docs.customdomain.ai/docs/connect-flow/routing

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:

```bash
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](#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](/docs/security/domain-checks#when-you-save-an-origin).

## 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):

```bash
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:

```json
"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:

```json
"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](/docs/connect-flow/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](/docs/dns/root-domains) and
[Verify and go live](/docs/connect-flow/verify-and-go-live).
