Delete Knowledge Base Document

Before You Begin

🔗 Use the GraphQL Playground to execute the queries in this guide.

➡️ New to GraphQL? Learn how to navigate the Playground with our Playground Basics Guide.

Prerequisites

1. Authentication: Use a Service Account token (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.

⚠️

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

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

Response:

{
  "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:

{
  "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.