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
ParameterbotId (path) Typenumber Requiredyes DescriptionBot ID, the data.bots[].id field in the GET /v1/bots response
Parameterforce (query) Typeboolean Requiredno Descriptiontrue retries deletion and keeps the record 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
Fielddata.deleted Typeboolean Descriptiontrue on successful deletion
Fielddata.alreadyAbsentOnB24 Typeboolean DescriptionPresent 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
HTTP400 CodeINVALID_BOT_ID DescriptionbotId is not a number
HTTP404 CodeBOT_NOT_FOUND DescriptionBot not found
HTTP403 CodeBOT_ACCESS_DENIED DescriptionThe bot belongs to a different API key
HTTP502 CodeBOT_DELETE_PARTIAL DescriptionBitrix24 rejected the unregistration request 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
HTTP409 CodeBOT_DELETE_PENDING DescriptionWith ?force=true, removal on Bitrix24 was not confirmed. The record and the key are kept for a retry. Retry DELETE after the Retry-After interval
HTTP409 CodeBOT_EFFECT_IN_PROGRESS DescriptionAn earlier change to the bot, including a previous DELETE, is still being reconciled with Bitrix24. Nothing is sent to Bitrix24 and the record is kept. Retry after the delay in the Retry-After header: 30 seconds or, if the change is waiting for the next scheduled check, the time until that check, at most 300 seconds
HTTP409 CodeBOT_UNAVAILABLE DescriptionThe bot state must be repaired on the platform side. There is no Retry-After header, and retrying will not help. Contact support and quote the request time
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the imbot scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is read-only — see access rights
HTTP401 CodeTOKEN_MISSING DescriptionThe 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.

Reuse: a deleted bot cannot be restored. A new registration via POST /v1/bots is required.

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. ?force=true is not needed for this. The same applies when Bitrix24 rejected the unregistration request but had in fact already removed the bot: Vibecode additionally checks whether the bot is still in the Bitrix24 account and answers with success when it is gone. A check that itself fails (for example, because of an expired token) does not count as confirmation — 502 is returned.

What ?force=true changes: it bypasses local availability guards but does not treat an unknown result as success. While an earlier change to the bot is still being reconciled, 409 BOT_EFFECT_IN_PROGRESS is returned with ?force=true as well.

See also