---
title: "What removing a domain would do with its DNS records"
method: GET
path: "/connections/{id}/removal"
tags: ["Connections"]
---

# What removing a domain would do with its DNS records

`GET /connections/{id}/removal`

## Request

- Base URL: `https://api.customdomain.ai/v1`
- URL: `https://api.customdomain.ai/v1/connections/{id}/removal`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Read-only. Lists the records we added, what each one did to its name when we wrote it (created, added to a shared set, replaced, merged) and what it held before when we know, what a removal would do with each, whether that can happen automatically, needs one more sign-in or key, or only by hand, and the exact manual steps. Show it before asking the person to confirm. While a removal runs, `removal_started_at` is set. Once the domain is removed, it answers `removed: true` with `result`, what the removal did, to the callers that could have removed it: read this, not the connection's `404`, to learn the outcome. An end user's widget token must be bound as for `DELETE /connections/{id}`.

## Path parameters

- `id` string, required

## Response `200`

The removal plan, or the outcome of a finished removal

- RemovalPlan
  - `connection_id` string, required
  - `domain` string, required
  - `provider` string
  - `provider_name` string
  - `connected_via` string, required: The rail that wrote the records (see `Connection.write_rail`), `manual` when none did, or `unknown_api` for an older connection written through a provider API.
  - `access` 'kept' | 'one_time' | 'none', required: What access we hold now.
  - `access_detail` string
  - `record_removal` 'automatic' | 'partial' | 'reauthorize' | 'manual' | 'in_use' | 'not_needed', required: What choosing `remove` can do: `automatic` with the access we kept; `partial` (some automatically, the rest by hand: a Domain Connect revert cannot restore a replaced value, and the Route 53 access role cannot delete); `reauthorize` (one more sign-in or key, see `reauthorize`); `manual` (only by hand, see `manual_steps`); `in_use` (another connection still serves the domain, so the records stay); `not_needed` (nothing was added).
  - `default_choice` 'remove' | 'keep', required: The choice to offer first: `remove` when it can run without the person (automatic or partial), `keep` otherwise. A `DELETE` without a records choice keeps its original behaviour instead (see `DELETE /connections/{id}`).
  - `reauthorize` object
    - `methods` string[]
    - `provider` string
    - `flow` string
    - `regions` string[]
  - `records_in_use_elsewhere` boolean, required
  - `records` RemovalRecord[], required
    - `type` string, required: The type as a DNS panel shows it (ALIAS, A, CNAME, TXT, MX, CAA).
    - `host` string, required: fully-qualified record name
    - `name` string, required: the name a DNS panel wants ("@", "www", "_dmarc")
    - `value` string, required
    - `ttl` integer
    - `priority` integer
    - `change` 'created' | 'added' | 'replaced' | 'merged' | 'existing' | 'unknown', required: What writing the record did to its name (see `DnsRecord.change`).
    - `action` 'delete' | 'remove_value' | 'restore' | 'keep', required: What a removal does with it: `delete` our value, take our value out of a shared TXT or CAA set (`remove_value`), put back what it replaced (`restore`), or `keep` it (another connected domain uses it, it was already there before we wrote it, or it is an SPF policy whose original we do not know).
    - `prior` PriorValue[]
      - `type` string, required
      - `value` string, required
      - `ttl` integer
      - `priority` integer
    - `prior_source` 'provider' | 'public_dns'
    - `note` string
  - `manual_steps` string[], required: The exact steps to remove the records by hand, in order.
  - `notes` string[]
  - `teardown` string[], required: What always happens, whatever the choice.
  - `removal_started_at` string, date-time: Set while a removal of the domain is running.
  - `removed` boolean: True once the domain is removed: the connection is gone and `result` is what the removal did with its records.
  - `removed_at` string, date-time
  - `result` RemovalOutcome
    - `choice` 'remove' | 'keep', required
    - `outcome` 'removed' | 'partly_removed' | 'kept' | 'manual' | 'in_use' | 'not_needed' | 'failed', required
    - `via` string
    - `removed` RemovalResult[]
      - `type` string, required
      - `name` string, required
      - `value` string, required
      - `note` string
    - `restored` RemovalResult[]
      - `type` string, required
      - `name` string, required
      - `value` string, required
      - `note` string
    - `left_in_place` RemovalResult[]
      - `type` string, required
      - `name` string, required
      - `value` string, required
      - `note` string
    - `failed` RemovalResult[]
      - `type` string, required
      - `name` string, required
      - `value` string, required
      - `note` string
    - `manual_steps` string[]

## Other responses

- `401`: Error envelope: {code, title, details}.
- `403`: Error envelope: {code, title, details}.
- `404`: 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)