> ## 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 Overview & Architecture

> The complete guide to understanding, integrating, and developing with Valuez AI

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   │
└───────────────────┴───────────────────┴────────────────┴───────────────┘
```

1. **AI Voice Agents**: Autonomous conversational agents configured with specific roles, languages (English, Hindi, Marathi), custom instructions, LLM backends, voices, and interruption handling.
2. **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.
3. **Telephony & Campaigns**: Integration with Exotel to dial real phone numbers, run scheduled outbound calling batches, detect voicemails, and transfer calls to human agents.
4. **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`<br />`/api/v1/tts/external`<br />`/api/v1/stt/external`<br />`/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/*`<br />`/api/v1/external/kb/*`<br />`/api/v1/external/campaign/*`<br />`/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:

<Steps>
  <Step title="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`
  </Step>

  <Step title="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...` |
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Tip>
  **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.
</Tip>

***

## 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](/dev-lookups).

### 3. Standard Pagination Format

All list endpoints use this standard POST body structure:

```json theme={null}
{
  "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:

```mermaid theme={null}
graph TD
    A[1. Get API Key from Dashboard] --> B[2. Query Lookups: Regions, Languages, Industries]
    B --> C[3. Create AI Agent: Name, Prompts, Greetings]
    C --> D[4. Configure Voice & STT: LLM, Voice Model, Interruption]
    D --> E[5. Create Knowledge Base & Upload Documents/FAQs]
    E --> F[6. Test Conversations via TTT or Chat API]
    F --> G[7. Map Contacts & Launch Outbound Campaign]
    G --> H[8. Review Dashboards, Call Logs & Lead Analytics]
```

<Steps>
  <Step title="Step 1: Authenticate">
    Learn how API keys are generated and used in [API Authentication](/dev-authentication).
  </Step>

  <Step title="Step 2: Resolve Lookup Values">
    Fetch available master IDs (industries, languages, voices, regions) in [Lookups](/dev-lookups).
  </Step>

  <Step title="Step 3: Create & Ground Agents">
    Build the agent persona and upload knowledge documents via [Agents and Knowledge](/dev-agents-knowledge).
  </Step>

  <Step title="Step 4: Integrate Chat & Speech">
    Embed real-time text-to-text, TTS, and STT in your app using [Speech & Agent APIs](/dev-integration-apis).
  </Step>

  <Step title="Step 5: Run Outbound Campaigns">
    Import contact lists and trigger auto-dialer batches in [Campaigns](/dev-campaigns).
  </Step>

  <Step title="Step 6: Monitor Performance">
    Track real-time call gauges and campaign outcomes via [Developer Dashboard](/dev-dashboard).
  </Step>
</Steps>

***

## 6. Where to Go Next

<CardGroup cols={3}>
  <Card title="Authentication" icon="key" href="/dev-authentication">
    Generate your API key and configure headers.
  </Card>

  <Card title="Speech & Agent APIs" icon="sparkles" href="/dev-integration-apis">
    Direct TTT, TTS, STT, and Chat endpoints.
  </Card>

  <Card title="Agents & Knowledge" icon="brain" href="/dev-agents-knowledge">
    Create agents, upload PDFs, and manage FAQs.
  </Card>

  <Card title="Campaign APIs" icon="phone" href="/dev-campaigns">
    Schedule outbound calls, import CSVs, and inspect logs.
  </Card>

  <Card title="Lookups Reference" icon="list" href="/dev-lookups">
    Find all lookup endpoints for dropdown IDs.
  </Card>

  <Card title="Dashboard APIs" icon="chart-line" href="/dev-dashboard">
    Query live call counts and campaign metrics.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.