Documentation

Build intelligent Q&A systems powered by your own documents and knowledge bases.

Quick Start

Get up and running in less than 5 minutes. Create a knowledge base, upload documents, and start querying.

1

Get Your API Key

Sign up at the dashboard and generate your API key from the settings page

2

Create a Knowledge Base

Create an isolated knowledge base for your use case (support, documentation, training, etc.)

POST /knowledge-bases
3

Upload Documents

Upload PDF, DOCX, or TXT files - content is automatically extracted

POST /documents
4

Query Your Knowledge Base

Use semantic search to find relevant answers with AI avatar responses

POST /query?knowledge_base_id=YOUR_KB_ID
// Step 1: Create a knowledge base
const response = await fetch('API_BASE_URL/knowledge-bases', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: "Product Documentation",
    description: "All product manuals and guides",
    language: "ar" // or "en"
  })
});

const kb = await response.json();

// Step 2: Upload a document
const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('knowledge_base_id', kb.id);

await fetch('API_BASE_URL/documents', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY'
  },
  body: formData
});

// Step 3: Generate Q&A pairs automatically
const qaGeneration = await fetch(
  `API_BASE_URL/qa-pairs/generate-from-text?knowledge_base_id=${kb.id}`,
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      text: "Your document text or content...",
      run_audit: true
    })
  }
);

// Step 4: Query the knowledge base
const queryResponse = await fetch(
  `API_BASE_URL/query?knowledge_base_id=${kb.id}`,
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      query: "ما هي متطلبات التثبيت؟",
      top_k: 5,
      include_video: true
    })
  }
);

const result = await queryResponse.json();
console.log('Answer:', result.answer);
console.log('Confidence:', result.confidence);
console.log('Sources:', result.sources);

Knowledge Base Setup

Build custom knowledge bases from your documents, then let AI automatically generate Q&A pairs and enable semantic search for intelligent query responses.

Core Workflow

1. Create Knowledge Base

Create isolated knowledge bases for different use cases (customer support, product docs, training materials)

2. Upload Documents

Upload PDF, DOCX, or TXT files - text content is automatically extracted and processed

3. Generate Q&A Pairs

AI automatically generates question-answer pairs from your documents using advanced NLP

4. Sync to Vector Database

Q&A pairs are embedded and stored in a vector database using OpenAI embeddings for semantic search

Supported Document Formats

PDF Documents

PDF files with text content

Word Documents

DOCX format files

Text Files

Plain TXT files

// Create knowledge base
const kb = await fetch('API_BASE_URL/knowledge-bases', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: "Product Support KB",
    description: "Customer support knowledge base",
    language: "ar"  // or "en" for English
  })
}).then(r => r.json());

// Upload document
const formData = new FormData();
formData.append('file', document.querySelector('input[type="file"]').files[0]);
formData.append('knowledge_base_id', kb.id);

const doc = await fetch('API_BASE_URL/documents', {
  method: 'POST',
  headers: { 'X-API-Key': 'YOUR_API_KEY' },
  body: formData
}).then(r => r.json());

// Process document to generate Q&A pairs
const workflow = await fetch(`API_BASE_URL/qa-generation/process-document/${doc.id}`, {
  method: 'POST',
  headers: { 'X-API-Key': 'YOUR_API_KEY' }
}).then(r => r.json());

// Check workflow status
const status = await fetch(`API_BASE_URL/workflows/${workflow.workflow_id}/status`, {
  headers: { 'X-API-Key': 'YOUR_API_KEY' }
}).then(r => r.json());

console.log('Q&A Generation Status:', status.status);

Querying Your Knowledge Base

Use semantic search and intent detection to provide intelligent responses to user queries.

How Query Processing Works

1
User submits a query in Arabic or English
2
Intent detection classifies the query type (greeting, question, farewell, etc.)
3
Vector search finds the most relevant Q&A pairs using embeddings
4
AI avatar generates a response based on the retrieved content
5
Response includes answer, confidence score, and optional video

Query Parameters

query

The user's question or search text (supports Arabic and English)

top_k

Number of relevant results to retrieve (default: 5, recommended: 3-10)

include_video

Include avatar video response in the result (default: false)

// Query the knowledge base
const response = await fetch('API_BASE_URL/query?knowledge_base_id=YOUR_KB_ID', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: "ما هي ساعات العمل؟",  // What are the working hours?
    top_k: 5,
    include_video: true
  })
});

const result = await response.json();

console.log('Answer:', result.answer);
console.log('Confidence:', result.confidence);  // 0.0 to 1.0
console.log('Sources:', result.sources);        // Related Q&A pairs
console.log('Video URL:', result.video_url);    // Avatar response video

// Response structure:
{
  "answer": "ساعات العمل من 9 صباحاً إلى 5 مساءً",
  "confidence": 0.92,
  "sources": [
    {
      "question": "ما هي ساعات العمل؟",
      "answer": "ساعات العمل من 9 صباحاً إلى 5 مساءً",
      "similarity": 0.98
    }
  ],
  "video_url": "https://storage.../avatar_response.mp4"
}

Response Modes

Our platform offers three response modes optimized for different use cases and performance requirements. Choose the mode that best fits your needs based on speed, quality, and coverage requirements.

Knowledge Base Mode (Default & Recommended)

Lightning-fast responses using pre-processed knowledge base with advanced caching. This is the default mode for all plans.

Speed
Instant responses (<100ms) - Fastest possible delivery
Quality
Highest quality - Curated, verified answers from your knowledge base
Plans
Available on all plans (Starter, Professional, Enterprise)
Best For
FAQ systems, customer support, documentation with known questions

Real-Time Generation Mode (Enterprise Only)

Dynamic answer generation for questions not in the knowledge base using real-time AI processing with lipsync generation.

Speed
6-10 seconds - Slower but handles novel queries
Quality
Standard quality - Real-time lipsync with lower quality than KB mode
Plans
Enterprise plan only
Best For
Handling unexpected questions, dynamic content, exploratory conversations

Hybrid Mode (Enterprise Only)

Best of both worlds - instant KB answers with automatic fallback to real-time generation when needed.

Speed
Instant when in KB (<100ms), 6-10s for fallback
Quality
Highest for KB answers, standard for real-time generation
Plans
Enterprise plan only
Best For
Maximum coverage - handles both known and novel questions seamlessly

API Configuration

Enterprise customers can specify the response mode in the API request:

// Knowledge Base Mode (default)
POST /query?knowledge_base_id=YOUR_KB_ID
{
  "query": "What are your business hours?",
  "mode": "knowledge_base" // or omit for default
}

// Real-Time Generation Mode (Enterprise only)
POST /query?knowledge_base_id=YOUR_KB_ID
{
  "query": "What are your business hours?",
  "mode": "realtime"
}

// Hybrid Mode (Enterprise only)
POST /query?knowledge_base_id=YOUR_KB_ID
{
  "query": "What are your business hours?",
  "mode": "hybrid"
}

Intent Detection System

The system automatically classifies user queries into different intent types and provides customizable responses for each intent.

Default Intent Types

greeting

User greets the system (e.g., "Hello", "مرحباً", "Hi there")

farewell

User says goodbye (e.g., "Bye", "وداعاً", "See you later")

question

User asks a direct question that can be answered from the knowledge base

follow_up

User continues the conversation with a follow-up question

no_result

No relevant answer found in the knowledge base (fallback response)

Customizing Intent Responses

You can customize the response for each intent type to match your brand voice and use case.

// Get all intent responses for a knowledge base
const intents = await fetch(
  'API_BASE_URL/intent-responses?knowledge_base_id=YOUR_KB_ID',
  {
    headers: { 'X-API-Key': 'YOUR_API_KEY' }
  }
).then(r => r.json());

// Update an intent response
await fetch('API_BASE_URL/intent-responses/INTENT_ID', {
  method: 'PATCH',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    response_text: "مرحباً بك! كيف يمكنني مساعدتك اليوم؟",
    follow_up_text: "يمكنك سؤالي عن أي شيء متعلق بمنتجاتنا وخدماتنا"
  })
});

Advanced Features

Asynchronous Workflows

Long-running operations like document processing and video generation are handled asynchronously through workflows. Monitor progress using the workflow status endpoint.

// Start document processing workflow
const workflow = await fetch('API_BASE_URL/qa-generation/process-document/DOC_ID', {
  method: 'POST',
  headers: { 'X-API-Key': 'YOUR_API_KEY' }
}).then(r => r.json());

// Poll for status
const checkStatus = async () => {
  const status = await fetch(
    `API_BASE_URL/workflows/${workflow.workflow_id}/status`,
    { headers: { 'X-API-Key': 'YOUR_API_KEY' } }
  ).then(r => r.json());

  console.log('Status:', status.status);     // "running", "completed", "failed"
  console.log('Progress:', status.progress); // 0-100

  if (status.status === 'completed') {
    console.log('Result:', status.result);
  }
};

// Poll every 5 seconds
const interval = setInterval(async () => {
  await checkStatus();
}, 5000);

Vector Search & Embeddings

The system uses OpenAI embeddings to convert Q&A pairs into vector representations, enabling semantic search that understands meaning rather than just matching keywords.

Automatic Vectorization

Q&A pairs are automatically embedded when synced to the vector database

Semantic Similarity

Finds relevant answers even when query wording differs from stored questions

Configurable Results

Control the number of results returned (top_k parameter)

Multi-Language Support

Built with strong support for both Arabic and English, with language-specific processing and responses.

// Create knowledge base with language preference
await fetch('API_BASE_URL/knowledge-bases', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: "Arabic Support KB",
    language: "ar"  // Sets primary language
  })
});

// Create Q&A pairs with language specification
await fetch('API_BASE_URL/qa-pairs?knowledge_base_id=YOUR_KB_ID', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    question: "ما هو رقم الدعم الفني؟",
    answer: "رقم الدعم الفني هو: 123-456-7890",
    language: "ar"
  })
});

Avatar Integration

Upload custom avatars and generate video responses for a more engaging user experience.

Upload Avatar Videos

Upload your own avatar videos to personalize responses

Video Response Generation

Generate videos for Q&A pairs individually or in batch

Include in Query Responses

Set include_video=true to get avatar responses with your queries

API Reference Overview

Authentication

All API requests require authentication using the X-API-Key header:

X-API-Key: YOUR_API_KEY

Knowledge Bases

Create, list, update, and delete knowledge bases

GET /knowledge-basesPOST /knowledge-bases

Documents

Upload and manage documents in knowledge bases

POST /documentsGET /documents?knowledge_base_id=...

Q&A Pairs

Generate, create, and manage Q&A pairs

POST /qa-pairs/generate-from-textGET /qa-pairs?knowledge_base_id=...

Query API

Query knowledge bases with semantic search

POST /query?knowledge_base_id=...

Complete API Documentation

For comprehensive API documentation with detailed examples, parameters, and response schemas, visit the full API reference.

Additional Resources