Developer Overview & Architecture

Welcome to the Valuez AI Developer Guide. This documentation is designed for software engineers, backend developers, and system integrators who want to build on the Valuez AI platform. Whether you are automating outbound voice campaigns, embedding AI voice agents into your product, synthesizing speech, or programmatically managing knowledge bases, this guide covers everything from foundational concepts to production API integration.

1. What is Valuez AI?

Valuez AI is an enterprise-grade voice and conversational automation platform. At a high level, the platform combines four core capabilities:

┌────────────────────────────────────────────────────────────────────────┐
│                              VALUEZ AI PLATFORM                        │
├───────────────────┬───────────────────┬────────────────┬───────────────┤
│    1. AI AGENTS   │ 2. KNOWLEDGE BASE │ 3. TELEPHONY   │ 4. OPERATIONS │
│                   │      (RAG)        │   & CAMPAIGNS  │  & ANALYTICS  │
├───────────────────┼───────────────────┼────────────────┼───────────────┤
│ • Prompts & Tone  │ • Documents (PDF) │ • Exotel IVR   │ • Call Logs   │
│ • LLM Brain       │ • Business Info   │ • Outbound Auto│ • Lead Scores │
│ • Voice (TTS)     │ • FAQs & Q&A      │   Dialer       │ • Token Usage │
│ • Speech (STT)    │ • Catalogs        │ • Virtual Nos  │ • Analytics   │
└───────────────────┴───────────────────┴────────────────┴───────────────┘

AI Voice Agents: Autonomous conversational agents configured with specific roles, languages (English, Hindi, Marathi), custom instructions, LLM backends, voices, and interruption handling.
Knowledge Base (RAG): Retrieval-Augmented Generation powered by Qdrant vector search. Agents answer customer questions using your uploaded documents, FAQs, business details, and product catalogs.
Telephony & Campaigns: Integration with Exotel to dial real phone numbers, run scheduled outbound calling batches, detect voicemails, and transfer calls to human agents.
Operations & Analytics: Comprehensive logging of call recordings, transcriptions, conversation turns, lead qualification, and API credit accounting.

2. Developer Integration Paths

There are two primary ways you will interact with Valuez AI via APIs:

Path	Primary Endpoints	Authentication	Use Cases
Direct Integration APIs	`/api/v1/ttt` `/api/v1/tts/external` `/api/v1/stt/external` `/api/v1/external/chat`	Header: `x-api-key`	Embed AI chat in your mobile/web app, run TTS speech generation, or transcribe audio files.
Workspace Management APIs	`/api/v1/external/agent/` `/api/v1/external/kb/` `/api/v1/external/campaign/` `/api/v1/external/team-management/`	Header: `x-api-key`	Programmatically create agents, upload KB documents, trigger outbound calling campaigns, and query dashboards.

Production Base URL: https://api.dashboard.valuez.ai All API paths in this guide are relative to the production base URL above.

3. Postman Collection Quickstart

Your workspace admin will share the Valuez External Developer API Postman Collection and ValuezAI_REST_API environment with you. Once imported, you can test every endpoint without writing any code first.

Setting Up Postman in 3 Steps:

Import Collection & Environment

In Postman, click Import and load the two JSON files shared by your admin:

Postman Collection: Valuez External Developer API
Postman Environment: ValuezAI_REST_API

Configure Environment Variables

Select the ValuezAI_REST_API environment from the top-right dropdown in Postman, then set the two required variables:

Variable	Description	Value
`BaseURL`	Production API host	`https://api.dashboard.valuez.ai`
`APIKey`	API key provided by your workspace admin	`valuezai_api_12_a8f3b2c...`

Send Your First Request

Open any endpoint in the collection and click Send. The collection automatically attaches your x-api-key header on every request — no manual header setup needed.

Auth Inheritance in Postman: All endpoints in the collection inherit the x-api-key authentication configured at the root level. You never have to add the header manually to individual requests.

4. Key Architectural Concepts & Conventions

Before making API calls, understand these four conventions used throughout the platform:

1. Dual ID System (UUIDs vs Integers)

To ensure secure multi-tenancy and high database performance, Valuez uses two identifier types:

KeyID (UUID string): Public, non-sequential identifiers used in URL paths and external references (e.g., AgentKeyID, KBKeyID, CampaignKeyID, LeadKeyID).
ID (Integer): Internal relational foreign keys (e.g., AgentID, KBID, AdminID).
Rule for Creates: When creating a new entity, pass null for the KeyID (e.g., "CampaignKeyID": null). The server generates a new UUID and returns it in the response.

2. Lookup Dependencies (Lookups First!)

Valuez uses relational master tables for fields like AgentTypeID, IndustryTypeID, RegionTypeID, LanguageID, and StopRuleID.

You cannot pass arbitrary numbers for these fields.
Always call the corresponding lookup endpoint first to obtain the valid ID for your workspace. See Lookups Reference.

3. Standard Pagination Format

All list endpoints use this standard POST body structure:

{
  "search": "",
  "pageNo": 1,
  "pageSize": 10,
  "sortColumn": "CreatedOn",
  "sortOrder": "DESC"
}

4. File Uploads

Document attachments (PDFs, Excel files) and audio files use multipart/form-data:

KB Documents: field name document
Contacts CSV: field name file
STT Audio: field name audioFile

5. End-to-End Developer Lifecycle

Follow this step-by-step roadmap to build your integration in the correct order:

Step 1: Authenticate

Learn how API keys are generated and used in API Authentication.

Step 2: Resolve Lookup Values

Fetch available master IDs (industries, languages, voices, regions) in Lookups.

Step 3: Create & Ground Agents

Build the agent persona and upload knowledge documents via Agents and Knowledge.

Step 4: Integrate Chat & Speech

Embed real-time text-to-text, TTS, and STT in your app using Speech & Agent APIs.

Step 5: Run Outbound Campaigns

Import contact lists and trigger auto-dialer batches in Campaigns.

Step 6: Monitor Performance

Track real-time call gauges and campaign outcomes via Developer Dashboard.

6. Where to Go Next

Authentication

Generate your API key and configure headers.

Speech & Agent APIs

Direct TTT, TTS, STT, and Chat endpoints.

Agents & Knowledge

Create agents, upload PDFs, and manage FAQs.

Campaign APIs

Schedule outbound calls, import CSVs, and inspect logs.

Lookups Reference

Find all lookup endpoints for dropdown IDs.

Dashboard APIs

Query live call counts and campaign metrics.

Getting started

Dashboards

Campaigns

Teams

Agents and knowledge

Reference

Developer Overview & Architecture

1. What is Valuez AI?

2. Developer Integration Paths

3. Postman Collection Quickstart

Setting Up Postman in 3 Steps:

4. Key Architectural Concepts & Conventions

1. Dual ID System (UUIDs vs Integers)

2. Lookup Dependencies (Lookups First!)

4. File Uploads

5. End-to-End Developer Lifecycle

6. Where to Go Next

Authentication

Speech & Agent APIs

Agents & Knowledge

Campaign APIs

Lookups Reference

Dashboard APIs

​1. What is Valuez AI?

​2. Developer Integration Paths

​3. Postman Collection Quickstart

​Setting Up Postman in 3 Steps:

​4. Key Architectural Concepts & Conventions

​1. Dual ID System (UUIDs vs Integers)

​2. Lookup Dependencies (Lookups First!)

​3. Standard Pagination Format

​4. File Uploads

​5. End-to-End Developer Lifecycle

​6. Where to Go Next

Authentication

Speech & Agent APIs

Agents & Knowledge

Campaign APIs

Lookups Reference

Dashboard APIs

1. What is Valuez AI?

2. Developer Integration Paths

3. Postman Collection Quickstart

Setting Up Postman in 3 Steps:

4. Key Architectural Concepts & Conventions

1. Dual ID System (UUIDs vs Integers)

2. Lookup Dependencies (Lookups First!)

3. Standard Pagination Format

4. File Uploads

5. End-to-End Developer Lifecycle

6. Where to Go Next