Custom knowledge base

Overview

Custom Knowledge Bases allow you to implement your own document retrieval server, giving you complete control over how your assistant searches and retrieves information. Instead of relying on Vapi’s built-in knowledge base providers, you can integrate your own search infrastructure, vector databases, or custom retrieval logic.

With Custom Knowledge Bases, you can:

Use your own vector database or search infrastructure
Implement custom retrieval algorithms and scoring
Integrate with existing document management systems
Apply custom business logic to document filtering
Maintain full control over data security and privacy

How Custom Knowledge Bases Work

Custom Knowledge Bases operate through a webhook-style integration where Vapi forwards search requests to your server and expects structured responses containing relevant documents.

User Query

User asks assistant a question during conversation

Search Request

Vapi sends search request to your custom endpoint

Document Response

Your server returns relevant documents or direct response

Creating a Custom Knowledge Base

Step 1: Create the Knowledge Base

Use the Vapi API to create a custom knowledge base configuration:

curl --location 'https://api.vapi.ai/knowledge-base' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_VAPI_API_KEY' \
--data '{
    "provider": "custom-knowledge-base",
    "server": {
        "url": "https://your-domain.com/kb/search",
        "secret": "your-webhook-secret"
    }
}'

Step 2: Attach to Your Assistant

Custom knowledge bases can only be attached to assistants via the API. This functionality is not available through the dashboard interface.

To attach a custom knowledge base to your assistant, update the assistant’s model configuration. You must provide the complete model configuration including all existing messages, as partial patches are not supported for nested objects:

curl --location --request PATCH 'https://api.vapi.ai/assistant/YOUR_ASSISTANT_ID' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_VAPI_API_KEY' \
--data '{
    "model": {
        "model": "gpt-4o",
        "provider": "openai",
        "messages": [
            {
                "role": "system",
                "content": "Your existing system prompt and instructions..."
            }
        ],
        "knowledgeBaseId": "YOUR_KNOWLEDGE_BASE_ID"
    }
}'

When updating an assistant’s model, you must include the complete model object including all existing messages and configuration. The API replaces the entire model object and doesn’t support partial updates for nested objects.

Next Steps

Now that you have a custom knowledge base implementation:

Implement the custom endpoint: Handle the retrieval request and return results from your server
Query tool configuration: Learn advanced Query tool configurations
Assistant Configuration: Optimize your assistant’s use of knowledge bases

Custom Knowledge Bases require a webhook endpoint that’s publicly accessible. For production deployments, ensure your server can handle concurrent requests and has appropriate error handling and monitoring in place.