For AI agents: markdown of this page — /docs-content-en/bots/management/delete.md documentation index — /llms.txt

Delete a bot

DELETE /v1/bots/:botId

Deletes a bot from Bitrix24 and from the Vibecode database. The action is irreversible.

Parameters

Parameter Type Required Description
botId number yes Bot ID (path parameter)
force (query) boolean no true retries deletion while preserving the Bot and its key if Bitrix24 does not confirm removal (409 BOT_DELETE_PENDING). By default, a Bitrix24 error keeps the record and returns 502 BOT_DELETE_PARTIAL

Examples

curl — personal key

Terminal 
curl -X DELETE https://vibecode.bitrix24.com/v1/bots/42 \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl -X DELETE https://vibecode.bitrix24.com/v1/bots/42 \
  -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/bots/42', {
  method: 'DELETE',
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { data } = await res.json()
console.log(data) // { deleted: true }

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/bots/42', {
  method: 'DELETE',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

Response fields

Field Type Description
data.deleted boolean true on successful deletion
data.alreadyAbsentOnB24 boolean Present when Bitrix24 no longer had this bot registered: the record is deleted from the Vibecode database and nothing is left behind on the Bitrix24 side

Response example

JSON 
{
  "success": true,
  "data": {
    "deleted": true
  }
}

Error response example

404 — bot not found:

JSON 
{
  "success": false,
  "error": {
    "code": "BOT_NOT_FOUND",
    "message": "Bot 42 not found. Register it first via POST /v1/bots."
  }
}

Errors

HTTP Code Description
400 INVALID_BOT_ID botId is not a number
404 BOT_NOT_FOUND Bot not found
403 BOT_ACCESS_DENIED The bot belongs to a different API key
502 BOT_DELETE_PARTIAL Bitrix24 rejected the unregister and the bot's removal could not be confirmed; the Vibecode database record is kept. The message states separately whether the bot is definitely still there or whether the check was inconclusive. The error text is in error.b24UnregisterError, and a six-character support code is in error.incidentCode. Call POST /v1/bots/:botId/reauth only when error.details.reauthAllowed=true; otherwise resolve the cause of the disabled state first
409 BOT_DELETE_PENDING With ?force=true, removal on Bitrix24 was not confirmed. The Bot and its retry handle remain; retry DELETE after the Retry-After interval
403 SCOPE_DENIED The API key does not have the imbot scope
403 WRITE_BLOCKED_READONLY_KEY The key is read-only — see access rights
401 TOKEN_MISSING The API key has no configured tokens

Full list of common API errors — Errors.

Known specifics

Cascade deletion: deleting a bot also deletes the linked AI agent or managed bot records, if they were bound to this bot.

Irreversibility: the bot is deleted both from Bitrix24 and from the Vibecode database. Reusing it requires a new registration via POST /v1/bots.

Repeating the call is safe: if Bitrix24 answers that it has no such bot, the deletion counts as successful — the Vibecode database record is removed and the 200 response carries alreadyAbsentOnB24: true. No ?force=true needed. The same applies when Bitrix24 rejected the unregister but had in fact already removed the bot: Vibecode additionally checks whether the bot is still on the account and answers with success when it is gone. A check that itself fails (an expired token, say) does not count as confirmation — 502 is returned.

Partial deletion and ?force=true: when removal on Bitrix24 cannot be confirmed, ordinary DELETE returns 502 BOT_DELETE_PARTIAL and ?force=true returns 409 BOT_DELETE_PENDING with Retry-After. Both keep the Vibecode record for a later retry. ?force=true bypasses local availability guards but does not treat an unknown remote result as success. If Bitrix24 confirms the bot is absent, the record is deleted and the response carries alreadyAbsentOnB24: true.

See also