---
agentTools:
  projectIndex: https://developers.pipefy.com/llms.txt
---

# Delete Knowledge Base Document

Delete a pipe-scoped knowledge base document

## Before You Begin

🔗 **Use the [GraphQL Playground](https://app.pipefy.com/graphiql)** to execute the queries in this guide.

➡️ **New to GraphQL?** Learn how to navigate the Playground with our **[Playground Basics Guide](https://developers.pipefy.com/reference/exploring-the-playground)**.

## Prerequisites

1. **Authentication**: Use a [Service Account token](https://developers.pipefy.com/reference/service-accounts) (Personal Access Tokens are deprecated).
2. **Permissions**: You must be **admin** of the pipe where the document was created.
3. **Document ID**: The `id` returned when the document was created. See [Create Knowledge Base Document](https://developers.pipefy.com/reference/create-knowledge-base-document-mutation).

> ⚠️ **Deletion is permanent.** A deleted document cannot be recovered. Any AI agents that reference the document will no longer have access to its content.

## Delete a Knowledge Base Document

Use the `deleteAiKnowledgeBaseDocument` mutation to permanently delete a document from a pipe's knowledge base.

#### Inputs

* **pipeUuid**: UUID of the pipe the document belongs to (required).
* **documentId**: ID of the knowledge base document to delete (required).

```graphql
mutation {
  deleteAiKnowledgeBaseDocument(input: { pipeUuid: "pipe-uuid-123", documentId: "doc-uuid-789" }) {
    success
    errors
  }
}
```

Response:

```json
{
  "data": {
    "deleteAiKnowledgeBaseDocument": {
      "success": true,
      "errors": []
    }
  }
}
```

### Response explained

* **success**: `true` when the document was successfully deleted, `false` otherwise.
* **errors**: Array of error messages when the deletion fails. Empty on success.

### Error handling

If the deletion fails (e.g., permission denied or pipe not found), you'll receive an error response:

```json
{
  "data": {
    "deleteAiKnowledgeBaseDocument": null
  },
  "errors": [
    {
      "message": "Permission denied",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": ["deleteAiKnowledgeBaseDocument"]
    }
  ]
}
```

#### Error response explained

* **data.deleteAiKnowledgeBaseDocument**: Returns `null` when the operation fails.
* **errors**: Array containing error details when the operation fails.
* **errors\[].message**: Human-readable error description. Common messages:
  * `"Permission denied"` — the authenticated user is not an admin of the pipe.
  * `"Pipe not found with id: <uuid>"` — the `pipeUuid` does not match an existing pipe.
  * `"Field 'deleteAiKnowledgeBaseDocument' doesn't exist on type 'Mutation'"` — the feature flag is not enabled for the organization.

## Tips

* **Agent references**: Deleting a document automatically removes it from all agents and behaviors that reference it.
* **Finding your document ID**: The `id` is returned by the `createAiKnowledgeBaseDocument` mutation. See [Create Knowledge Base Document](https://developers.pipefy.com/reference/create-knowledge-base-document-mutation).