Skip to main content
Create and manage knowledge bases for retrieval augmented generation (RAG) with your voice agents.
Prerequisites: API key

​
Create a Knowledge Base

Create a knowledge base with documents that your agent can use for RAG. 
import requests

response = requests.post(
    'https://dev.voice.ai/api/v1/knowledge-base/',
    headers={'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json'},
    json={
        'name': 'Product Information',
        'description': 'FAQ and product details',
        'documents': [
            {
                'content': 'Our product supports voice cloning, text-to-speech, and real-time conversations.',
                'metadata': {'source': 'product-docs.md', 'category': 'features'}
            },
            {
                'content': 'Pricing starts at $0.01 per minute for voice calls.',
                'metadata': {'source': 'pricing.md', 'category': 'pricing'}
            }
        ]
    }
)

kb_id = response.json()['kb_id']
print(f'Created knowledge base: {kb_id}')
Response: 
{
  "kb_id": 123,
  "user_id": "user_abc123",
  "name": "Product Information",
  "description": "FAQ and product details",
  "document_count": 2,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

​
List Knowledge Bases

Get all your knowledge bases with pagination support. 
import requests

response = requests.get(
    'https://dev.voice.ai/api/v1/knowledge-base/',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    params={'page': 1, 'page_size': 10}
)

data = response.json()
for kb in data['knowledge_bases']:
    print(f"{kb['name']} ({kb['document_count']} documents) - ID: {kb['kb_id']}")

​
Get Knowledge Base Details

Retrieve details for a specific knowledge base, including all documents. 
import requests

response = requests.get(
    f'https://dev.voice.ai/api/v1/knowledge-base/{kb_id}',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)

kb = response.json()
print(f"Name: {kb['name']}")
print(f"Documents: {kb['document_count']}")

​
Update a Knowledge Base

Update the name, description, or add new documents to an existing knowledge base. 
import requests

response = requests.put(
    f'https://dev.voice.ai/api/v1/knowledge-base/{kb_id}',
    headers={'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json'},
    json={
        'name': 'Updated Product Information',
        'description': 'Updated FAQ and product details',
        'documents': [
            {
                'content': 'New feature: Real-time voice cloning is now available.',
                'metadata': {'source': 'changelog.md'}
            }
        ]
    }
)

print(f"Updated: {response.json()['name']}")

​
Assign Knowledge Base to Agent

Assign an existing knowledge base to an agent for RAG capabilities. 
import requests

response = requests.post(
    f'https://dev.voice.ai/api/v1/agent/{agent_id}/assign-knowledge-base',
    headers={'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json'},
    json={'kb_id': kb_id}
)

agent = response.json()
print(f"Agent {agent['agent_id']} now uses knowledge base {agent['kb_id']}")

​
Create Agent with Knowledge Base

You can also create an agent with a knowledge base directly, or create a new knowledge base during agent creation. 
import requests

# Option 1: Assign existing knowledge base
response = requests.post(
    'https://dev.voice.ai/api/v1/agent/',
    headers={'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json'},
    json={
        'name': 'Support Agent',
        'config': {'prompt': 'You are a helpful support agent.'},
        'kb_id': kb_id
    }
)

# Option 2: Create new knowledge base during agent creation
response = requests.post(
    'https://dev.voice.ai/api/v1/agent/',
    headers={'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json'},
    json={
        'name': 'Support Agent',
        'config': {'prompt': 'You are a helpful support agent.'},
        'documents': [
            {'content': 'Return policy: 30-day returns accepted.', 'metadata': {'source': 'policy.md'}}
        ]
    }
)

​
Remove Knowledge Base from Agent

Unassign a knowledge base from an agent. 
import requests

requests.delete(
    f'https://dev.voice.ai/api/v1/agent/{agent_id}/knowledge-base',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)

print('Knowledge base removed from agent')

​
Delete a Knowledge Base

Permanently delete a knowledge base. Note: You must unassign it from all agents first. 
import requests

requests.delete(
    f'https://dev.voice.ai/api/v1/knowledge-base/{kb_id}',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)

print('Knowledge base deleted')

​
Best Practices

  • Document Structure: Use clear, concise content with relevant metadata for better retrieval
  • Knowledge Base Reuse: The API automatically detects and reuses knowledge bases with identical content
  • Agent Assignment: One knowledge base can be shared across multiple agents
  • Updates: Adding documents to a knowledge base automatically rebuilds the index

​
Next Steps