> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brainstormer.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Delete Impact

> What deleting an agent removes or disables, and which of its knowledge bases may be deleted with it.

# Agent Delete Impact

Two read-only endpoints behind the **Delete agent** dialog. Together they say exactly what deleting an agent takes away, and which of its linked knowledge bases the caller may choose to delete as well. Neither endpoint deletes anything.

They are split by ownership: the bot service reports what happens to the **agent** (its public link and channels), the knowledge service reports the **knowledge bases** — including its own verdict on whether the caller may delete each one.

<Note>
  All API requests require a valid JWT token in the `Authorization: Bearer <token>` header. The API Gateway decodes the JWT and forwards auth context (`user-id`, `organization-id`, `user-email`, `x-platform-role`, `x-org-role`) as headers to downstream services.
</Note>

Both endpoints require **`delete`** permission on the agent — the same check `DELETE /api/bots/:id` applies. A caller who cannot delete the agent gets `403` (or `404` for an agent outside their organization) and learns nothing about what deleting it would do. Org owners, admins and members hold `delete` on every agent in their organization; a `viewer` needs an explicit grant.

***

## What deleting an agent does

Agent delete is a **soft delete** (`bots.deleted_at` is set; no row is removed). Nothing is erased; these things stop working:

| Effect | Detail |
| - | - |
| Public page and web widget | `/a/:slug` and the embedded widget return 404. Reported only when the agent is currently published and not a draft. |
| WhatsApp / WhatsApp Business | The channel stays connected and **stops replying** — inbound messages are dropped. Disconnect the channel first to free the number. |
| Conversations | **Kept.** They stay in the inbox, marked as from a deleted agent. |
| Linked knowledge bases | **Kept** unless you choose them. An unchosen KB stays in your workspace and still counts toward your plan's knowledge-base limit. |

Deleting a knowledge base is a **hard delete**: the KB, its documents, sources, vectors and graph data are removed, it stops counting toward your plan, and its links to agents are removed with it. Any other agent that used it keeps working without it.

***

## Get agent impact

<ParamField method="GET" path="/api/bots/:id/delete-impact" />

### Path Parameters

<ParamField path="id" type="string" required>
  Agent UUID.
</ParamField>

### Response (200)

<ResponseField name="agent" type="object">
  `{(id, name, status, organizationId)}`
</ResponseField>

<ResponseField name="publicLink" type="object | null">
  `{slug}` when the agent is live at `/a/:slug` and through the web widget;
  otherwise `null`.
</ResponseField>

<ResponseField name="channels" type="array">
  One entry per connected channel: `{(id, type, label, isActive)}`. `type` is
  `whatsapp` or `whatsapp_business` today; `label` is the display phone number
  when one is stored.
</ResponseField>

<ResponseField name="conversationCount" type="number">
  Conversations that are **kept** after the delete.
</ResponseField>

```json theme={null}
{
  "agent": {
    "id": "550e8400-…",
    "name": "Support bot",
    "status": "published",
    "organizationId": "9cbf9c29-…"
  },
  "publicLink": { "slug": "support-bot" },
  "channels": [
    {
      "id": "1b2c…",
      "type": "whatsapp_business",
      "label": "+91 91528 10101",
      "isActive": true
    }
  ],
  "conversationCount": 42
}
```

`404` when the agent does not exist or is already deleted.

***

## Get knowledge base impact

<ParamField method="GET" path="/api/knowledge/agents/:agentId/delete-impact" />

### Path Parameters

<ParamField path="agentId" type="string" required>
  Agent UUID.
</ParamField>

### Response (200)

<ResponseField name="knowledgeBases" type="array">
  Every knowledge base linked to the agent, in the agent's organization:

  * `id`, `name`, `documentCount`, `sourceCount`
  * `otherAgentCount` — every **other** live agent in the KB's organization that uses it
  * `otherAgents` — up to five of them by `{ id, name }`
  * `canDelete` — the knowledge service's own verdict for `DELETE /api/knowledge/kb/:id` for this caller
  * `cannotDeleteReason` — why `canDelete` is false, in plain words; otherwise `null`
</ResponseField>

<ResponseField name="truncated" type="boolean">
  `true` when the agent links more than 100 knowledge bases and the list was cut.
</ResponseField>

A knowledge base with `otherAgentCount > 0` is **shared**: deleting it would break those agents, so the dialog shows it but does not let you tick it.

```json theme={null}
{
  "truncated": false,
  "knowledgeBases": [
    {
      "id": "0aeb6534-…",
      "name": "Product docs",
      "documentCount": 12,
      "sourceCount": 2,
      "otherAgents": [],
      "otherAgentCount": 0,
      "canDelete": true,
      "cannotDeleteReason": null
    },
    {
      "id": "66666666-…",
      "name": "Shared FAQ",
      "documentCount": 4,
      "sourceCount": 1,
      "otherAgents": [{ "id": "…", "name": "Billing bot" }],
      "otherAgentCount": 3,
      "canDelete": true,
      "cannotDeleteReason": null
    }
  ]
}
```

***

## Deleting an agent with some of its knowledge bases

There is no bulk endpoint. The dialog runs the ordinary routes in order, so every delete keeps its own permission check and audit entry:

1. `DELETE /api/bots/:id` — if this fails, nothing else is attempted.
2. `DELETE /api/knowledge/kb/:id` once per chosen knowledge base.

If the agent is deleted but a knowledge base is not, the result is reported as partial: the agent is gone, the named knowledge bases remain, and they can be retried on their own.

Both deletes write an audit entry (`agent.delete`, `knowledge_base.delete`) under the organization that owned the resource.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.