## Detach a domain

`DELETE /v1/infra/servers/:id/domain`

Detaches the domain from the server: the application stops responding on this name, and the name itself becomes available for a new attachment. An attachment cannot be restored through the API — attach the domain again.

Who can make the call — [Access](/docs/infra/domain#access).

## Parameters

| Parameter | In | Type | Required | Description |
|----------|---|-----|:-----:|----------|
| `id` | path | string (UUID) | yes | Server ID. Source — the `id` field from the [server list](/docs/infra/servers/list) |

## Examples

### curl — personal key

```bash
curl -X DELETE "https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/domain" \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth application

```bash
curl -X DELETE "https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/domain" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

### JavaScript — personal key

```javascript
const res = await fetch(
  `https://vibecode.bitrix24.com/v1/infra/servers/${serverId}/domain`,
  { method: 'DELETE', headers: { 'X-Api-Key': 'YOUR_API_KEY' } }
)
const body = await res.json()
if (body.success) console.log('Domain detached')
```

### JavaScript — OAuth application

```javascript
const res = await fetch(
  `https://vibecode.bitrix24.com/v1/infra/servers/${serverId}/domain`,
  {
    method: 'DELETE',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
    },
  }
)
```

## Response fields

| Field | Type | Description |
|------|-----|----------|
| `success` | boolean | `true` when the domain is detached |
| `data.deleted` | boolean | `true` — the attachment is removed |

Unlike deleting CRM entity records, this endpoint responds with `200` and a body, not `204 No Content`.

## Response example

```json
{
  "success": true,
  "data": {
    "deleted": true
  }
}
```

## Error response example

404 — no domain is attached to the server:

```json
{
  "success": false,
  "error": {
    "code": "NO_DOMAIN",
    "message": "No domain attached"
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|----------|
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |
| 401 | `INVALID_API_KEY` | The key is not recognized — no such key exists on the platform |
| 403 | `INFRA_SCOPE_REQUIRED` | The key lacks the `vibe:infra` scope. Checked before the server lookup |
| 403 | `INFRA_FORBIDDEN_FOR_COWORK_KEY` | The call was made with a Cowork/Code key — such a key works with data only and cannot perform write operations. What to do — [Project key for deploy](/docs/cowork/deploy-key) |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is in read-only mode — write operations are blocked for it |
| 404 | `SERVER_NOT_FOUND` | The server was not found, was deleted, or is managed by another key |
| 404 | `NO_DOMAIN` | No domain is attached to the server, including on a repeated detach |
| 429 | `RATE_LIMITED` | The limit of 5 requests per minute for this endpoint was exceeded. The limit is counted per key owner, not per individual key. The exact value arrives in the `x-ratelimit-limit` header (the cap is divided across replicas) |
| 503 | `CUSTOM_DOMAIN_REGISTRY_UNAVAILABLE` | The domain registry did not respond, so the domain was not detached. A domain in the `ACTIVE` status moves to `SUSPENDED` in this case, and the application may stop responding on it. Retry the call later |
| 503 | `user_self_deletion_pending` | The key owner requested deletion of their account on the portal. Access is restored once the deletion is cancelled |

Full list of common API errors — [Errors](/docs/errors).

## Known specifics

- **Records at the DNS provider remain.** Detaching does not touch them: delete the `TXT` record and the `CNAME` or `A` record yourself.
- **The previous `TXT` record will not work for a new attachment.** Attaching the same name again issues a new `TXT` value, so replace the record at the DNS provider and run [verification](./verify.md) again.

## See also

- [Attach a domain](./attach.md)
- [Get the domain](./get.md)
- [Verify the domain](./verify.md)
- [Custom domain](/docs/infra/domain)