## 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` (path) | number | yes | Bot ID, the `data.bots[].id` field in the [`GET /v1/bots`](/docs/bots/management/list) response |
| `force` (query) | boolean | no | `true` 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

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

### curl — OAuth application

```bash
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 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 |
| 409 | `BOT_DELETE_PENDING` | With `?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 |
| 409 | `BOT_EFFECT_IN_PROGRESS` | An 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 |
| 409 | `BOT_UNAVAILABLE` | The 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 |
| 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](/docs/access-rights) |
| 401 | `TOKEN_MISSING` | The API key has no configured tokens |

Full list of common API errors — [Errors](/docs/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.

**Stalled long-name rename:** The owner of a standalone bot whose rename stalled after its name was truncated to 50 Unicode code points can call ordinary `DELETE /v1/bots/:botId` with the same API key. Vibecode cancels the unfinished rename only after confirming the bot is absent from Bitrix24. If ownership, the key or registration changed, or a previous request may still be in flight, the record is kept and the response is `409`. This path does not cover bots linked to AI agents or managed bots.

**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

- [Events](/docs/bots/events)
- [Messages](/docs/bots/messages)
- [Bot platform](/docs/bots)