Document ingestion, chunking, and RAG retrieval for your AI agents
The Knowledge Bases page (KnowledgeBasePage) manages document collections that power RAG retrieval for your agents. It provides a card-based list view of all knowledge bases, a two-panel detail view showing documents and their chunks, inline editing capabilities for both documents and chunks, and integration with the Knowledge Import Wizard for ingesting content from multiple sources.
Knowledge bases are organization-aware — they can be scoped to a specific client organization for data isolation, or kept internal to your organization.
RAG is the technique of retrieving relevant documents before generating a response. Instead of relying solely on the LLM's training data, the agent searches your knowledge base for specific, up-to-date information and uses it to form accurate answers.
A document is a source file you import (PDF, markdown, web page, etc.). A chunk is a smaller segment of that document — typically a few paragraphs — that the retrieval system can match against queries. Smaller chunks allow more precise retrieval but use less context per match.
Knowledge bases can be assigned to a client organization via clientOrgId. This ensures data isolation — agents in Org A cannot access Org B's knowledge bases. When the org context switcher is active, only relevant KBs are shown.
| Field | Required | Description |
|---|---|---|
| Name | Yes | Descriptive name (e.g., "Product Documentation Q1 2026") |
| Description | No | What this knowledge base contains and its purpose |
| Organization | No | Assign to a client org for data isolation, or leave as internal |
POST /api/engine/knowledge-bases
Content-Type: application/json
{
"name": "Customer Support Playbook",
"description": "Standard responses, escalation procedures, refund policies",
"orgId": "default-org-id",
"clientOrgId": "client-abc123"
}Clicking a knowledge base card opens the detail view with:
Documents are the source files imported into a knowledge base. Each document shows:
| Property | Description |
|---|---|
| Name | Document filename or title (editable inline) |
| Source Type | Where the document came from (upload, github, url, etc.) |
| MIME Type | File format (text/markdown, application/pdf, etc.) |
| Size | File size in bytes or KB |
| Chunk Count | Number of chunks generated from this document |
| Status | Processing status (pending, processed, error) |
Documents can be renamed via inline editing and deleted individually. Deleting a document removes all its chunks.
Select a document to view its chunks in the right panel. Each chunk displays:
// Update a chunk's content
PUT /api/engine/knowledge-bases/{kbId}/chunks/{chunkId}
Content-Type: application/json
{ "content": "Updated chunk text with corrected information..." }
// Delete a chunk
DELETE /api/engine/knowledge-bases/{kbId}/chunks/{chunkId}The Import Wizard (KnowledgeImportWizard) is accessible from both the list view and detail view. It supports importing content from:
Import jobs are tracked asynchronously — you can view their progress in the Import Jobs section of the detail view.
The Agent Access card in the KB detail view controls which agents can search and retrieve information from this knowledge base.
Each knowledge base has an agentIds array stored in the database. When an agent performs a RAG search via GET /knowledge-bases/search?agentId=xxx, only knowledge bases where the agent's ID is in the agentIds array are searched.
Updating agent access calls PUT /knowledge-bases/:id with the new agentIds array. Changes take effect immediately — the agent will have access on its very next query. No agent restart is required.
PUT /knowledge-bases/:id
{
"agentIds": ["agent-uuid-1", "agent-uuid-2"]
}When a new agent is created, knowledge bases are automatically assigned based on org context:
| Agent Type | Gets Access To |
|---|---|
| Client org agent | All KBs belonging to their client organization |
| Internal agent | All KBs NOT belonging to any client organization (shared/internal KBs) |
If you add new knowledge bases after agents are already running, use the "Sync Knowledge" button on the agent's Deployment tab to trigger auto-assignment for that agent.
POST /knowledge-bases/auto-assign/:agentId
Body: { "clientOrgId": "org-uuid" } // optional
Response: { "assigned": ["kb-id-1", "kb-id-2"], "count": 2 }Only adds new assignments — does not remove existing ones.
Agent access respects organization boundaries. If a knowledge base belongs to a client organization, only agents assigned to that organization can be given access. This ensures data isolation in multi-tenant deployments.
| Endpoint | Method | Description |
|---|---|---|
/api/engine/knowledge-bases | GET | List all knowledge bases |
/api/engine/knowledge-bases | POST | Create a new knowledge base |
/api/engine/knowledge-bases/{id} | GET | Get KB detail with documents and stats |
/api/engine/knowledge-bases/{id} | PUT | Update KB name, description, org assignment |
/api/engine/knowledge-bases/{id} | DELETE | Delete KB and all documents/chunks |
/api/engine/knowledge-bases/{id}/documents/{docId} | PUT | Rename a document |
/api/engine/knowledge-bases/{id}/documents/{docId} | DELETE | Delete a document and its chunks |
/api/engine/knowledge-bases/{id}/documents/{docId}/chunks | GET | List chunks for a document |
/api/engine/knowledge-bases/{id}/chunks/{chunkId} | PUT | Update chunk content |
/api/engine/knowledge-bases/{id}/chunks/{chunkId} | DELETE | Delete a single chunk |
The document may still be processing. Check the import jobs section for status. If the status is "error", the file format may not be supported or the content couldn't be extracted.
Check: (1) Is the KB assigned to the agent? (2) Are the relevant chunks well-formed? (3) Is the query phrasing similar to the chunk content? Try editing chunks for clarity.
Check the org context switcher — you may be viewing a different organization's KBs. Clear the org filter to see all knowledge bases.