---
title: "Move a domain to its application's current routing, or back to the edge"
method: POST
path: "/connections/{id}:retarget"
tags: ["Connections"]
---

# Move a domain to its application's current routing, or back to the edge

`POST /connections/{id}:retarget`

## Request

- Base URL: `https://api.customdomain.ai/v1`
- URL: `https://api.customdomain.ai/v1/connections/{id}:retarget`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://api.customdomain.ai/oauth/agent/authorize`, token URL `https://api.customdomain.ai/oauth/agent/token`, scopes: `domains:connect`)

A connected domain keeps the routing it connected with when its application's routing changes (domains still waiting for DNS follow the change). This moves one: the domain's expected records become those of the application's current routing, or with `{"to": "edge"}` those of the CustomDomain™ edge whatever the application's routing (the way back for a domain moved off the edge by mistake). The body is optional.

The customer's DNS is not changed. A moved domain goes back to `pending` with a fresh verification clock, is checked at once (a domain whose DNS already names the new place is `live` again in the response's `status`), and otherwise waits for its records (returned in `records`); drift is not reported while it waits. Moving a live domain off the edge stops edge serving at once (`stops_edge_serving`).

A domain whose records were written through a connected provider account that holds a usable key is moved by rewriting them, when the `move_rewrite` flag is on: 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 (`propagating`); if the write fails twice the customer is told as for any other move.

A no-op (`moved: false`) when the domain already points there. Refused (409) when the domain's records are stored and no rewrite is possible: records your backend supplied (change them with `PUT /connections/{id}/records`) or records written into the customer's DNS during setup by a rail that cannot rewrite them (disconnect and reconnect to move it). A server-side API key or an agent token only: a widget token is refused (403). Recorded in the audit log as `connection.retargeted`.

## Path parameters

- `id` string, required

## Request body

- object
  - `to` 'application' | 'edge': Where to move the domain.

## Response `200`

The domain's routing after the move, and its records from now on.

- object
  - `connection_id` string, required
  - `moved` boolean, required
  - `routing` ConnectionRouting, required
    - `mode` 'edge' | 'custom', required: `edge`: records point at the CustomDomain™ edge. `custom`: at your own infrastructure.
    - `cname_target` string: For `custom`: the hostname subdomains and ALIAS-capable roots point at.
    - `apex_ipv4` string[]: For `custom`: the addresses roots get on DNS providers with no ALIAS-style record.
    - `set_at` string, date-time, required: When this routing was recorded for the domain.
  - `previous_routing` ConnectionRouting
    - `mode` 'edge' | 'custom', required: `edge`: records point at the CustomDomain™ edge. `custom`: at your own infrastructure.
    - `cname_target` string: For `custom`: the hostname subdomains and ALIAS-capable roots point at.
    - `apex_ipv4` string[]: For `custom`: the addresses roots get on DNS providers with no ALIAS-style record.
    - `set_at` string, date-time, required: When this routing was recorded for the domain.
  - `records` DnsRecord[], required
    - `type` string, required: DNS record type. `APEXCNAME` is the engine's provider-agnostic CNAME-at-the-apex type (a plain CNAME is illegal at a zone apex); it is realized to the host's native ALIAS / ANAME / flattened-CNAME on write, and shown to users as `ALIAS` in manual instructions.
    - `host` string, required: fully-qualified record name
    - `value` string, required
    - `ttl` integer
    - `priority` integer, nullable: MX only
    - `applied` boolean: true once written through a provider
    - `change` 'created' | 'added' | 'replaced' | 'merged' | 'existing': What writing this record did to its name, recorded when we wrote it through a provider API. `created`: nothing of this type was there. `added`: our value joined a shared TXT or CAA set and the values already there were kept. `replaced`: the values of this type at the name were replaced (`prior` holds them). `merged`: an SPF policy was merged with the one already there (`prior` holds the original). `existing`: our exact value was already there, so removing the domain leaves it. Omitted when not recorded (a manual or one-click setup, or a record written before this was recorded).
    - `prior` PriorValue[]: The values this record replaced, so removing the domain can put them back. Omitted when nothing was replaced or it is unknown.
      - `type` string, required
      - `value` string, required
      - `ttl` integer
      - `priority` integer
    - `prior_source` 'provider' | 'public_dns': Where `prior` was read: `provider` (through the provider's API right before the write) or `public_dns` (observed in public DNS before the change). Omitted when unknown.
  - `customer_action_required` boolean, required
  - `rewriting` boolean: CustomDomain™ is writing the new records itself, through the rail that wrote the old ones. Present only when true; `customer_action_required` is then false.
  - `stops_edge_serving` boolean, required
  - `status` 'pending' | 'propagating' | 'live' | 'failed'

## Other responses

- `400`: Error envelope: {code, title, details}.
- `401`: Error envelope: {code, title, details}.
- `403`: Error envelope: {code, title, details}.
- `404`: Error envelope: {code, title, details}.
- `409`: Error envelope: {code, title, details}.

---

[API](https://skmtc.dev/customdomain/apis/customdomain-control-plane-api.md) · [All operations](https://skmtc.dev/customdomain/apis/customdomain-control-plane-api/llms.txt) · [OpenAPI document](https://skmtc.dev/customdomain/apis/customdomain-control-plane-api/revisions/34d89cb7a7cd?raw)