For AI agents: markdown of this page — /docs-content-en/infra/domain/detach.md documentation index — /llms.txt

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.

Parameters

Parameter In Type Required Description
Parameterid Inpath Typestring (UUID) Requiredyes DescriptionServer ID. Source — the id field from the server list

Examples

curl — personal key

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

curl — OAuth application

Terminal 
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
Fieldsuccess Typeboolean Descriptiontrue when the domain is detached
Fielddata.deleted Typeboolean Descriptiontrue — 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
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP401 CodeINVALID_API_KEY DescriptionThe key is not recognized — no such key exists on the platform
HTTP403 CodeINFRA_SCOPE_REQUIRED DescriptionThe key lacks the vibe:infra scope. Checked before the server lookup
HTTP403 CodeINFRA_FORBIDDEN_FOR_COWORK_KEY DescriptionThe 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
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is in read-only mode — write operations are blocked for it
HTTP404 CodeSERVER_NOT_FOUND DescriptionThe server was not found, was deleted, or is managed by another key
HTTP404 CodeNO_DOMAIN DescriptionNo domain is attached to the server, including on a repeated detach
HTTP429 CodeRATE_LIMITED DescriptionThe 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)
HTTP503 CodeCUSTOM_DOMAIN_REGISTRY_UNAVAILABLE DescriptionThe 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
HTTP503 Codeuser_self_deletion_pending DescriptionThe 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.

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 again.

See also