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 — delete the record from the Vibecode database even if Bitrix24 rejected the unregister. By default, on a Bitrix24 error the record is kept and 502 BOT_DELETE_PARTIAL is returned

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
data.forced boolean Present with ?force=true when Bitrix24 rejected the unregister: the record is deleted from the Vibecode database, the bot remains on the Bitrix24 side
data.b24UnregisterError string Present together with forced. The Bitrix24 error text that caused the unregister to fail

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, or force-delete the record with ?force=true
403 SCOPE_DENIED The API key does not have the imbot scope
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: if Bitrix24 rejected the unregister and the bot's removal could not be confirmed, 502 BOT_DELETE_PARTIAL is returned and the Vibecode database record is kept. Retry after POST /v1/bots/:botId/reauth only when the response contains error.details.reauthAllowed=true; when it is false, that route returns 409 BOT_REAUTH_NOT_ALLOWED, so resolve the cause of the disabled state first, or use ?force=true. With ?force=true the record is deleted from the Vibecode database even on a Bitrix24 error, the bot stays on the Bitrix24 side until manual cleanup, and the response includes forced: true and b24UnregisterError. The exception is when Bitrix24 answers that the bot does not exist: nothing is orphaned, so the response carries alreadyAbsentOnB24: true instead of forced.

See also