Knowledge Base & RAG - Voice Agent API - Voice AI Developer Docs

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. See the Create Knowledge Base endpoint for details.

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}')

curl -X POST "https://dev.voice.ai/api/v1/knowledge-base/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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"}
      }
    ]
  }'

const response = await fetch('https://dev.voice.ai/api/v1/knowledge-base/', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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' }
      }
    ]
  })
});

const data = await response.json();
console.log(`Created knowledge base: ${data.kb_id}`);

Response:

{
  "kb_id": 123,
  "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. See the Knowledge Base List endpoint for details.

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']}")

curl -X GET "https://dev.voice.ai/api/v1/knowledge-base/?page=1&page_size=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('https://dev.voice.ai/api/v1/knowledge-base/?page=1&page_size=10', {
  method: 'GET',
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});

const data = await response.json();
data.knowledge_bases.forEach((kb: any) => {
  console.log(`${kb.name} (${kb.document_count} documents) - ID: ${kb.kb_id}`);
});

Get Knowledge Base Details

Retrieve details for a specific knowledge base, including all documents. See the Knowledge Base Details endpoint for details.

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']}")

curl -X GET "https://dev.voice.ai/api/v1/knowledge-base/{kb_id}" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(`https://dev.voice.ai/api/v1/knowledge-base/${kbId}`, {
  method: 'GET',
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});

const kb = await response.json();
console.log(`Name: ${kb.name}`);
console.log(`Documents: ${kb.document_count}`);

Update a Knowledge Base

Update the name, description, or replace all documents in an existing knowledge base. Note: If you provide documents, they will replace ALL existing documents in the knowledge base. See the Update Knowledge Base endpoint for details.

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']}")

curl -X PUT "https://dev.voice.ai/api/v1/knowledge-base/{kb_id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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"}
      }
    ]
  }'

const response = await fetch(`https://dev.voice.ai/api/v1/knowledge-base/${kbId}`, {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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' }
      }
    ]
  })
});

const data = await response.json();
console.log(`Updated: ${data.name}`);

Assign Knowledge Base to Agent

Assign an existing knowledge base to an agent for RAG capabilities. See the Assign Knowledge Base endpoint for details.

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']}")

curl -X POST "https://dev.voice.ai/api/v1/agent/{agent_id}/assign-knowledge-base" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kb_id": 123
  }'

const response = await fetch(`https://dev.voice.ai/api/v1/agent/${agentId}/assign-knowledge-base`, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ kb_id: kbId })
});

const agent = await response.json();
console.log(`Agent ${agent.agent_id} now uses knowledge base ${agent.kb_id}`);

Create Agent with Knowledge Base

You can create an agent and assign an existing knowledge base during agent creation.

import requests

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
    }
)

agent = response.json()
print(f"Created agent {agent['agent_id']} with knowledge base {agent['kb_id']}")

curl -X POST "https://dev.voice.ai/api/v1/agent/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Agent",
    "config": {"prompt": "You are a helpful support agent."},
    "kb_id": 123
  }'

const response = await fetch('https://dev.voice.ai/api/v1/agent/', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Support Agent',
    config: { prompt: 'You are a helpful support agent.' },
    kb_id: kbId
  })
});

const agent = await response.json();
console.log(`Created agent ${agent.agent_id} with knowledge base ${agent.kb_id}`);

Remove Knowledge Base from Agent

Unassign a knowledge base from an agent. See the Unassign Knowledge Base endpoint for details.

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')

curl -X DELETE "https://dev.voice.ai/api/v1/agent/{agent_id}/knowledge-base" \
  -H "Authorization: Bearer YOUR_API_KEY"

await fetch(`https://dev.voice.ai/api/v1/agent/${agentId}/knowledge-base`, {
  method: 'DELETE',
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});

console.log('Knowledge base removed from agent');

Delete a Knowledge Base

Permanently delete a knowledge base. Note: You must unassign it from all agents first. See the Delete Knowledge Base endpoint for details.

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')

curl -X DELETE "https://dev.voice.ai/api/v1/knowledge-base/{kb_id}" \
  -H "Authorization: Bearer YOUR_API_KEY"

await fetch(`https://dev.voice.ai/api/v1/knowledge-base/${kbId}`, {
  method: 'DELETE',
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});

console.log('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: When updating documents, provide the complete set of documents you want in the knowledge base, as updates replace all existing documents

Next Steps

Agent Quickstart - Create your first agent
API Reference - Complete API reference

Get started

Text-to-Speech

Voice Agents

SDKs

Knowledge Base & RAG - Voice Agent API

Create a Knowledge Base

List Knowledge Bases

Get Knowledge Base Details

Update a Knowledge Base

Assign Knowledge Base to Agent

Create Agent with Knowledge Base

Remove Knowledge Base from Agent

Delete a Knowledge Base

Best Practices

Next Steps

​Create a Knowledge Base

​List Knowledge Bases

​Get Knowledge Base Details

​Update a Knowledge Base

​Assign Knowledge Base to Agent

​Create Agent with Knowledge Base

​Remove Knowledge Base from Agent

​Delete a Knowledge Base

​Best Practices

​Next Steps

Create a Knowledge Base

List Knowledge Bases

Get Knowledge Base Details

Update a Knowledge Base

Assign Knowledge Base to Agent

Create Agent with Knowledge Base

Remove Knowledge Base from Agent

Delete a Knowledge Base

Best Practices

Next Steps