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

> disconnect connection with choice: CustomDomain™ API reference in the connections group. Covers request parameters, the request body, responses and error codes.

Source: https://docs.customdomain.ai/docs/api-reference/connections/disconnectConnectionWithChoice

## `POST https://api.customdomain.ai/v1/connections/{id}: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}`. A share link's token is refused with `403` `forbidden`, as there.

### Authentication

`widgetJWT`, `apiKey`, `agentToken`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |
| `confirm` | query | string | no | The domain being removed, as written on the connection (case, scheme, path and a trailing dot do not matter). Required of a delegated agent token: without it the answer is `400 confirmation_required`. Any credential that sends it, an API key or an application token included, gets `409 confirmation_mismatch` when it names another domain (`400 confirmation_required` when it is empty). Nothing is removed either way. A credential other than an agent token may leave it out. |

### Request body (JSON)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `records` | `remove`, `keep` | no |  |
| `provider` | string | no | DNS provider id; defaults to the connection's provider. |
| `zone` | string | no | The DNS zone; found from the key when omitted. |
| `credential` | object | no |  |

### Responses

| Status | Description |
| --- | --- |
| `200` | Removed; what happened to the records |
| `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}`. |

### `200` response body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `connection_id` | string | yes |  |
| `domain` | string | yes |  |
| `disconnected` | boolean | yes |  |
| `records` | object | yes |  |
| `serving` | `stopped` | yes |  |
| `certificate` | `removed`, `kept`, `none` | yes |  |
| `monitoring` | `stopped` | yes |  |

The full specification is served at `GET https://api.customdomain.ai/v1/openapi.json`.
