> ## Documentation Index > Fetch the complete documentation index at: https://docs.valuez.ai/llms.txt > Use this file to discover all available pages before exploring further. # Developer Agent and Knowledge Base APIs > Complete lifecycle guide for creating agents, voice profiles, knowledge bases, and RAG data This guide walks you through programmatically building and training AI Voice Agents. An **Agent** represents the conversational persona (its name, role, prompts, language, and voice model). A **Knowledge Base (KB)** contains the business ground truth (documents, FAQs, catalog, business profile) stored in a Qdrant vector database that the agent references during customer conversations. **Production Base URL**: `https://api.dashboard.valuez.ai` All requests require the `x-api-key` header containing the API key provided by your workspace admin. See [API Authentication](/dev-authentication). *** ## Agent & KB Lifecycle ```mermaid theme={null} graph LR Step1[1. Create Agent Base] --> Step2[2. Configure Voice & Models] Step2 --> Step3[3. Create Knowledge Base] Step3 --> Step4[4. Ingest Documents, FAQs & Catalog] ``` ## 1. Creating & Managing Agents (`/api/v1/external/agent/*`) ### 1.1 List Workspace Agents Fetch all existing agents with pagination and sorting. * **Endpoint**: `POST /api/v1/external/agent/agent-list` ```json theme={null} { "searchName": "", "pageNo": 1, "pageSize": 10, "sortColumn": "CreatedOn", "sortOrder": "DESC" } ``` ### 1.2 Create or Update an Agent Creates a new AI agent or updates an existing one. * **Endpoint**: `POST /api/v1/external/agent/add-update-agent` ```json theme={null} { "AgentKeyID": null, "TemplateID": 0, "AgentName": "Customer Support Assistant", "AgentDescription": "Support assistant handling warranty queries, business hours, and order tracking.", "AgentTypeID": 1, "RegionTypeID": 1, "TimeZoneID": 1, "IndustryTypeID": 1, "LanguageID": 1, "ToneID": 1, "IconID": 5, "AdminID": 1 } ``` #### Field Explanations: | Field | Type | Required | Description | | - | - | - | - | | `AgentKeyID` | UUID string | No | Pass `null` to create a new agent. To update, pass the existing `AgentKeyID`. | | `TemplateID` | Integer | Yes | Pass `0` to build from scratch. Pass a positive integer to inherit from a pre-built template. | | `AgentName` | String | Yes | Name of the agent (max 30 characters). | | `AgentDescription` | String | Yes | Detailed persona instructions and role boundaries (10–1200 characters). | | `AgentTypeID` | Integer | Yes | Type of agent (from [Agent Type Lookup](/dev-lookups)). | | `RegionTypeID` | Integer | Yes | Operating region (from [Region Lookup](/dev-lookups)). | | `TimeZoneID` | Integer | Yes | Operating timezone (from [Timezone Lookup](/dev-lookups)). | | `IndustryTypeID` | Integer | Yes | Industry sector (from [Industry Lookup](/dev-lookups)). | | `LanguageID` | Integer | Yes | Primary language: `1` (English), `2` (Hindi), `3` (Marathi). | | `ToneID` | Integer | Yes | Conversational tone (from [Agent Tone Lookup](/dev-lookups)). | | `IconID` | Integer | Yes | Avatar icon ID (from [Icon Lookup](/dev-lookups)). | ### 1.3 Fetch a Single Agent * **Endpoint**: `GET /api/v1/external/agent/get-agent?AgentKeyID={AgentKeyID}` * Returns full agent metadata, system prompt, greetings, and associated KB ID. *** ## 2. Voice & Model Configuration (`/api/v1/external/agent-config/*`) Once an agent is created, configure its runtime engines: Speech-to-Text (STT), Large Language Model (LLM), and Text-to-Speech (TTS). ### 2.1 Discover Voice & LLM Models Before setting configuration, query the available models for your tenant: * `GET /api/v1/external/agent-config/llm-provider-list` - Foundation LLM providers (Sarvam, OpenAI, etc.). * `GET /api/v1/external/agent-config/voice-provider-list` - TTS engines. * `GET /api/v1/external/agent-config/voice-model-list?voiceProviderID=12` - Specific voices available for a provider. * `GET /api/v1/external/agent-config/transcribe-model-list?transcribeProviderID=8` - STT models. * `GET /api/v1/external/agent-config/demo-voice?voiceID=1&voiceProviderID=12&speed=1.00` - Audio preview stream. ### 2.2 Save Runtime Configuration * **Endpoint**: `POST /api/v1/external/agent-config/insert-agent-config` ```json theme={null} { "AgentID": 17, "TranscribeID": 96537, "TranscribeProviderID": 9, "IsAllowInteruption": 1, "IsBackgroundNoiceFilter": 1, "BackgroundNoiceFilterCount": 60, "IsEnableDTMF": 0 } ``` | Field | Type | Description | | - | - | - | | `AgentID` | Integer | Internal integer ID of the agent. | | `TranscribeID` | Integer | Selected speech transcription model. | | `TranscribeProviderID` | Integer | STT provider identifier. | | `IsAllowInteruption` | Boolean (`0` or `1`) | Whether caller can interrupt the agent while speaking. | | `IsBackgroundNoiceFilter` | Boolean (`0` or `1`) | Enable acoustic noise dampening. | | `BackgroundNoiceFilterCount` | Integer (`0`–`100`) | Filter sensitivity threshold (recommended: `60`). | | `IsEnableDTMF` | Boolean (`0` or `1`) | Allow telephone keypad touch-tone input during calls. | *** ## 3. Knowledge Base Setup (`/api/v1/external/kb/*`) A Knowledge Base (KB) powers the Retrieval-Augmented Generation (RAG) system. Every agent links to a KB ID. ### 3.1 Create or Update a Knowledge Base * **Endpoint**: `POST /api/v1/external/kb/add-update-kb` ```json theme={null} { "KBKeyID": null, "KnowledgeBaseName": "IT Sales Assistant KB", "IndustryID": 1, "AgentTypeID": 1, "ConversationalModeIDs": "1,2" } ``` * When creating, pass `"KBKeyID": null`. The response returns the newly created `KBKeyID` and internal `KBID`. * `ConversationalModeIDs`: String of comma-separated modes (`1` = Voice, `2` = Chat). ### 3.2 Clear Vector Embeddings * **Endpoint**: `POST /api/v1/external/kb/clear-qdrant` * Destructively wipes vector embeddings in Qdrant for a collection (e.g., `kb_embeddings_{OrgID}_{KBID}`). Used during full re-indexing. *** ## 4. Ingesting Knowledge Data A Knowledge Base can ingest four types of data: ### 4.1 Documents (PDF, Excel, Word) - `/api/v1/external/kb-doc/*` Upload company policies, product sheets, or manuals. The backend chunks the document, generates embeddings, and indexes them in Qdrant. * **Endpoint**: `POST /api/v1/external/kb-doc/add-update` * **Content-Type**: `multipart/form-data` | Form Field | Type | Description | | - | - | - | | `document` | File | The binary file (`.pdf`, `.xlsx`, `.csv`, max 10 MB). | | `KBID` | Text | The integer ID of the Knowledge Base. | | `KBDocumentKeyID` | Text | Empty string for new upload; UUID for updates. | ### 4.2 Frequently Asked Questions (FAQs) - `/api/v1/external/kb-faq/*` Direct Q\&A pairs provide deterministic, high-confidence answers for common caller inquiries. * **Endpoint**: `POST /api/v1/external/kb-faq/add-update-faq` ```json theme={null} { "KBID": 17, "faqs": [ { "KBFAQID": 0, "Question": "What is your refund policy?", "Answer": "We offer full refunds within 14 days of purchase upon return receipt." }, { "KBFAQID": 0, "Question": "Do you offer emergency technical support?", "Answer": "Yes, 24/7 emergency support is available for Platinum enterprise plans." } ] } ``` *(Pass `KBFAQID: 0` for new questions; pass existing integer ID to edit).* ### 4.3 Business Profile & Hours - `/api/v1/external/kb-business-info/*` Gives the agent foundational facts about your business, office addresses, and operating hours. * **Endpoint**: `POST /api/v1/external/kb-business-info/add-update` ```json theme={null} { "KBID": 17, "businessInfo": { "business_name": "Valuez AI Technologies", "business_type": "Corporate", "industry": "Artificial Intelligence", "company_description": "Enterprise voice automation provider.", "website_url": "https://valuez.ai", "support_email": "support@valuez.ai", "support_phone": "+919876543210", "office_address": "Mumbai, Maharashtra, India", "working_hours": [ { "day": "Monday", "open_time": "09:00 AM", "close_time": "06:00 PM", "is_open": true }, { "day": "Tuesday", "open_time": "09:00 AM", "close_time": "06:00 PM", "is_open": true }, { "day": "Wednesday", "open_time": "09:00 AM", "close_time": "06:00 PM", "is_open": true }, { "day": "Thursday", "open_time": "09:00 AM", "close_time": "06:00 PM", "is_open": true }, { "day": "Friday", "open_time": "09:00 AM", "close_time": "06:00 PM", "is_open": true }, { "day": "Saturday", "open_time": "10:00 AM", "close_time": "02:00 PM", "is_open": true }, { "day": "Sunday", "open_time": "12:00 AM", "close_time": "12:00 AM", "is_open": false } ], "timezone": "Asia/Kolkata", "KBBusinessInfoID": 0 } } ``` ### 4.4 Product & Service Catalog - `/api/v1/external/kb-catalog/*` Allows agents to quote prices, check inventory availability, and explain service terms. * **Endpoint**: `POST /api/v1/external/kb-catalog/add-update` ```json theme={null} { "KBID": 17, "products": [ { "product_id": null, "product_name": "Enterprise VoIP Gateway", "product_description": "Hardware bridge for Asterisk SIP trunks.", "category": "Hardware", "price": 299.00, "currency": "USD", "availability": true, "sku": "VOIP-GW-100", "warranty": 2 } ], "services": [ { "service_id": null, "service_name": "Telephony Onboarding Consulting", "service_description": "Dedicated SIP trunk configuration assistance.", "service_duration": 1.0, "service_price": 150.00, "service_price_range": "150 to 250", "currency": "USD", "booking_required": true, "service_area": ["Remote"] } ] } ``` *** ## 5. Inspecting Conversation Logs (`/api/v1/external/logs/*`) Track conversations handled by your agents: * **List Logs**: `POST /api/v1/external/logs/conversational-log-list` ```json theme={null} { "pageSize": 10, "pageNo": 1, "search": "", "startDate": null, "endDate": null, "sortColumn": "CreatedOn", "sortOrder": "DESC" } ``` * **Get Transcript Detail**: `GET /api/v1/external/logs/get-conversational-log?ConversationalLogKeyID={uuid}` Test your agent with live chat queries. Deploy this agent in automated calling campaigns. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.