Knowledge Base

From the CLI

npx zavudev agents knowledge-bases create --sender <senderId> --name "Product docs"
npx zavudev agents knowledge-bases documents add --sender <senderId> --kb <kbId> \
  --title "Pricing" --content-file ./pricing.md
npx zavudev agents knowledge-bases documents list --sender <senderId> --kb <kbId>

Processing takes a few seconds; isProcessed flips to true and chunkCount fills in. Verify retrieval actually fires with npx zavudev agents test — it reports how many chunks the answer used.

A prompt that says “only state what the documentation returns” with no documents attached does not refuse. It invents. Attach the documents before relying on that instruction.

Knowledge Base

A Knowledge Base lets your AI agent answer questions using your own documents. Upload FAQs, product docs, policies, or any text content, and the agent will search for relevant information when responding to customers.

What is a Knowledge Base?

A Knowledge Base is a collection of documents that your agent can reference. When a customer asks a question, the agent:

Searches the knowledge base for relevant content
Retrieves the most relevant chunks
Includes that context in its prompt
Generates an informed response

This approach is called RAG (Retrieval Augmented Generation).

Use Cases

Use Case	Documents to Upload
Customer Support	FAQs, troubleshooting guides, help articles
Product Information	Product specs, features, pricing
Policy Questions	Terms of service, privacy policy, refund policy
Technical Support	Documentation, API guides, tutorials
Sales	Product comparisons, case studies, benefits

Via Dashboard

Navigate to Knowledge Bases

Go to Senders > select your sender > Agent tab > Knowledge Bases section.

Create Knowledge Base

Click Create Knowledge Base and enter:

Name: A descriptive name (e.g., “Product FAQs”)
Description: What this knowledge base contains

Add Documents

Click Add Document and choose how to add content:

Text: Paste text content directly
Markdown: Upload .md files
PDF: Upload PDF documents
URL: Import content from a webpage

Wait for Processing

Documents are automatically chunked and embedded. This takes a few seconds for small documents, longer for large PDFs.

You’ll see a processing indicator while chunks are being created. The agent can only use fully processed documents.

Verify

Check the document list to see:

Chunk Count: Number of searchable chunks created
Processing Status: Whether the document is ready

Via API

Create Knowledge Base

import Zavudev from "@zavudev/sdk";

const zavu = new Zavudev({
  apiKey: process.env["ZAVUDEV_API_KEY"],
});

const kb = await zavu.senders.agent.knowledgeBases.create("sender_abc123", {
  name: "Product FAQs",
  description: "Frequently asked questions about our products",
});

console.log("Knowledge Base created:", kb.id);

import os
from zavudev import Zavudev

zavu = Zavudev(
    api_key=os.environ.get("ZAVUDEV_API_KEY"),
)

kb = zavu.senders.agent.knowledge_bases.create(
    "sender_abc123",
    name="Product FAQs",
    description="Frequently asked questions about our products",
)

print(f"Knowledge Base created: {kb.id}")

require "zavudev"

client = Zavudev::Client.new(api_key: ENV["ZAVUDEV_API_KEY"])

kb = client.senders.agent.knowledge_bases.create("sender_abc123",
  name: "Product FAQs",
  description: "Frequently asked questions about our products"
)

puts "Knowledge Base created: #{kb.id}"

kb, _ := client.Senders.Agent.KnowledgeBases.New(context.TODO(), "sender_abc123", zavudev.KnowledgeBaseCreateParams{
	Name:        zavudev.String("Product FAQs"),
	Description: zavudev.String("Frequently asked questions about our products"),
})

fmt.Printf("Knowledge Base created: %s\n", kb.ID)

$kb = $client->senders->agent->knowledgeBases->create('sender_abc123', [
    'name' => 'Product FAQs',
    'description' => 'Frequently asked questions about our products',
]);

echo "Knowledge Base created: {$kb->id}\n";

curl -X POST https://api.zavu.dev/v1/senders/sender_abc123/agent/knowledge-bases \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product FAQs",
    "description": "Frequently asked questions about our products"
  }'

Add Document

const document = await zavu.senders.agent.knowledgeBases.documents.create(
  "sender_abc123",
  "kb_xyz789",
  {
    title: "Return Policy",
    content: `# Return Policy

## 30-Day Returns
All products can be returned within 30 days of purchase for a full refund.

## Conditions
- Items must be unused and in original packaging
- Original receipt required
- Shipping costs are non-refundable

## How to Return
1. Contact support@example.com
2. Receive return shipping label
3. Ship item within 7 days
4. Refund processed within 5 business days

## Exceptions
- Final sale items cannot be returned
- Custom orders are non-refundable
`,
  }
);

console.log("Document added:", document.id);

document = zavu.senders.agent.knowledge_bases.documents.create(
    "sender_abc123",
    "kb_xyz789",
    title="Return Policy",
    content="""# Return Policy

## 30-Day Returns
All products can be returned within 30 days of purchase for a full refund.

## Conditions
- Items must be unused and in original packaging
- Original receipt required
- Shipping costs are non-refundable

## How to Return
1. Contact support@example.com
2. Receive return shipping label
3. Ship item within 7 days
4. Refund processed within 5 business days

## Exceptions
- Final sale items cannot be returned
- Custom orders are non-refundable
""",
)

print(f"Document added: {document.id}")

document = client.senders.agent.knowledge_bases.documents.create("sender_abc123", "kb_xyz789",
  title: "Return Policy",
  content: "# Return Policy\n\n## 30-Day Returns\nAll products can be returned within 30 days of purchase for a full refund.\n\n## Conditions\n- Items must be unused and in original packaging\n- Original receipt required\n- Shipping costs are non-refundable\n\n## How to Return\n1. Contact support@example.com\n2. Receive return shipping label\n3. Ship item within 7 days\n4. Refund processed within 5 business days\n\n## Exceptions\n- Final sale items cannot be returned\n- Custom orders are non-refundable"
)

puts "Document added: #{document.id}"

document, _ := client.Senders.Agent.KnowledgeBases.Documents.New(context.TODO(), "sender_abc123", "kb_xyz789", zavudev.DocumentCreateParams{
	Title:   zavudev.String("Return Policy"),
	Content: zavudev.String("# Return Policy\n\n## 30-Day Returns\nAll products can be returned within 30 days of purchase for a full refund.\n\n## Conditions\n- Items must be unused and in original packaging\n- Original receipt required\n- Shipping costs are non-refundable\n\n## How to Return\n1. Contact support@example.com\n2. Receive return shipping label\n3. Ship item within 7 days\n4. Refund processed within 5 business days\n\n## Exceptions\n- Final sale items cannot be returned\n- Custom orders are non-refundable"),
})

fmt.Printf("Document added: %s\n", document.ID)

$document = $client->senders->agent->knowledgeBases->documents->create('sender_abc123', 'kb_xyz789', [
    'title' => 'Return Policy',
    'content' => "# Return Policy\n\n## 30-Day Returns\nAll products can be returned within 30 days of purchase for a full refund.\n\n## Conditions\n- Items must be unused and in original packaging\n- Original receipt required\n- Shipping costs are non-refundable\n\n## How to Return\n1. Contact support@example.com\n2. Receive return shipping label\n3. Ship item within 7 days\n4. Refund processed within 5 business days\n\n## Exceptions\n- Final sale items cannot be returned\n- Custom orders are non-refundable",
]);

echo "Document added: {$document->id}\n";

curl -X POST https://api.zavu.dev/v1/senders/sender_abc123/agent/knowledge-bases/kb_xyz789/documents \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Return Policy",
    "content": "# Return Policy\n\n## 30-Day Returns\nAll products can be returned within 30 days..."
  }'

List Knowledge Bases

const kbs = await zavu.senders.agent.knowledgeBases.list("sender_abc123");

for (const kb of kbs.items) {
  console.log(`${kb.name}: ${kb.documentCount} documents, ${kb.totalChunks} chunks`);
}

kbs = zavu.senders.agent.knowledge_bases.list("sender_abc123")

for kb in kbs.items:
    print(f"{kb.name}: {kb.document_count} documents, {kb.total_chunks} chunks")

kbs = client.senders.agent.knowledge_bases.list("sender_abc123")

kbs.items.each do |kb|
  puts "#{kb.name}: #{kb.document_count} documents, #{kb.total_chunks} chunks"
end

kbs, _ := client.Senders.Agent.KnowledgeBases.List(context.TODO(), "sender_abc123", zavudev.KnowledgeBaseListParams{})

for _, kb := range kbs.Items {
	fmt.Printf("%s: %d documents, %d chunks\n", kb.Name, kb.DocumentCount, kb.TotalChunks)
}

$kbs = $client->senders->agent->knowledgeBases->list('sender_abc123');

foreach ($kbs->items as $kb) {
    echo "{$kb->name}: {$kb->documentCount} documents, {$kb->totalChunks} chunks\n";
}

curl https://api.zavu.dev/v1/senders/sender_abc123/agent/knowledge-bases \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY"

List Documents

const docs = await zavu.senders.agent.knowledgeBases.documents.list(
  "sender_abc123",
  "kb_xyz789"
);

for (const doc of docs.items) {
  console.log(`${doc.title}: ${doc.chunkCount} chunks`);
}

docs = zavu.senders.agent.knowledge_bases.documents.list(
    "sender_abc123",
    "kb_xyz789"
)

for doc in docs.items:
    print(f"{doc.title}: {doc.chunk_count} chunks")

docs = client.senders.agent.knowledge_bases.documents.list("sender_abc123", "kb_xyz789")

docs.items.each do |doc|
  puts "#{doc.title}: #{doc.chunk_count} chunks"
end

docs, _ := client.Senders.Agent.KnowledgeBases.Documents.List(context.TODO(), "sender_abc123", "kb_xyz789", zavudev.DocumentListParams{})

for _, doc := range docs.Items {
	fmt.Printf("%s: %d chunks\n", doc.Title, doc.ChunkCount)
}

$docs = $client->senders->agent->knowledgeBases->documents->list('sender_abc123', 'kb_xyz789');

foreach ($docs->items as $doc) {
    echo "{$doc->title}: {$doc->chunkCount} chunks\n";
}

curl https://api.zavu.dev/v1/senders/sender_abc123/agent/knowledge-bases/kb_xyz789/documents \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY"

Delete Document

await zavu.senders.agent.knowledgeBases.documents.delete(
  "sender_abc123",
  "kb_xyz789",
  "doc_abc123"
);

zavu.senders.agent.knowledge_bases.documents.delete(
    "sender_abc123",
    "kb_xyz789",
    "doc_abc123"
)

client.senders.agent.knowledge_bases.documents.delete("sender_abc123", "kb_xyz789", "doc_abc123")

client.Senders.Agent.KnowledgeBases.Documents.Delete(context.TODO(), "sender_abc123", "kb_xyz789", "doc_abc123")

$client->senders->agent->knowledgeBases->documents->delete('sender_abc123', 'kb_xyz789', 'doc_abc123');

curl -X DELETE https://api.zavu.dev/v1/senders/sender_abc123/agent/knowledge-bases/kb_xyz789/documents/doc_abc123 \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY"

How RAG Works

Customer: "What's your return policy?"
                    |
                    v
            +------------------+
            | Embed Question   |
            | Create vector    |
            +------------------+
                    |
                    v
            +------------------+
            | Vector Search    |
            | Find similar     |
            | chunks           |
            +------------------+
                    |
                    v
            +------------------+
            | Retrieve Top     |
            | Chunks (e.g., 3) |
            +------------------+
                    |
                    v
            +------------------+
            | Inject Context   |
            | into LLM Prompt  |
            +------------------+
                    |
                    v
            +------------------+
            | Generate Answer  |
            | with Context     |
            +------------------+
                    |
                    v
Customer: "You can return any item within
           30 days for a full refund. Items
           must be unused and in original
           packaging. Contact support@..."

Processing Steps

Chunking: Documents are split into smaller pieces (~500-1000 tokens each)
Embedding: Each chunk is converted to a vector using an embedding model
Indexing: Vectors are stored for fast similarity search
Retrieval: When a question arrives, we find the most similar chunks
Generation: Retrieved chunks are included in the LLM prompt as context

What you can put in, and where

Which formats are accepted depends on the surface, and the API is the narrowest of the three. It takes text and nothing else.

Source	Dashboard	API / SDK	CLI
Text or Markdown pasted in	yes	yes — `content`	yes — `--content` / `--content-file`
A file: `.pdf`, `.docx`, `.doc`, `.odt`, `.xlsx`, `.xls`, `.csv`, `.txt`, `.md`, `.json`	yes	no	no
A web page, by URL	yes	no	no

The API’s POST /v1/senders/{senderId}/agent/knowledge-bases/{kbId}/documents takes title and content, both strings. There is no upload endpoint for knowledge-base files and no URL parameter: to load a PDF or a page from your own code, extract the text yourself and send it as content. A document knows where it came from — sourceType and sourceUrl are stored and returned, so one imported from the web can be told apart from one that was pasted. They are not yet declared in the OpenAPI schema, so a generated SDK will not type them; read them from the raw response until it is.

File extraction is text only. Images and charts are not read, and a table is flattened into the surrounding text.

Importing a web page

In the dashboard, open the agent, go to Knowledge, choose a knowledge base, then Add document → URL. It reads that one page — not the site — and files it under a knowledge base named after the host, so several pages of the same site group together. Add the pages that answer questions one at a time: shipping, returns, pricing. The onboarding assistant can do the same thing if you paste a link into the chat. This adds to what the agent knows. It does not change the agent’s prompt, its model or its channels.

Document Limits

Limit	Value
Max `content` per document, API	500,000 characters
Max characters kept from an imported web page	40,000
Documents added by one website import	30
Chunks added by one website import	1,500

The last three are the website importer’s caps. Documents you create through the API or the dashboard are bounded by content length, and by nothing else today: there is no enforced ceiling on documents per knowledge base or on knowledge bases per agent, so plan capacity from content size rather than from a document count.

Best Practices

Structure Content

Use headers, bullet points, and clear sections. Well-structured content creates better chunks.

Be Specific

Include specific answers to common questions. The more explicit, the better the retrieval.

Keep Current

Update documents when information changes. Outdated content leads to incorrect answers.

Separate Topics

Create separate documents for different topics. This improves retrieval accuracy.

Content Writing Tips

Good document structure:

# Product Returns

## How long do I have to return an item?
You have 30 days from the delivery date to return any item for a full refund.

## What condition must items be in?
Items must be unused, unworn, and in original packaging with all tags attached.

## How do I start a return?
1. Email support@example.com with your order number
2. We'll send a prepaid return label within 24 hours
3. Ship the item within 7 days
4. Refund processes within 5 business days of receipt

Poor document structure:

Returns are processed within the timeframe specified in our terms. Contact support for assistance with any issues you may have regarding your order.

Write documents as if you’re answering specific customer questions. This makes retrieval more accurate.

Example Documents

FAQ Document

# Shipping FAQs

## How long does shipping take?
- Standard shipping: 5-7 business days
- Express shipping: 2-3 business days
- Same-day delivery: Available in select cities

## How much does shipping cost?
- Free shipping on orders over $50
- Standard shipping: $5.99
- Express shipping: $12.99

## Do you ship internationally?
Yes! We ship to over 50 countries. International shipping takes 7-14 business days.

## Can I track my order?
Yes, you'll receive a tracking number via email once your order ships.

Product Document

# Pro Widget X100

## Overview
The Pro Widget X100 is our flagship widget designed for professional use.

## Specifications
- Weight: 2.5 lbs
- Dimensions: 10" x 6" x 4"
- Battery life: 12 hours
- Warranty: 2 years

## Features
- Wireless connectivity (Bluetooth 5.0 and WiFi)
- Water-resistant (IP67 rating)
- Voice control compatible

## Price
- Standard edition: $299
- Pro edition: $449 (includes accessories)

## Common Questions

### Is it compatible with Mac?
Yes, works with macOS 10.15 and later.

### Can I use it outdoors?
Yes, the IP67 rating means it's water and dust resistant.

Next Steps

Setup Guide

Configure your AI agent settings

Add Tools

Let your agent execute actions

Create Flows

Build structured conversation paths

AI Agents Concept

Learn how agents work under the hood

Getting Started

Build agents

Send & receive

Operate

Developer tools

Integrations

Knowledge Base

From the CLI

Knowledge Base

What is a Knowledge Base?

Use Cases

Via Dashboard

Via API

Create Knowledge Base

Add Document

List Knowledge Bases

List Documents

Delete Document

How RAG Works

Processing Steps

What you can put in, and where

Importing a web page

Document Limits

Best Practices

Structure Content

Be Specific

Keep Current

Separate Topics

Content Writing Tips

Example Documents

FAQ Document

Product Document

Next Steps

Setup Guide

Add Tools

Create Flows

AI Agents Concept

​From the CLI

​Knowledge Base

​What is a Knowledge Base?

​Use Cases

​Via Dashboard

​Via API

​Create Knowledge Base

​Add Document

​List Knowledge Bases

​List Documents

​Delete Document

​How RAG Works

​Processing Steps

​What you can put in, and where

​Importing a web page

​Document Limits

​Best Practices

Structure Content

Be Specific

Keep Current

Separate Topics

​Content Writing Tips

​Example Documents

​FAQ Document

​Product Document

​Next Steps

Setup Guide

Add Tools

Create Flows

AI Agents Concept

From the CLI

Knowledge Base

What is a Knowledge Base?

Use Cases

Via Dashboard

Via API

Create Knowledge Base

Add Document

List Knowledge Bases

List Documents

Delete Document

How RAG Works

Processing Steps

What you can put in, and where

Importing a web page

Document Limits

Best Practices

Content Writing Tips

Example Documents

FAQ Document

Product Document

Next Steps