Knowledge Bases

Knowledge bases allow your AI agents to retrieve information from your own documents during phone calls. Instead of relying solely on the system prompt, agents can search through uploaded files, web pages, and text content to provide accurate, grounded answers.

Overview

A knowledge base is a collection of sources — files, URLs, or text snippets — that your agent can search during a conversation. When a caller asks a question, the agent retrieves the most relevant passages from the knowledge base and uses them to formulate a response. This is especially useful for:

Product catalogs — answer questions about pricing, features, and availability
FAQ documents — handle common customer inquiries accurately
Policy documents — reference specific terms, conditions, or procedures
Internal wikis — provide support agents with up-to-date information
Training materials — ensure consistent, accurate responses across all calls

Creating a Knowledge Base

From the Dashboard

Navigate to Knowledge Bases in the sidebar
Click Create Knowledge Base
Enter a Name and optional Description
Click Create

Via API

curl -X POST https://api.revring.ai/v1/knowledge-bases \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product FAQ",
    "description": "Frequently asked questions about our products"
  }'

Adding Sources

Each knowledge base can contain up to 50 sources. Sources are processed asynchronously — after adding a source, it moves through the following statuses:

Status	Description
`queued`	Source is queued for processing
`processing`	Source is being indexed and will be available shortly
`ready`	Source is indexed and available for retrieval
`failed`	Processing failed (check `errorMessage` for details)

Text Sources

Add text content directly. Useful for FAQ lists, policy excerpts, or any structured text. Dashboard: Click Add Source → Text, enter a name and content, then click Add Text Source. API:

curl -X POST https://api.revring.ai/v1/knowledge-bases/{id}/sources \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceType": "text",
    "displayName": "Return Policy",
    "content": "Our return policy allows returns within 30 days of purchase. Items must be in original condition with receipt. Refunds are processed within 5-7 business days."
  }'

Text sources can be up to 100,000 characters.

URL Sources

Add a web page URL. RevRing fetches and indexes the page content automatically. Dashboard: Click Add Source → URL, enter a Name and the URL, then click Add URL Source. Turn on Read linked pages too to read a whole site, and pick a schedule under Keep it current. API:

curl -X POST https://api.revring.ai/v1/knowledge-bases/{id}/sources \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceType": "url",
    "originalUrl": "https://www.example.com/faq",
    "displayName": "FAQ Page"
  }'

Only http:// and https:// URLs are supported. Without crawl settings, the single page is read once, when the source is added.

Whole websites

Add crawl to read the pages a URL links to as well, so one source covers a help center or documentation site. RevRing starts at originalUrl and follows links on the same site under one path, up to maxPages pages, and combines them into one source with each page’s address. Linked files (images, PDFs, scripts, feeds, text files) are not followed; add those as file sources.

curl -X POST https://api.revring.ai/v1/knowledge-bases/{id}/sources \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceType": "url",
    "originalUrl": "https://help.example.com/",
    "displayName": "Help center",
    "crawl": { "maxPages": 25, "includePath": "/articles/", "refreshDays": 7 }
  }'

Field	Description
`maxPages`	Pages to read, 1 to 50 (default 1: only `originalUrl`).
`includePath`	Only follow links whose path starts with this, for example `/help/`. Defaults to the folder of `originalUrl`, so `https://example.com/help/start` stays under `/help/`.
`refreshDays`	Read the pages again every 1 to 90 days. Leave it out to read them once.

Reading a site takes up to a few minutes. When it finishes, the source’s crawl shows how many pages were read and when (lastFetchedAt). The content of all pages counts toward one source.

Keeping URL sources current

With refreshDays set, RevRing reads the pages again on that schedule. To read a URL source again right away (after you publish a change, for example), hover the source in the dashboard and click the refresh icon, or call:

curl -X POST https://api.revring.ai/v1/knowledge-bases/{id}/sources/{sourceId}/refresh \
  -H "x-api-key: YOUR_API_KEY"

The refresh runs in the background (202). Your agents keep using the current content the whole time: new content replaces it only once it is fully indexed, and when nothing changed, nothing is replaced. If a refresh cannot read the site, the current content stays. A source can be refreshed once a minute (429 otherwise), not while its first read is still running (409), and only URL sources can be refreshed (400).

File Sources

Upload documents directly. Supported formats: PDF, TXT, DOCX, MD, CSV, JSON. Dashboard: Click Add Source → File, then select a file from your computer. API:

curl -X POST https://api.revring.ai/v1/knowledge-bases/{id}/sources \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@/path/to/document.pdf"

Maximum file size is 20 MB.

Checking Source Status

After adding a source, you can check its processing status:

curl https://api.revring.ai/v1/knowledge-bases/{id}/sources/{sourceId} \
  -H "x-api-key: YOUR_API_KEY"

The response includes a status field (queued, processing, ready, or failed) and an errorMessage if processing failed.

Linking Knowledge Bases to Agents

Once your knowledge base has sources in the ready state, link it to one or more agents.

From the Dashboard

Open your agent’s settings
Go to the Knowledge tab
Click Link Knowledge Base
Select the knowledge base you want to link — it’s linked immediately

Via API

curl -X POST https://api.revring.ai/v1/agents/{agentId}/knowledge-bases \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "knowledgeBaseId": "kb_abc123"
  }'

To unlink:

curl -X DELETE https://api.revring.ai/v1/agents/{agentId}/knowledge-bases/{knowledgeBaseId} \
  -H "x-api-key: YOUR_API_KEY"

Retrieval Settings

When a knowledge base is linked to an agent, you can configure how the agent uses it. These settings are on the agent, not the knowledge base — so different agents can use the same knowledge base with different retrieval behaviors.

Retrieval Mode

Mode	Description
`automatic`	Labeled Automatic (RAG) in the dashboard. The agent automatically searches the knowledge base before every response. This is the default and recommended mode.
`query_tool`	Labeled Query Tool in the dashboard. The agent uses a dedicated tool to search the knowledge base. This gives you more control over when retrieval happens — useful if you want the agent to only search when explicitly asked.

Small knowledge bases are used in full. In automatic mode, when the combined text of an agent’s knowledge bases is small enough, the agent is simply given all of it — no search step, no chance of missing a passage, and no added latency. Larger knowledge bases (and ones built from uploaded files) use retrieval as described below. This applies across calls, web chat, and SMS.

Chunks to Retrieve

The number of text passages to retrieve per query (1–20, default 3). Higher values provide more context but use more tokens. Start with the default and increase if the agent is missing relevant information.

Similarity Threshold

Minimum relevance score for retrieved passages (0.0–1.0, default 0). Set this higher (e.g., 0.3–0.5) to filter out loosely related content. A value of 0 returns the top results regardless of relevance score.

Configuring via API

curl -X PATCH https://api.revring.ai/v1/agents/{agentId} \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "knowledgeBaseRetrievalMode": "automatic",
    "knowledgeBaseChunks": 5,
    "knowledgeBaseSimilarityThreshold": 0.3
  }'

Managing Sources

Deleting a Source

To remove a source from a knowledge base: Dashboard: Hover over the source row and click the trash icon, then confirm deletion. API:

curl -X DELETE https://api.revring.ai/v1/knowledge-bases/{id}/sources/{sourceId} \
  -H "x-api-key: YOUR_API_KEY"

Deleting a Knowledge Base

Deleting a knowledge base removes all its sources and unlinks it from any agents. Dashboard: Open the knowledge base, click the ⋮ menu, then select Delete Knowledge Base. API:

curl -X DELETE https://api.revring.ai/v1/knowledge-bases/{id} \
  -H "x-api-key: YOUR_API_KEY"

Best Practices

Content Quality

Be specific: Focused, well-structured content retrieves better than long, rambling documents
Use clear headings: Documents with clear sections help the retrieval system find relevant passages
Keep content current: Set refreshDays on URL sources, or refresh them after your site changes; replace file and text sources when the underlying content changes
Avoid duplication: Don’t add the same content multiple times across different sources

Prompt Integration

Reference the knowledge base in your agent’s prompt to guide how it uses retrieved information:

You are a customer support agent for Acme Corp.

When customers ask about our products, policies, or procedures,
use the information from your knowledge base to provide accurate answers.
If you can't find the answer in your knowledge base, let the customer know
and offer to transfer them to a specialist.

Do not make up information — only share what you can verify from your knowledge base.

Source Organization

Create separate knowledge bases for different topics (e.g., “Product Catalog”, “Support Policies”, “Pricing”)
Link only the relevant knowledge bases to each agent
Keep source count manageable — a few high-quality sources outperform many low-quality ones

Troubleshooting

Source stuck in processing

Most sources process within a few seconds to a minute; a URL source that reads a whole site can take a few minutes. If a source stays in processing for more than 15 minutes, it may have encountered an issue. Try deleting and re-adding the source. For file sources, ensure the file is not corrupted and is in a supported format.

Source failed to process

Check the errorMessage field on the source for specifics. Common causes include:

URL is unreachable or returns an error
File format is not supported
File is corrupted or empty
Text content is empty

Agent not using knowledge base

Verify the knowledge base is linked to the agent (check the Knowledge tab)
Ensure at least one source is in ready status
Check that retrieval mode is set to automatic (or query_tool if you prefer manual control)
Add guidance in your prompt telling the agent to use its knowledge base
Try increasing the knowledgeBaseChunks value if relevant content is being missed

Agent returning inaccurate information

Review the source content for accuracy
Increase knowledgeBaseSimilarityThreshold to filter out loosely related passages
Decrease knowledgeBaseChunks to reduce noise from less relevant results
Add instructions in your prompt to only use verified knowledge base content

Next Steps

Agent Tools

Configure system and custom tools

API Reference

Manage knowledge bases programmatically

Prompting & Variables

Customize agent behavior with variables

Conversation Flows

Build structured conversation flows

Getting started

Platform

Overview

Creating a Knowledge Base

From the Dashboard

Via API

Adding Sources

Text Sources

URL Sources

Whole websites

Keeping URL sources current

File Sources

Checking Source Status

Linking Knowledge Bases to Agents

From the Dashboard

Via API

Retrieval Settings

Retrieval Mode

Chunks to Retrieve

Similarity Threshold

Configuring via API

Managing Sources

Deleting a Source

Deleting a Knowledge Base

Best Practices

Content Quality

Prompt Integration

Source Organization

Troubleshooting

Next Steps

Agent Tools

API Reference

Prompting & Variables

Conversation Flows

​Overview

​Creating a Knowledge Base

​From the Dashboard

​Via API

​Adding Sources

​Text Sources

​URL Sources

​Whole websites

​Keeping URL sources current

​File Sources

​Checking Source Status

​Linking Knowledge Bases to Agents

​From the Dashboard

​Via API

​Retrieval Settings

​Retrieval Mode

​Chunks to Retrieve

​Similarity Threshold

​Configuring via API

​Managing Sources

​Deleting a Source

​Deleting a Knowledge Base

​Best Practices

​Content Quality

​Prompt Integration

​Source Organization

​Troubleshooting

​Next Steps

Agent Tools

API Reference

Prompting & Variables

Conversation Flows

Overview

Creating a Knowledge Base

From the Dashboard

Via API

Adding Sources

Text Sources

URL Sources

Whole websites

Keeping URL sources current

File Sources

Checking Source Status

Linking Knowledge Bases to Agents

From the Dashboard

Via API

Retrieval Settings

Retrieval Mode

Chunks to Retrieve

Similarity Threshold

Configuring via API

Managing Sources

Deleting a Source

Deleting a Knowledge Base

Best Practices

Content Quality

Prompt Integration

Source Organization

Troubleshooting

Next Steps