---
title: "Remove a domain, optionally authorizing the record removal once with a key"
method: POST
path: "/connections/{id}:disconnect"
tags: ["Connections"]
---

# Remove a domain, optionally authorizing the record removal once with a key

`POST /connections/{id}:disconnect`

## Request

- Base URL: `https://api.customdomain.ai/v1`
- URL: `https://api.customdomain.ai/v1/connections/{id}:disconnect`
- Auth: one of:
  - HTTP bearer
  - 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:disconnect`)

The same removal as `DELETE /connections/{id}` with a body. Send `credential` (a DNS provider API key) to authorize removing the records once when we did not keep the access that added them; it is used for this removal and never stored. The zone must show at least one of our records with that key, or the outcome lists the manual steps (the key may belong to another account). Answers `200` with the outcome; an end user's widget token must be bound as for `DELETE /connections/{id}`.

A delegated agent token needs `domains:disconnect` and must send `confirm`, as for `DELETE /connections/{id}`.

## Path parameters

- `id` string, required

## Query parameters

- `confirm` string

## Request body

- object
  - `records` 'remove' | 'keep'
  - `provider` string: DNS provider id; defaults to the connection's provider.
  - `zone` string: The DNS zone; found from the key when omitted.
  - `credential` object
    - `token` string: The provider API key, used once.

## Response `200`

Removed; what happened to the records

- DisconnectResult
  - `connection_id` string, required
  - `domain` string, required
  - `disconnected` boolean, required
  - `records` RemovalOutcome, required
    - `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[]
  - `serving` 'stopped', required
  - `certificate` 'removed' | 'kept' | 'none', required
  - `monitoring` 'stopped', required

## 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`: `reauthorization_required`, `removal_in_progress` or `confirmation_mismatch`, as for `DELETE /connections/{id}`.

---

[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)