Developer Agent and Knowledge Base APIs

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.

Agent & KB Lifecycle

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

{
  "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

{
  "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).
`RegionTypeID`	Integer	Yes	Operating region (from Region Lookup).
`TimeZoneID`	Integer	Yes	Operating timezone (from Timezone Lookup).
`IndustryTypeID`	Integer	Yes	Industry sector (from Industry Lookup).
`LanguageID`	Integer	Yes	Primary language: `1` (English), `2` (Hindi), `3` (Marathi).
`ToneID`	Integer	Yes	Conversational tone (from Agent Tone Lookup).
`IconID`	Integer	Yes	Avatar icon ID (from Icon Lookup).

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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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}

Speech & Agent APIs

Test your agent with live chat queries.

Launch Outbound Campaigns

Deploy this agent in automated calling campaigns.

Getting started

Dashboards

Campaigns

Teams

Agents and knowledge

Reference

Developer Agent and Knowledge Base APIs

Agent & KB Lifecycle

1. Creating & Managing Agents (`/api/v1/external/agent/*`)

1.1 List Workspace Agents

1.2 Create or Update an Agent

Field Explanations:

1.3 Fetch a Single Agent

2. Voice & Model Configuration (`/api/v1/external/agent-config/*`)

2.1 Discover Voice & LLM Models

2.2 Save Runtime Configuration

3. Knowledge Base Setup (`/api/v1/external/kb/*`)

3.1 Create or Update a Knowledge Base

3.2 Clear Vector Embeddings

4. Ingesting Knowledge Data

4.1 Documents (PDF, Excel, Word) - `/api/v1/external/kb-doc/*`

4.2 Frequently Asked Questions (FAQs) - `/api/v1/external/kb-faq/*`

4.3 Business Profile & Hours - `/api/v1/external/kb-business-info/*`

4.4 Product & Service Catalog - `/api/v1/external/kb-catalog/*`

5. Inspecting Conversation Logs (`/api/v1/external/logs/*`)

Speech & Agent APIs

Launch Outbound Campaigns

​Agent & KB Lifecycle

​1. Creating & Managing Agents (/api/v1/external/agent/*)

​1.1 List Workspace Agents

​1.2 Create or Update an Agent

​Field Explanations:

​1.3 Fetch a Single Agent

​2. Voice & Model Configuration (/api/v1/external/agent-config/*)

​2.1 Discover Voice & LLM Models

​2.2 Save Runtime Configuration

​3. Knowledge Base Setup (/api/v1/external/kb/*)

​3.1 Create or Update a Knowledge Base

​3.2 Clear Vector Embeddings

​4. Ingesting Knowledge Data

​4.1 Documents (PDF, Excel, Word) - /api/v1/external/kb-doc/*

​4.2 Frequently Asked Questions (FAQs) - /api/v1/external/kb-faq/*

​4.3 Business Profile & Hours - /api/v1/external/kb-business-info/*

​4.4 Product & Service Catalog - /api/v1/external/kb-catalog/*

​5. Inspecting Conversation Logs (/api/v1/external/logs/*)

Speech & Agent APIs

Launch Outbound Campaigns

Agent & KB Lifecycle

1. Creating & Managing Agents (`/api/v1/external/agent/*`)

1.1 List Workspace Agents

1.2 Create or Update an Agent

Field Explanations:

1.3 Fetch a Single Agent

2. Voice & Model Configuration (`/api/v1/external/agent-config/*`)

2.1 Discover Voice & LLM Models

2.2 Save Runtime Configuration

3. Knowledge Base Setup (`/api/v1/external/kb/*`)

3.1 Create or Update a Knowledge Base

3.2 Clear Vector Embeddings

4. Ingesting Knowledge Data

4.1 Documents (PDF, Excel, Word) - `/api/v1/external/kb-doc/*`

4.2 Frequently Asked Questions (FAQs) - `/api/v1/external/kb-faq/*`

4.3 Business Profile & Hours - `/api/v1/external/kb-business-info/*`

4.4 Product & Service Catalog - `/api/v1/external/kb-catalog/*`

5. Inspecting Conversation Logs (`/api/v1/external/logs/*`)