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.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; the Vibecode database record is kept. The error text is in error.b24UnregisterError. Retry after POST /v1/bots/:botId/reauth or force-delete 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.

Partial deletion and ?force=true: if Bitrix24 rejected the unregister, by default 502 BOT_DELETE_PARTIAL is returned and the Vibecode database record is kept — retry after POST /v1/bots/:botId/reauth or force-delete with ?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.

See also