Build a Knowledge Base - Naturalead API

Knowledge bases give your AI agents the context they need to have informed conversations with leads. Instead of relying solely on the system prompt, agents can retrieve relevant information from your knowledge base during each conversation turn using RAG (Retrieval-Augmented Generation). This guide covers every way to build and maintain a knowledge base: manual document uploads, automated website crawling, and webhook sources for live-updating content.

Understanding knowledge base types

Naturalead supports two types of knowledge bases:

Internal

For proprietary content such as product documentation, pricing sheets, FAQs, and sales playbooks. Content is uploaded manually or via webhook sources.

External

For publicly available content such as website pages, blog posts, and help center articles. Content is typically ingested via sitemap crawling.

The type is informational and does not affect how the AI retrieves content. Choose the type that best describes the source of your content so your team can manage knowledge bases effectively.

Prerequisites

Before starting, make sure you have:

A Naturalead account with an API key or dashboard access
The knowledge:upload permission (granted to owner, integrator, and ai_architect roles)
Content to ingest (text documents, a website URL, or an external API endpoint)

Step 1: Create a knowledge base

Step 2: Upload documents manually

For content you already have as text (FAQs, product specs, sales scripts), upload documents directly.

Documents are automatically chunked and indexed in the vector store. There is no separate indexing step required.

Step 3: Crawl a website via sitemap

For external knowledge bases, you can automatically ingest content from a website by crawling its sitemap.

Step 4: Manage crawl jobs

You can pause, resume, or cancel crawl jobs at any time. Pages already processed remain in the knowledge base regardless of the action taken.

Pause

Temporarily stop a running crawl. Useful if you need to reduce API load or review intermediate results.

Resume

Continue a paused crawl from where it left off. No pages are re-processed.

Cancel

Permanently stop a crawl. The job cannot be resumed after cancellation.

curl -X POST https://your-api.naturalead.com/api/knowledge-bases/KB_ID/crawl-jobs/JOB_ID/pause \
  -H "X-API-Key: nl_live_your_key"

curl -X POST https://your-api.naturalead.com/api/knowledge-bases/KB_ID/crawl-jobs/JOB_ID/resume \
  -H "X-API-Key: nl_live_your_key"

curl -X POST https://your-api.naturalead.com/api/knowledge-bases/KB_ID/crawl-jobs/JOB_ID/cancel \
  -H "X-API-Key: nl_live_your_key"

Step 5: Set up webhook sources for auto-updating content

Webhook sources let you automatically pull content from external APIs on a schedule. This is useful for keeping your knowledge base in sync with content that changes frequently, such as a CMS, helpdesk, or product catalog.

Webhook sources store authentication credentials (headers, auth config) in the database. Use dedicated service accounts with minimal permissions for external API access, and rotate credentials regularly.

Step 6: Attach a knowledge base to an agent

Once your knowledge base has content, attach it to an AI agent configuration so conversations can use it for RAG retrieval.

curl -X PUT https://your-api.naturalead.com/api/agent-config \
  -H "X-API-Key: nl_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "knowledgeBaseId": "KB_ID"
  }'

response = requests.put(
    "https://your-api.naturalead.com/api/agent-config",
    headers={
        "X-API-Key": "nl_live_your_key",
        "Content-Type": "application/json",
    },
    json={"knowledgeBaseId": kb_id},
)

config = response.json()
print(f"Agent config updated with KB: {config.get('knowledgeBaseId')}")

const response = await fetch(
  "https://your-api.naturalead.com/api/agent-config",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "nl_live_your_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ knowledgeBaseId: kbId }),
  }
);

const config = await response.json();
console.log(`Agent config updated with KB: ${config.knowledgeBaseId}`);

When a conversation is active, the AI agent queries the attached knowledge base on each inbound message to retrieve relevant context before generating a response.

Cleanup and maintenance

Delete a document

Remove a single document from a knowledge base. The document is also removed from the vector store.

curl -X DELETE https://your-api.naturalead.com/api/knowledge-bases/KB_ID/documents/DOC_ID \
  -H "X-API-Key: nl_live_your_key"

Delete a knowledge base

Deleting a knowledge base removes all associated documents, crawl jobs, and webhook sources.

This action is irreversible. All documents, crawl jobs, and webhook source configurations within the knowledge base will be permanently deleted.

curl -X DELETE https://your-api.naturalead.com/api/knowledge-bases/KB_ID \
  -H "X-API-Key: nl_live_your_key"

Summary

Method	Best for	Update frequency
Manual upload	Small, static content (FAQs, scripts)	As needed
Sitemap crawl	Website content, help centers, blogs	One-time or periodic re-crawl
Webhook source	Dynamic content from APIs, CMS, databases	Scheduled (configurable interval)

Combine all three methods within a single knowledge base to give your AI agent the most comprehensive context for lead qualification conversations.

​Understanding knowledge base types

Internal

External

​Prerequisites

​Step 1: Create a knowledge base

​Step 2: Upload documents manually

​Step 3: Crawl a website via sitemap

​Step 4: Manage crawl jobs

Pause

Resume

Cancel

​Step 5: Set up webhook sources for auto-updating content

​Step 6: Attach a knowledge base to an agent

​Cleanup and maintenance

​Delete a document

​Delete a knowledge base

​Summary

Understanding knowledge base types

Prerequisites

Step 1: Create a knowledge base

Step 2: Upload documents manually

Step 3: Crawl a website via sitemap

Step 4: Manage crawl jobs

Step 5: Set up webhook sources for auto-updating content

Step 6: Attach a knowledge base to an agent

Cleanup and maintenance

Delete a document

Delete a knowledge base

Summary