Skip to main content

​
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.
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.
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: 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

​

​
Path Parameters

​
string
required
Agent UUID.

​
Response (200)

​
object
{(id, name, status, organizationId)}
​
object | null
{slug} when the agent is live at /a/:slug and through the web widget; otherwise null.
​
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.
​
number
Conversations that are kept after the delete.
404 when the agent does not exist or is already deleted.

​
Get knowledge base impact

​

​
Path Parameters

​
string
required
Agent UUID.

​
Response (200)

​
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
​
boolean
true when the agent links more than 100 knowledge bases and the list was cut.
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.

​
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.