Copy page

Guides

Knowledge Base

Knowledge bases provide your agents with reference material they can search during calls. When a caller asks a question, the agent queries attached knowledge bases for relevant chunks and uses them to ground its response — preventing hallucination and keeping answers accurate.

This is retrieval-augmented generation (RAG) applied to real-time voice conversations.

Prerequisites: Neuratel account, API key

---

How it works

1. You create a knowledge base from a URL, plain text, or file upload.
2. Neuratel splits the content into chunks and indexes them for semantic search.
3. You attach the knowledge base to one or more agents.
4. During a call, the agent searches the knowledge base when it needs information.
5. Relevant chunks are injected into the LLM context alongside the conversation history.

---

Create from URL

Scrape and index the content of a web page.

Code
curl -X POST https://api.neuratel.ai/v1/knowledge-base \
  -H "Authorization: Bearer nk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product FAQ",
    "type": "url",
    "url": "https://example.com/faq",
    "description": "Frequently asked questions about our products"
  }'

Code
import httpx

client = httpx.Client(
    base_url="https://api.neuratel.ai",
    headers={"Authorization": "Bearer nk_live_your_api_key"},
)

kb = client.post("/v1/knowledge-base", json={
    "name": "Product FAQ",
    "type": "url",
    "url": "https://example.com/faq",
    "description": "Frequently asked questions about our products",
}).json()

print(kb["id"])  # kb_abc123

Code
const kb = await fetch("https://api.neuratel.ai/v1/knowledge-base", {
  method: "POST",
  headers: {
    "Authorization": "Bearer nk_live_your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Product FAQ",
    type: "url",
    url: "https://example.com/faq",
    description: "Frequently asked questions about our products",
  }),
}).then((r) => r.json());

console.log(kb.id); // kb_abc123

---

Create from text

Directly paste text content — useful for internal policies, scripts, or structured data.

Code
curl -X POST https://api.neuratel.ai/v1/knowledge-base \
  -H "Authorization: Bearer nk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Return Policy",
    "type": "text",
    "content": "Our return policy allows returns within 30 days of purchase. Items must be in original packaging. Refunds are processed within 5-7 business days. Digital products are non-refundable. Contact [email protected] for exceptions.",
    "description": "Company return and refund policy"
  }'

Code
kb = client.post("/v1/knowledge-base", json={
    "name": "Return Policy",
    "type": "text",
    "content": (
        "Our return policy allows returns within 30 days of purchase. "
        "Items must be in original packaging. Refunds are processed within "
        "5-7 business days. Digital products are non-refundable. "
        "Contact [email protected] for exceptions."
    ),
    "description": "Company return and refund policy",
}).json()

Code
const kb = await fetch("https://api.neuratel.ai/v1/knowledge-base", {
  method: "POST",
  headers: {
    "Authorization": "Bearer nk_live_your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Return Policy",
    type: "text",
    content:
      "Our return policy allows returns within 30 days of purchase. " +
      "Items must be in original packaging. Refunds are processed within " +
      "5-7 business days. Digital products are non-refundable. " +
      "Contact [email protected] for exceptions.",
    description: "Company return and refund policy",
  }),
}).then((r) => r.json());

---

Create from file upload

Upload a document. Supported formats: PDF, DOCX, TXT, MD, HTML, EPUB (max 21 MB).

Code
curl -X POST https://api.neuratel.ai/v1/knowledge-base \
  -H "Authorization: Bearer nk_live_your_api_key" \
  -F "name=Product Manual" \
  -F "type=file" \
  -F "description=Technical product documentation v2.1" \
  -F "[email protected]"

Code
with open("product-manual.pdf", "rb") as f:
    kb = client.post(
        "/v1/knowledge-base",
        data={
            "name": "Product Manual",
            "type": "file",
            "description": "Technical product documentation v2.1",
        },
        files={"file": ("product-manual.pdf", f, "application/pdf")},
    ).json()

Code
const formData = new FormData();
formData.append("name", "Product Manual");
formData.append("type", "file");
formData.append("description", "Technical product documentation v2.1");
formData.append("file", fileBlob, "product-manual.pdf");

const kb = await fetch("https://api.neuratel.ai/v1/knowledge-base", {
  method: "POST",
  headers: { "Authorization": "Bearer nk_live_your_api_key" },
  body: formData,
}).then((r) => r.json());

Response:

Code
{
  "id": "kb_abc123",
  "name": "Product Manual",
  "type": "file",
  "status": "processing",
  "created_at": "2026-04-07T09:00:00Z"
}

---

Processing status

After creation, the knowledge base is indexed asynchronously. Check status with GET /v1/knowledge-base/{id}.

Status	Meaning
processing	Content is being chunked and indexed
ready	Knowledge base is searchable
failed	Processing failed — check the error field

The agent will not use the knowledge base until status is ready.

---

Attach to an agent

Include knowledge base IDs in the agent configuration so the agent searches them during calls.

Code
curl -X PATCH https://api.neuratel.ai/v1/agents/agent_abc123 \
  -H "Authorization: Bearer nk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "knowledge_base_ids": ["kb_abc123", "kb_def456"]
  }'

Code
client.patch("/v1/agents/agent_abc123", json={
    "knowledge_base_ids": ["kb_abc123", "kb_def456"],
})

Code
await fetch("https://api.neuratel.ai/v1/agents/agent_abc123", {
  method: "PATCH",
  headers: {
    "Authorization": "Bearer nk_live_your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    knowledge_base_ids: ["kb_abc123", "kb_def456"],
  }),
});

You can attach multiple knowledge bases to a single agent. The agent searches all of them and uses the most relevant chunks.

---

List knowledge bases

Code
curl "https://api.neuratel.ai/v1/knowledge-base?limit=20" \
  -H "Authorization: Bearer nk_live_your_api_key"

---

Update a knowledge base

Code
curl -X PUT https://api.neuratel.ai/v1/knowledge-base/kb_abc123 \
  -H "Authorization: Bearer nk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Manual v3",
    "description": "Updated technical documentation"
  }'

---

Delete a knowledge base

Code
curl -X DELETE https://api.neuratel.ai/v1/knowledge-base/kb_abc123 \
  -H "Authorization: Bearer nk_live_your_api_key"

Deleting a knowledge base automatically removes it from all agents that reference it.

---

Rate limits

Operation	Limit
Bulk imports (file/URL)	10 per hour
Text-based creates	60 per hour
Queries	No separate limit (included in agent call processing)

If you exceed the bulk import limit, the API returns 429 Too Many Requests.

---

Best practices

Practice	Reason
One topic per knowledge base	Improves retrieval relevance — a smaller, focused KB returns better chunks than a large, mixed one
Keep source documents updated	Stale data causes the agent to give outdated answers. Re-upload when content changes
Write content in Q&A format	The chunking algorithm works well with question-answer pairs
Test retrieval before assigning	Run test calls and check transcripts to verify the agent is finding the right information
Use descriptive names	Product FAQ — Returns is easier to manage than KB 3

---

Limits

Limit	Value
Max file size	21 MB
Supported formats	PDF, DOCX, TXT, MD, HTML, EPUB
Max knowledge bases per organisation	100
Max chunks per knowledge base	10,000

---

Related

• Building Your First Agent
• Agent Studio
• Tools and Actions