Domain Chatbot API Documentation

Complete API documentation for the Domain Chatbot platform, including both the API server and Agent server endpoints.

Last Updated: 2025-01-17
Total Endpoints Documented: 172 endpoints across API Server and Agent Server

Overview
Base URLs
Authentication
API Server Endpoints
Agent Server Endpoints
Error Handling
Rate Limiting

Overview

The Domain Chatbot platform consists of two main servers:

API Server (LLM_full/main.py): RESTful API server running on port 8009, handling authentication, queries, logs, stats, and domain management.
Agent Server (Agent/main.py): Real-time communication server supporting WebSocket (port 7861) and WebRTC (port 7860) for chatbot interactions.

Base URLs

API Server

Development: http://localhost:8009
Production: https://api.aventora.ai (or configured domain)

Agent Server

WebSocket: ws://localhost:7861 (or configured domain)
WebRTC: http://localhost:7860 (or configured domain)
Offer Proxy: http://localhost:7862 (or configured domain)

Note: The Offer Proxy server runs on port 7862 and provides:

POST /api/offer - WebRTC offer endpoint (proxied to Pipecat backend)
GET /health - Health check endpoint

Authentication

JWT Token Authentication

Most endpoints require JWT token authentication via the Authorization header:

Authorization: Bearer <access_token>

Token Types

User JWT Tokens: Obtained via /auth/login or /auth/autologin
Temporary Tokens: Generated by admins for time-limited access
Domain API Keys: For server-to-server integrations

Token Generation

POST /token
Content-Type: application/x-www-form-urlencoded

username=<username>&password=<password>

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}

Autologin (Temporary Token)

POST /auth/autologin
Content-Type: application/json

{
  "token": "<temporary_token>"
}

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "user": {
    "id": 1,
    "username": "user@example.com",
    "email": "user@example.com",
    "is_admin": false,
    "domain": "example",
    "language": "en"
  }
}

Domain API Key Authentication

For server-to-server integrations, use domain API keys:

Authorization: Bearer <domain_api_key>

Or via custom header:

X-API-Key: <domain_api_key>

Security Summary

This section provides a quick reference table of all endpoint security requirements. Endpoints are categorized as follows:

Cat1: Public - No authentication required
Cat2: JWT Token - Requires authenticated user with valid JWT token
Cat3: Domain API Key - Can be accessed via domain-specific API key
Cat4: System API Key - Can be accessed via platform-wide admin API key
Cat5: Other - Custom security model (described in notes)

API Server - Core

Endpoint	Description	Security Category
GET /health	Health check	Cat1
POST /token	OAuth2 login	Cat1

Authentication Endpoints

Endpoint	Description	Security Category
POST /auth/register	User registration	Cat1
POST /auth/activate	Activate user account	Cat1
POST /auth/login	User login	Cat1
POST /auth/validate-token	Validate JWT token	Cat1
POST /auth/refresh-token	Refresh expired token	Cat1
POST /auth/request-password-reset	Request password reset	Cat1
POST /auth/reset-password	Reset password	Cat1
POST /auth/change-password	Change password	Cat2
GET /auth/user/settings	Get user settings	Cat2
POST /auth/user/settings	Set user setting	Cat2
DELETE /auth/user/settings/{key}	Delete user setting	Cat2
GET /auth/active-users	List active users	Cat2
GET /auth/inactive-users	List inactive users	Cat2
PUT /auth/users/{user_id}	Update user	Cat2
GET /auth/domain/{domain}/users	Get domain users	Cat5 (JWT or Domain API Key)
GET /auth/user-by-email/{email}	Get user by email	Cat5 (JWT or Domain API Key)
POST /auth/admin/generate-temp-token	Generate temporary token	Cat2 (Admin)
POST /auth/autologin	Autologin with temp token	Cat1
GET /auth/admin/tokens	List temporary tokens	Cat2 (Admin)
DELETE /auth/admin/tokens/{token_id}	Revoke temporary token	Cat2 (Admin)
POST /auth/admin/domain-api-keys	Create domain API key	Cat2 (Admin) or Cat4
GET /auth/admin/domain-api-keys	List domain API keys	Cat2 (Admin) or Cat4
GET /auth/admin/domain/{domain_name}/info	Get domain info	Cat2 (Admin) or Cat4
DELETE /auth/admin/domain-api-keys/{key_id}	Revoke domain API key	Cat2 (Admin)
POST /auth/api/v1/tokens/generate	Generate token via API key	Cat3

Query Endpoints

Endpoint	Description	Security Category
POST /query/	Process query	Cat2 (JWT required)
POST /query/stream	Process query (streaming SSE)	Cat2 (JWT required)
POST /query/continue	Continue conversation	Cat2 (JWT required)
POST /query/continue/stream	Continue conversation (streaming SSE)	Cat2 (JWT required)
GET /query/language/{language_code}	Get language name	Cat1
GET /query/search	Search knowledge base	Cat5 (Optional JWT, rate limited if not authenticated)
GET /query/cache/status	Get cache status	Cat1
POST /query/cache/clear	Clear cache	Cat2 (Admin)
POST /query/send-form-email	Send form email	Cat2 (JWT required)
POST /query/request-service	Process service request	Cat2 (JWT required)

Logs Endpoints

Endpoint	Description	Security Category
GET /logs/	List chat logs	Cat2 (Admin)
GET /logs/{log_id}	Get log entry	Cat2 (Admin)
PATCH /logs/{log_id}	Update log entry	Cat2 (Admin)
POST /logs/archive	Archive logs	Cat2 (Admin)

Stats Endpoints

Endpoint	Description	Security Category
GET /stats/{domain}	Get domain stats	Cat2 (Admin)
GET /stats/	Get all domains stats	Cat2 (Super Admin) or Cat4
GET /stats/domains	List all domains	Cat2 (Super Admin) or Cat4
GET /stats/metadata/{domain_name}	Get domain metadata	Cat2 or Cat3
PUT /stats/metadata/{domain_name}	Update domain metadata	Cat2 (Admin)
POST /stats/upload-logo/{domain_name}	Upload logo	Cat2 (Admin)
GET /stats/logo/{domain_name}	Get logo	Cat1
POST /stats/upload-background-image/{domain_name}	Upload background image	Cat2 (Admin)
GET /stats/background-image/{domain_name}	Get background image	Cat1
POST /stats/upload-font/{domain_name}	Upload font	Cat2 (Admin)
GET /stats/font/{domain_name}/{font_filename}	Get font file	Cat1
GET /stats/fonts/{domain_name}	List fonts	Cat2 (Admin)

Calendar Endpoints

Endpoint	Description	Security Category
GET /api/calendar/users	Get user by ID	Cat1
POST /api/calendar/availability	Create availability	Cat1
GET /api/calendar/users/{user_id}/availability	Get user availability	Cat1
PUT /api/calendar/availability/{availability_id}	Update availability	Cat1
POST /api/calendar/users/{user_id}/set-default-availability	Set default availability	Cat1
POST /api/calendar/users/{user_id}/set-availability	Set availability	Cat1
POST /api/calendar/appointments	Create appointment	Cat1
POST /api/calendar/appointments/book	Book appointment	Cat1
GET /api/calendar/appointments/{appointment_id}	Get appointment	Cat1
GET /api/calendar/users/{user_id}/appointments	Get user appointments	Cat1
GET /api/calendar/admins/{admin_id}/appointments	Get admin appointments	Cat1
PUT /api/calendar/appointments/{appointment_id}	Update appointment	Cat1
DELETE /api/calendar/appointments/{appointment_id}	Cancel appointment	Cat1
POST /api/calendar/appointments/{appointment_id}/cancel	Cancel with domain/lang	Cat1
GET /api/calendar/admins/{admin_id}/available-slots	Get available slots	Cat1
GET /api/calendar/users/{user_id}/overview	Get calendar overview	Cat1
GET /api/calendar/domains/{domain}/admins	Get domain admins	Cat1
GET /api/calendar/health	Calendar health check	Cat1

Calendly Endpoints

Endpoint	Description	Security Category
GET /calendly/next-slot	Get next available slot	Cat1
GET /calendly/first-slot/{date}	Get first slot on date	Cat1
POST /calendly/book	Generate scheduling link	Cat1

Submissions Endpoints

Endpoint	Description	Security Category
POST /submissions/	Create submission	Cat5 (Optional JWT, rate limited if not authenticated)
GET /submissions/{submission_id}	Get submission	Cat5 (Optional JWT)
GET /submissions/	List submissions	Cat5 (Optional JWT)
PUT /submissions/{submission_id}	Update submission	Cat5 (Optional JWT)
DELETE /submissions/{submission_id}	Delete submission	Cat2 (Admin)
GET /submissions/count/total	Get submission count	Cat5 (Optional JWT)

STT Preprocessing Endpoints

Endpoint	Description	Security Category
POST /sttpreprocess/	Preprocess STT text	Cat2
POST /sttpreprocess/batch	Batch preprocess	Cat2
GET /sttpreprocess/stats	Get preprocessing stats	Cat2
GET /sttpreprocess/languages	Get initialized languages	Cat2
GET /sttpreprocess/health	Health check	Cat1
POST /sttpreprocess/formalize-farsi	Formalize Farsi text	Cat2
POST /sttpreprocess/files/upload	Upload custom words file	Cat2
GET /sttpreprocess/files/download	Download file	Cat2
GET /sttpreprocess/files/list	List files	Cat2
POST /sttpreprocess/files/update	Update file content	Cat2
GET /sttpreprocess/files/content	Get file content	Cat2

Index Management Endpoints

Endpoint	Description	Security Category
POST /regenerate-index/	Regenerate index	Cat2 (Admin)
POST /regenerate-index/async-indexing/{domain_name}	Start async indexing	Cat2 (Admin)
GET /regenerate-index/indexing-status/{task_id}	Get indexing status	Cat2 (Admin)
POST /regenerate-index/backup	Backup knowledge base	Cat2 (Admin)
POST /regenerate-index/deduplicate	Deduplicate entries	Cat2 (Admin)
POST /regenerate-index/add-domain	Add new domain	Cat2 (Admin)
POST /regenerate-index/add-anonymous-user/{domain_name}	Add anonymous user	Cat2 (Admin)
GET /regenerate-index/anonymous-user-status/{domain_name}	Get anonymous user status	Cat1
POST /regenerate-index/add-data-from-url/{domain_name}	Crawl URL and add data	Cat2 (Admin)
POST /regenerate-index/upload-file/{domain_name}	Upload file	Cat2 (Admin)
POST /regenerate-index/update-domain-data/{domain_name}	Update domain data	Cat2 (Admin)
GET /regenerate-index/get-domain-data/{domain_name}	Get domain data	Cat2 (Admin)
POST /regenerate-index/set-embedding-version/{domain_name}	Set embedding version	Cat2 (Admin)
GET /regenerate-index/get-domain-versions/{domain_name}	Get embedding versions	Cat2 (Admin)
POST /regenerate-index/build-faiss-index/{domain_name}	Build FAISS index	Cat2 (Admin)
POST /regenerate-index/upload-to-vector-store/{domain_name}	Upload to vector store	Cat2 (Admin)

Agent Server - WebSocket

Endpoint	Description	Security Category
WebSocket /ws	Text-only chat session	Cat5 (Token required if SECURE_AGENT=true)
GET /health	Health check	Cat1
WebSocket /ws-simple	Simple test endpoint	Cat1

Agent Server - WebRTC

Endpoint	Description	Security Category
POST /api/offer	WebRTC offer (via proxy)	Cat5 (Token in metadata if SECURE_AGENT=true)
GET /health (Offer Proxy)	Offer proxy health	Cat1

Telegram Integration

Endpoint	Description	Security Category
POST /telegram/webhook	Telegram webhook	Cat1 (Telegram signature validation)
POST /telegram/webhook/{domain}	Telegram webhook with domain	Cat1 (Telegram signature validation)
POST /telegram/callback	Telegram callback handler	Cat1 (Telegram signature validation)
GET /telegram/status	Telegram status	Cat1

WhatsApp Integration

Endpoint	Description	Security Category
POST /whatsapp/webhook	WhatsApp webhook	Cat1 (Twilio signature validation)
POST /whatsapp/webhook/{domain}	WhatsApp webhook with domain	Cat1 (Twilio signature validation)
GET /whatsapp/status	WhatsApp status	Cat1

Phone/Voice Integration

Endpoint	Description	Security Category
GET /phone/static/{filename}	Serve static audio files	Cat1
POST /voice/webhook/{domain}	Twilio voice webhook	Cat1 (Twilio signature validation)
WebSocket /voice/stream/{domain}	Twilio media stream	Cat1 (Established via Twilio)
POST /voice/status/{domain}	Call status callback	Cat1 (Twilio signature validation)
GET /voice/status	Phone integration status	Cat1

Piper TTS Endpoints

Endpoint	Description	Security Category
GET /api/tts	Generate TTS (GET)	Cat1
POST /api/tts	Generate TTS (POST)	Cat1
GET /bench	TTS benchmark	Cat1
GET /diag	TTS diagnostics	Cat1

Endpoints by Security Category

Cat1 - Public (No Authentication Required)

Endpoint	Description
GET /health	Health check
POST /token	OAuth2 login
POST /auth/register	User registration
POST /auth/activate	Activate user account
POST /auth/login	User login
POST /auth/validate-token	Validate JWT token
POST /auth/refresh-token	Refresh expired token
POST /auth/request-password-reset	Request password reset
POST /auth/reset-password	Reset password
POST /auth/autologin	Autologin with temp token
GET /query/language/{language_code}	Get language name
GET /query/cache/status	Get cache status
GET /stats/logo/{domain_name}	Get logo
GET /stats/background-image/{domain_name}	Get background image
GET /stats/font/{domain_name}/{font_filename}	Get font file
GET /api/calendar/health	Calendar health check
GET /calendly/next-slot	Get next available slot
GET /calendly/first-slot/{date}	Get first slot on date
POST /calendly/book	Generate scheduling link
GET /regenerate-index/anonymous-user-status/{domain_name}	Get anonymous user status
GET /sttpreprocess/health	Health check
GET /health (Agent Server)	Health check
WebSocket /ws-simple	Simple test endpoint
GET /health (Offer Proxy)	Offer proxy health
POST /telegram/webhook	Telegram webhook
POST /telegram/webhook/{domain}	Telegram webhook with domain
POST /telegram/callback	Telegram callback handler
GET /telegram/status	Telegram status
POST /whatsapp/webhook	WhatsApp webhook
POST /whatsapp/webhook/{domain}	WhatsApp webhook with domain
GET /whatsapp/status	WhatsApp status
GET /phone/static/{filename}	Serve static audio files
POST /voice/webhook/{domain}	Twilio voice webhook
WebSocket /voice/stream/{domain}	Twilio media stream
POST /voice/status/{domain}	Call status callback
GET /voice/status	Phone integration status
GET /api/tts	Generate TTS (GET)
POST /api/tts	Generate TTS (POST)
GET /bench	TTS benchmark
GET /diag	TTS diagnostics

Note: Cat1 endpoints may have rate limiting but require no authentication. Webhook endpoints are validated via provider signatures (Telegram, Twilio).

Cat2 - JWT Token (Authenticated User Required)

Endpoint	Description	Notes
POST /auth/change-password	Change password
GET /auth/user/settings	Get user settings
POST /auth/user/settings	Set user setting
DELETE /auth/user/settings/{key}	Delete user setting
GET /auth/active-users	List active users
PUT /auth/users/{user_id}	Update user
POST /sttpreprocess/	Preprocess STT text
POST /sttpreprocess/batch	Batch preprocess
GET /sttpreprocess/stats	Get preprocessing stats
GET /sttpreprocess/languages	Get initialized languages
POST /sttpreprocess/formalize-farsi	Formalize Farsi text
POST /sttpreprocess/files/upload	Upload custom words file
GET /sttpreprocess/files/download	Download file
GET /sttpreprocess/files/list	List files
POST /sttpreprocess/files/update	Update file content
GET /sttpreprocess/files/content	Get file content
GET /auth/inactive-users	List inactive users	Admin only
POST /auth/admin/generate-temp-token	Generate temporary token	Admin only
GET /auth/admin/tokens	List temporary tokens	Admin only
DELETE /auth/admin/tokens/{token_id}	Revoke temporary token	Admin only
DELETE /auth/admin/domain-api-keys/{key_id}	Revoke domain API key	Admin only
GET /logs/	List chat logs	Admin only
GET /logs/{log_id}	Get log entry	Admin only
PATCH /logs/{log_id}	Update log entry	Admin only
POST /logs/archive	Archive logs	Admin only
GET /stats/{domain}	Get domain stats	Admin only
PUT /stats/metadata/{domain_name}	Update domain metadata	Admin only
POST /stats/upload-logo/{domain_name}	Upload logo	Admin only
POST /stats/upload-background-image/{domain_name}	Upload background image	Admin only
POST /stats/upload-font/{domain_name}	Upload font	Admin only
GET /stats/fonts/{domain_name}	List fonts	Admin only
DELETE /submissions/{submission_id}	Delete submission	Admin only
POST /regenerate-index/	Regenerate index	Admin only
POST /regenerate-index/async-indexing/{domain_name}	Start async indexing	Admin only
GET /regenerate-index/indexing-status/{task_id}	Get indexing status	Admin only
POST /regenerate-index/backup	Backup knowledge base	Admin only
POST /regenerate-index/deduplicate	Deduplicate entries	Admin only
POST /regenerate-index/add-domain	Add new domain	Admin only
POST /regenerate-index/add-anonymous-user/{domain_name}	Add anonymous user	Admin only
POST /regenerate-index/add-data-from-url/{domain_name}	Crawl URL and add data	Admin only
POST /regenerate-index/upload-file/{domain_name}	Upload file	Admin only
POST /regenerate-index/update-domain-data/{domain_name}	Update domain data	Admin only
GET /regenerate-index/get-domain-data/{domain_name}	Get domain data	Admin only
POST /regenerate-index/set-embedding-version/{domain_name}	Set embedding version	Admin only
GET /regenerate-index/get-domain-versions/{domain_name}	Get embedding versions	Admin only
POST /regenerate-index/build-faiss-index/{domain_name}	Build FAISS index	Admin only
POST /regenerate-index/upload-to-vector-store/{domain_name}	Upload to vector store	Admin only
GET /stats/	Get all domains stats	Super Admin only
GET /stats/domains	List all domains	Super Admin only

Note: Requires valid JWT token in Authorization: Bearer <token> header. Some endpoints require admin (is_admin=true) or super admin (admin with no domain assigned) privileges.

Cat3 - Domain API Key

Endpoint	Description
POST /auth/api/v1/tokens/generate	Generate token via API key
GET /stats/metadata/{domain_name}	Get domain metadata

Note: Can be accessed using domain-specific API key in Authorization: Bearer <api_key> header. Keys are scoped to specific domains.

Cat4 - System API Key (Platform-Wide Admin)

Endpoint	Description
POST /auth/admin/domain-api-keys	Create domain API key
GET /auth/admin/domain-api-keys	List domain API keys
GET /auth/admin/domain/{domain_name}/info	Get domain info
GET /stats/	Get all domains stats
GET /stats/domains	List all domains

Note: Can be accessed using platform-wide admin API key in Authorization: Bearer <api_key> header. Keys have no domain assigned (platform-wide access).

Cat5 - Other Security Models

Endpoint	Description	Security Model
GET /query/search	Search knowledge base	Optional JWT, rate limited if not authenticated
GET /auth/domain/{domain}/users	Get domain users	JWT or Domain API Key
GET /auth/user-by-email/{email}	Get user by email	JWT or Domain API Key
POST /submissions/	Create submission	Optional JWT, rate limited if not authenticated
GET /submissions/{submission_id}	Get submission	Optional JWT
GET /submissions/	List submissions	Optional JWT
PUT /submissions/{submission_id}	Update submission	Optional JWT
GET /submissions/count/total	Get submission count	Optional JWT
WebSocket /ws	Text-only chat session	Token required if SECURE_AGENT=true
POST /api/offer	WebRTC offer (via proxy)	Token in metadata if SECURE_AGENT=true

Security Model Details:

Query Search Endpoint: Optional JWT authentication. If not authenticated, rate limiting applies. If authenticated, no rate limiting.
Auth User Lookup Endpoints: Accepts either JWT token (for admin UI) or domain API key (for server-to-server). Both authentication methods are required - at least one must be provided.
Submissions Endpoints: JWT authentication required. Contact forms should generate tokens via /api/chatbot-token endpoint.
WebSocket /ws: If SECURE_AGENT=true, requires JWT token via query parameter (?token=<jwt>) or Authorization header. If SECURE_AGENT=false, no authentication required.
WebRTC /api/offer: If SECURE_AGENT=true, requires JWT token in metadata. If SECURE_AGENT=false, no authentication required.

Security Category Details

Cat1 - Public (No Authentication):

Health checks, public query endpoints, webhooks (with provider signature validation), static assets
No authentication required, but may have rate limiting

Cat2 - JWT Token (Authenticated User):

Requires valid JWT token in Authorization: Bearer <token> header
Some endpoints require admin privileges (is_admin=true)
Some endpoints require super admin (admin with no domain assigned)

Cat3 - Domain API Key:

Can be accessed using domain-specific API key
API key passed in Authorization: Bearer <api_key> header
Keys are scoped to specific domains

Cat4 - System API Key:

Can be accessed using platform-wide admin API key
API key passed in Authorization: Bearer <api_key> header
Keys have no domain assigned (platform-wide access)

Cat5 - Other Security Models:

Submissions Endpoints: Optional JWT authentication. If not authenticated, rate limiting applies. If authenticated, no rate limiting.
WebSocket /ws: If SECURE_AGENT=true, requires JWT token via query parameter (?token=<jwt>) or Authorization header. If SECURE_AGENT=false, no authentication required.
WebRTC /api/offer: If SECURE_AGENT=true, requires JWT token in metadata. If SECURE_AGENT=false, no authentication required.
Webhook Endpoints: No authentication, but validated via provider signatures (Telegram, Twilio)

Endpoint Usage Across Projects

This section documents where each endpoint is used across the codebase. This helps understand dependencies and integration points.

Authentication Endpoints

Endpoint	Used By	Location
POST /auth/login	aventora-admin, aventora-bot, AIventora-Phone	`aventora-admin/lib/api/auth.ts`, `aventora-bot/lib/services/auth_service.dart`, `AIventora-Phone/scripts/create_domain_api_key.py`
POST /auth/register	aventora-admin, aventora-bot, aventora-site	`aventora-admin/lib/api/auth.ts`, `aventora-bot/lib/services/auth_service.dart`, `aventora-site/app/register/page.tsx`
POST /auth/activate	aventora-bot	`aventora-bot/lib/services/auth_service.dart`
POST /auth/validate-token	aventora-admin, aventora-site, aventora-bot	`aventora-admin/middleware.ts`, `aventora-site/app/api/*/route.ts`, `aventora-bot/lib/services/token_validation_service.dart`
POST /auth/refresh-token	aventora-bot	`aventora-bot/lib/services/token_validation_service.dart`
POST /auth/request-password-reset	aventora-bot	`aventora-bot/lib/services/auth_service.dart`
POST /auth/reset-password	aventora-bot	`aventora-bot/lib/services/auth_service.dart`
POST /auth/change-password	aventora-admin	`aventora-admin/lib/api/auth.ts`
GET /auth/user/settings	aventora-admin, aventora-bot	`aventora-admin/lib/api/auth.ts`, `aventora-bot/lib/services/auth_service.dart`
POST /auth/user/settings	aventora-admin, aventora-bot	`aventora-admin/lib/api/auth.ts`, `aventora-bot/lib/services/auth_service.dart`
DELETE /auth/user/settings/{key}	aventora-bot	`aventora-bot/lib/services/auth_service.dart`
GET /auth/active-users	aventora-admin	`aventora-admin/lib/api/auth.ts`
GET /auth/inactive-users	aventora-admin	`aventora-admin/lib/api/auth.ts`
PUT /auth/users/{user_id}	aventora-admin	`aventora-admin/lib/api/auth.ts`
GET /auth/domain/{domain}/users	aventora-admin, AIventora-Phone	`aventora-admin/lib/api/auth.ts`, `AIventora-Phone/services/domain_resolver.py`
GET /auth/user-by-email/{email}	AIventora-Phone	`AIventora-Phone/services/sms_service.py`, `AIventora-Phone/bot/handlers/conversational_handler.py`, `AIventora-Phone/server/routers/calls.py`, `AIventora-Phone/services/email_pull_service.py`
POST /auth/admin/generate-temp-token	aventora-admin, aventora-bot	`aventora-admin/lib/api/auth.ts`, `aventora-bot/lib/services/auth_service.dart`
POST /auth/autologin	aventora-bot	`aventora-bot/lib/services/auth_service.dart`
GET /auth/admin/tokens	aventora-admin, aventora-bot	`aventora-admin/lib/api/auth.ts`, `aventora-bot/lib/services/auth_service.dart`
DELETE /auth/admin/tokens/{token_id}	aventora-admin, aventora-bot	`aventora-admin/lib/api/auth.ts`, `aventora-bot/lib/services/auth_service.dart`
POST /auth/admin/domain-api-keys	aventora-admin, aventora-bot, AIventora-Phone	`aventora-admin/lib/api/auth.ts`, `aventora-admin/scripts/*.ts`, `aventora-bot/lib/services/auth_service.dart`, `AIventora-Phone/scripts/create_domain_api_key.py`
GET /auth/admin/domain-api-keys	aventora-admin, aventora-bot, AIventora-Phone	`aventora-admin/lib/api/auth.ts`, `aventora-admin/scripts/*.ts`, `aventora-bot/lib/services/auth_service.dart`
GET /auth/admin/domain/{domain_name}/info	aventora-admin	`aventora-admin/scripts/*.ts`
DELETE /auth/admin/domain-api-keys/{key_id}	aventora-admin, aventora-bot	`aventora-admin/lib/api/auth.ts`, `aventora-bot/lib/services/auth_service.dart`
POST /auth/api/v1/tokens/generate	aventora-site	`aventora-site/app/api/chatbot-token/route.ts`

Query Endpoints

Endpoint	Used By	Location
POST /query/	Internal (domain-chatbot)	Used internally by chatbot processing
POST /query/stream	Internal (domain-chatbot)	Streaming variant of /query/ for clients that consume SSE
POST /query/continue	Internal (domain-chatbot)	`domain-chatbot/LLM/api_client_async.py`, `domain-chatbot/LLM/api_client_openai_d.py`
POST /query/continue/stream	Internal (domain-chatbot)	Streaming variant of /query/continue for clients that consume SSE
GET /query/language/{language_code}	Internal	Used for language processing
GET /query/search	Internal	Used for knowledge base search
GET /query/cache/status	Internal	Used for cache management
POST /query/cache/clear	Internal	Used for cache management
POST /query/send-form-email	aventora-bot	`aventora-bot/lib/services/form_email_service.dart`
POST /query/request-service	aventora-bot	`aventora-bot/lib/widgets/services_list_widget.dart`

Stats Endpoints

Endpoint	Used By	Location
GET /stats/{domain}	aventora-admin	Via `/api/api-server/stats/{domain}` proxy
GET /stats/	aventora-admin	Via `/api/api-server/stats/` proxy
GET /stats/domains	aventora-admin	Via `/api/api-server/stats/domains` proxy
GET /stats/metadata/{domain_name}	aventora-admin, AIventora-Phone, aventora-bot	`aventora-admin/app/api/phone/account-settings/route.ts`, `AIventora-Phone/services/domain_resolver.py`, `aventora-bot/lib/services/domain_metadata_service.dart`
PUT /stats/metadata/{domain_name}	aventora-admin	`aventora-admin/app/api/phone/account-settings/route.ts`
POST /stats/upload-logo/{domain_name}	aventora-admin	Via `/api/api-server/stats/upload-logo/{domain_name}` proxy
GET /stats/logo/{domain_name}	aventora-bot	`aventora-bot/lib/services/domain_logo_service.dart`
POST /stats/upload-background-image/{domain_name}	aventora-admin	Via `/api/api-server/stats/upload-background-image/{domain_name}` proxy
GET /stats/background-image/{domain_name}	aventora-bot	`aventora-bot/lib/services/domain_background_image_service.dart`, `aventora-bot/lib/services/theme_customization_service_web.dart`
POST /stats/upload-font/{domain_name}	aventora-admin	Via `/api/api-server/stats/upload-font/{domain_name}` proxy
GET /stats/font/{domain_name}/{font_filename}	aventora-bot	`aventora-bot/lib/services/domain_font_service.dart`, `aventora-bot/lib/services/theme_customization_service_web.dart`
GET /stats/fonts/{domain_name}	aventora-admin	Via `/api/api-server/stats/fonts/{domain_name}` proxy

Calendar Endpoints

Endpoint	Used By	Location
GET /api/calendar/users	aventora-bot	`aventora-bot/lib/services/calendar_service.dart`
POST /api/calendar/availability	aventora-bot	`aventora-bot/lib/services/calendar_service.dart`
GET /api/calendar/users/{user_id}/availability	aventora-bot	`aventora-bot/lib/services/calendar_service.dart`
PUT /api/calendar/availability/{availability_id}	aventora-bot	`aventora-bot/lib/services/calendar_service.dart`
POST /api/calendar/users/{user_id}/set-default-availability	aventora-bot	`aventora-bot/lib/services/calendar_service.dart`
POST /api/calendar/users/{user_id}/set-availability	aventora-bot	`aventora-bot/lib/services/calendar_service.dart`
POST /api/calendar/appointments	aventora-bot	`aventora-bot/lib/services/calendar_service.dart`
POST /api/calendar/appointments/book	aventora-bot	`aventora-bot/lib/services/calendar_service.dart`
GET /api/calendar/appointments/{appointment_id}	aventora-bot	`aventora-bot/lib/services/calendar_service.dart`
GET /api/calendar/users/{user_id}/appointments	aventora-bot	`aventora-bot/lib/services/calendar_service.dart`
GET /api/calendar/admins/{admin_id}/appointments	aventora-bot	`aventora-bot/lib/services/calendar_service.dart`
PUT /api/calendar/appointments/{appointment_id}	aventora-bot	`aventora-bot/lib/services/calendar_service.dart`
DELETE /api/calendar/appointments/{appointment_id}	aventora-bot	`aventora-bot/lib/services/calendar_service.dart`
POST /api/calendar/appointments/{appointment_id}/cancel	aventora-bot	`aventora-bot/lib/services/calendar_service.dart`
GET /api/calendar/admins/{admin_id}/available-slots	aventora-bot	`aventora-bot/lib/services/calendar_service.dart`
GET /api/calendar/users/{user_id}/overview	aventora-bot	`aventora-bot/lib/services/calendar_service.dart`
GET /api/calendar/domains/{domain}/admins	aventora-bot	`aventora-bot/lib/services/calendar_service.dart`
GET /api/calendar/health	Internal	Health check

Calendly Endpoints

Endpoint	Used By	Location
GET /calendly/next-slot	Internal	Used by chatbot for scheduling
GET /calendly/first-slot/{date}	Internal	Used by chatbot for scheduling
POST /calendly/book	Internal	Used by chatbot for scheduling

Submissions Endpoints

Endpoint	Used By	Location
POST /submissions/	aventora-site	`aventora-site/components//contact.tsx`, `aventora-site/components//footer.tsx`, `aventora-site/app/api/homelife-bayview-signup/route.ts`
GET /submissions/{submission_id}	aventora-admin	Via `/api/api-server/submissions/{submission_id}` proxy
GET /submissions/	aventora-admin	Via `/api/api-server/submissions/` proxy
PUT /submissions/{submission_id}	aventora-admin	Via `/api/api-server/submissions/{submission_id}` proxy
DELETE /submissions/{submission_id}	aventora-admin	Via `/api/api-server/submissions/{submission_id}` proxy
GET /submissions/count/total	aventora-admin	Via `/api/api-server/submissions/count/total` proxy

STT Preprocessing Endpoints

Endpoint	Used By	Location
POST /sttpreprocess/	aventora-bot	`aventora-bot/lib/services/stt_preprocess_service.dart`
POST /sttpreprocess/batch	aventora-bot	`aventora-bot/lib/services/stt_preprocess_service.dart`
GET /sttpreprocess/stats	aventora-bot	`aventora-bot/lib/services/stt_preprocess_service.dart`
GET /sttpreprocess/languages	aventora-bot	`aventora-bot/lib/services/stt_preprocess_service.dart`
GET /sttpreprocess/health	Internal	Health check
POST /sttpreprocess/formalize-farsi	Internal	Used for Farsi text processing
POST /sttpreprocess/files/upload	Internal	Admin file management
GET /sttpreprocess/files/download	Internal	Admin file management
GET /sttpreprocess/files/list	Internal	Admin file management
POST /sttpreprocess/files/update	Internal	Admin file management
GET /sttpreprocess/files/content	Internal	Admin file management

Index Management Endpoints

Logs Endpoints

Endpoint	Used By	Location
GET /logs/	aventora-admin	Via `/api/api-server/logs/` proxy
GET /logs/{log_id}	aventora-admin	Via `/api/api-server/logs/{log_id}` proxy
PATCH /logs/{log_id}	aventora-admin	Via `/api/api-server/logs/{log_id}` proxy
POST /logs/archive	aventora-admin	Via `/api/api-server/logs/archive` proxy

Agent Server Endpoints

Endpoint	Used By	Location
WebSocket /ws	aventora-bot, client-embedding	`aventora-bot/lib/services/websocket_service.dart`, `client-embedding/server.js`
GET /health	Internal, Monitoring	Health checks
WebSocket /ws-simple	Internal	Testing
POST /api/offer	Internal	WebRTC offer handling via proxy
GET /health (Offer Proxy)	Internal	Health check
POST /telegram/webhook	Telegram	External webhook from Telegram
POST /telegram/webhook/{domain}	Telegram	External webhook from Telegram
POST /telegram/callback	Telegram	External callback from Telegram
GET /telegram/status	Internal	Status check
POST /whatsapp/webhook	Twilio	External webhook from Twilio
POST /whatsapp/webhook/{domain}	Twilio	External webhook from Twilio
GET /whatsapp/status	Internal	Status check
GET /phone/static/{filename}	Twilio	Static audio files for phone greetings
POST /voice/webhook/{domain}	Twilio	External webhook from Twilio
WebSocket /voice/stream/{domain}	Twilio	Media stream from Twilio
POST /voice/status/{domain}	Twilio	Status callback from Twilio
GET /voice/status	Internal	Status check

Piper TTS Endpoints

Endpoint	Used By	Location
GET /api/tts	Internal (Pipecat)	`domain-chatbot/chatbot.py`, `domain-chatbot/Agent/`
POST /api/tts	Internal (Pipecat)	`domain-chatbot/chatbot.py`, `domain-chatbot/Agent/`
GET /bench	Internal	TTS benchmarking
GET /diag	Internal	TTS diagnostics

Unused Endpoints

The following endpoints are documented but not currently used by any project in the codebase:

Endpoint	Reason	Notes
POST /token	OAuth2 login endpoint	Standard OAuth2 endpoint, may be used by external clients or OAuth2 libraries
GET /query/cache/test	Test endpoint	Testing/debugging endpoint, not used in production
GET /microsoft/calendar/next-available	Commented out	Microsoft Calendar integration is commented out in `LLM_full/main.py`
GET /microsoft/calendar/first-available/{date}	Commented out	Microsoft Calendar integration is commented out in `LLM_full/main.py`
POST /microsoft/calendar/book-appointment	Commented out	Microsoft Calendar integration is commented out in `LLM_full/main.py`
GET /google/calendar/next-available-slot	Not included	Google Calendar router not explicitly included in `LLM_full/main.py`
POST /google/calendar/book-appointment	Not included	Google Calendar router not explicitly included in `LLM_full/main.py`
GET /ws-test	Test endpoint	Testing endpoint on Agent server
GET / (Agent Server)	Test endpoint	Root endpoint on Agent server for testing
WebSocket /ws-test-simple	Test endpoint	Simple WebSocket test endpoint

Note: Some of these endpoints (like /token) are standard OAuth2 endpoints that may be used by external OAuth2 clients or libraries, even if not directly referenced in the codebase. Test endpoints are intentionally not used in production code.

Notes

Proxy Routes: Many endpoints in aventora-admin are accessed via the /api/api-server/[...path] proxy route, which forwards requests to the actual API server with authentication headers.
Direct API Calls: Some projects (like aventora-bot, AIventora-Phone) make direct HTTP calls to the domain-chatbot API server.
Webhook Endpoints: Telegram, WhatsApp, and Twilio webhooks are called externally by their respective services, not by internal projects.
Internal Endpoints: Some endpoints are primarily used internally within the domain-chatbot project itself for processing and management.

API Server Endpoints

Health Check

GET /health

Check server health status.

Authentication: None

Response:

{
  "status": "ok",
  "message": "Server is running"
}

Authentication Endpoints (`/auth`)

POST /auth/register

Authentication: None

Request Body:

{
  "username": "user@example.com",
  "email": "user@example.com",
  "password": "secure_password",
  "require_activation": true,
  "is_admin": false,
  "domain": "example",
  "full_name": "John Doe",
  "generate_password": false,
  "specialty": "General"
}

Response:

{
  "id": 1,
  "username": "user@example.com",
  "email": "user@example.com",
  "is_admin": false,
  "is_active": false,
  "created_at": "2025-01-17T10:00:00Z",
  "updated_at": "2025-01-17T10:00:00Z",
  "redirect_url": "https://example.com/activate"
}

POST /auth/activate

Activate a user account using activation token.

Authentication: None

Request Body:

{
  "token": "activation_token_here"
}

Response:

{
  "id": 1,
  "username": "user@example.com",
  "email": "user@example.com",
  "is_admin": false,
  "is_active": true,
  "created_at": "2025-01-17T10:00:00Z",
  "updated_at": "2025-01-17T10:00:00Z"
}

POST /auth/login

Authentication: None (OAuth2 password flow)

Request: Form data

username=user@example.com&password=secure_password

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "user": {
    "id": 1,
    "username": "user@example.com",
    "email": "user@example.com",
    "is_admin": false,
    "domain": "example",
    "language": "en"
  }
}

POST /auth/validate-token

Validate a JWT token without requiring full authentication.

Authentication: None

Request Body:

{
  "token": "jwt_token_here"
}

Response:

{
  "valid": true,
  "user": {
    "id": 1,
    "username": "user@example.com",
    "email": "user@example.com",
    "is_admin": false,
    "domain": "example"
  }
}

POST /auth/refresh-token

Refresh an expired token to extend the session.

Authentication: None

Request Body:

{
  "token": "expired_token_here"
}

Response:

{
  "access_token": "new_jwt_token_here",
  "token_type": "bearer"
}

POST /auth/request-password-reset

Request a password reset email.

Authentication: None

Request Body:

{
  "email": "user@example.com",
  "origin": "https://example.com"
}

Response:

{
  "success": true,
  "message": "Password reset email sent"
}

POST /auth/reset-password

Reset password using reset token.

Authentication: None

Request Body:

{
  "token": "reset_token_here",
  "new_password": "new_secure_password"
}

Response:

{
  "success": true,
  "message": "Password reset successfully"
}

POST /auth/change-password

Change password for authenticated user.

Authentication: Required (JWT)

Request Body:

{
  "old_password": "current_password",
  "new_password": "new_secure_password"
}

Response:

{
  "success": true,
  "message": "Password changed successfully"
}

GET /auth/user/settings

Get user settings.

Authentication: Required (JWT)

Response:

{
  "settings": {
    "theme": "dark",
    "language": "en",
    "notifications": true
  }
}

POST /auth/user/settings

Set a user setting.

Authentication: Required (JWT)

Request Body:

{
  "key": "theme",
  "value": "dark"
}

Response:

{
  "success": true,
  "key": "theme",
  "value": "dark"
}

DELETE /auth/user/settings/{key}

Delete a user setting.

Authentication: Required (JWT)

Response:

{
  "success": true,
  "message": "Setting deleted"
}

GET /auth/active-users

Get list of active users.

Authentication: Required (JWT)

Query Parameters:

domain (optional): Filter by domain

Response:

[
  {
    "id": 1,
    "username": "user@example.com",
    "email": "user@example.com",
    "is_admin": false,
    "domain": "example"
  }
]

GET /auth/inactive-users

Get list of inactive users.

Authentication: Required (Admin JWT)

Query Parameters:

domain (optional): Filter by domain

Response:

[
  {
    "id": 2,
    "username": "inactive@example.com",
    "email": "inactive@example.com",
    "is_admin": false,
    "domain": "example",
    "is_active": false
  }
]

PUT /auth/users/{user_id}

Update user information.

Authentication: Required (JWT)

Request Body:

{
  "username": "new_username",
  "email": "new_email@example.com",
  "is_admin": false,
  "is_active": true,
  "settings": {
    "theme": "light"
  }
}

Response:

{
  "id": 1,
  "username": "new_username",
  "email": "new_email@example.com",
  "is_admin": false,
  "is_active": true
}

GET /auth/domain/{domain}/users

Get all users for a domain (server-to-server endpoint).

Authentication: Required (JWT or Domain API Key)

Response:

[
  {
    "id": 1,
    "username": "user@example.com",
    "email": "user@example.com",
    "is_admin": false,
    "domain": "example"
  }
]

GET /auth/user-by-email/{email}

Get user by email (server-to-server endpoint for phone assistant).

Authentication: Required (JWT or Domain API Key)

Response:

{
  "id": 1,
  "username": "user@example.com",
  "email": "user@example.com",
  "domain": "example"
}

POST /auth/admin/generate-temp-token

Generate a temporary access token (admin only).

Authentication: Required (Admin JWT)

Request Body:

{
  "username": "temp_user",
  "full_name": "Temporary User",
  "language": "en",
  "stt_provider": "openai",
  "tts_provider": "openai",
  "start_time": "2025-01-17T10:00:00Z",
  "end_time": "2025-01-17T18:00:00Z",
  "recipient_email": "user@example.com",
  "recipient_phone": "+1234567890",
  "notes": "Temporary access for demo"
}

Response:

{
  "token": "temporary_token_here",
  "username": "temp_user",
  "full_name": "Temporary User",
  "domain": "example",
  "language": "en",
  "stt_provider": "openai",
  "tts_provider": "openai",
  "start_time": "2025-01-17T10:00:00Z",
  "end_time": "2025-01-17T18:00:00Z",
  "qr_code_data_url": "data:image/png;base64,...",
  "autologin_url": "https://example.com/autologin?token=...",
  "created_at": "2025-01-17T10:00:00Z"
}

GET /auth/admin/tokens

Get all temporary tokens created by current admin.

Authentication: Required (Admin JWT)

Response:

[
  {
    "id": 1,
    "token": "temporary_token_here",
    "username": "temp_user",
    "created_at": "2025-01-17T10:00:00Z",
    "expires_at": "2025-01-17T18:00:00Z"
  }
]

DELETE /auth/admin/tokens/{token_id}

Revoke a temporary token.

Authentication: Required (Admin JWT)

Response:

{
  "success": true,
  "message": "Token revoked"
}

POST /auth/admin/domain-api-keys

Generate a domain API key.

Authentication: Required (Admin JWT or Platform Admin API Key)

Request Body:

{
  "name": "Production API Key",
  "description": "API key for production integration",
  "expires_in_days": 365,
  "domain": "example"
}

Response:

{
  "id": 1,
  "domain": "example",
  "name": "Production API Key",
  "api_key": "dk_live_abc123...",
  "api_key_prefix": "dk_live_",
  "created_at": "2025-01-17T10:00:00Z",
  "expires_at": "2026-01-17T10:00:00Z"
}

GET /auth/admin/domain-api-keys

Get all domain API keys for current admin's domain.

Authentication: Required (Admin JWT or Platform Admin API Key)

Response:

[
  {
    "id": 1,
    "domain": "example",
    "name": "Production API Key",
    "api_key_prefix": "dk_live_",
    "created_at": "2025-01-17T10:00:00Z",
    "expires_at": "2026-01-17T10:00:00Z"
  }
]

DELETE /auth/admin/domain-api-keys/{key_id}

Revoke a domain API key.

Authentication: Required (Admin JWT)

Response:

{
  "success": true,
  "message": "API key revoked"
}

POST /auth/api/v1/tokens/generate

Generate a temporary access token using domain API key.

Authentication: Required (Domain API Key)

Request Body:

{
  "username": "anonymous",
  "language": "en",
  "expires_in_hours": 24
}

Response:

{
  "access_token": "jwt_token_here",
  "token_type": "bearer",
  "expires_in": 86400
}

Query Endpoints (`/query`)

POST /query/

Process a query/question.

Authentication: Required (JWT)

Note: Anonymous users should generate tokens via POST /auth/api/v1/tokens/generate using domain API keys.

Request Body:

{
  "name": "John Doe",
  "email": "john@example.com",
  "question": "What are your business hours?",
  "language": "en",
  "domain": "example",
  "user_id": 1,
  "tts": false,
  "domain_metadata": {
    "welcome_message": "Welcome!",
    "contact_message": "Contact us"
  },
  "chat_history": ""
}

Response:

{
  "id": "response_id",
  "text": "Our business hours are Monday to Friday, 9 AM to 5 PM.",
  "role": "assistant",
  "hits": [
    {
      "text": "Business hours: Monday-Friday 9-5",
      "score": 0.95
    }
  ],
  "domain": "example",
  "language": "en"
}

POST /query/continue

Continue a conversation with context.

Authentication: Required (JWT)

Note: Anonymous users should generate tokens via POST /auth/api/v1/tokens/generate using domain API keys.

Request Body:

{
  "name": "John Doe",
  "email": "john@example.com",
  "session": [
    {
      "role": "user",
      "content": "What are your hours?"
    },
    {
      "role": "assistant",
      "content": "Our hours are 9-5."
    }
  ],
  "user_message": "What about weekends?",
  "user_id": 1,
  "tts": false,
  "language": "en",
  "domain": "example",
  "domain_metadata": {},
  "chat_history": ""
}

Response:

{
  "id": "response_id",
  "text": "We are closed on weekends.",
  "role": "assistant"
}

POST /query/stream

Streaming version of POST /query/. Returns Server-Sent Events (SSE) on text/event-stream.

Authentication: Required (JWT)

Request Body: Same as POST /query/ (QueryRequest: name, email, question, language, domain, user_id, tts, domain_metadata, chat_history, file).

Response: Content-Type: text/event-stream. Each event is a line data: <json>\n\n. JSON objects use one of the following type values:

`type`	When	Payload	Client action
`delta`	Each text chunk from the LLM	`{ "type": "delta", "content": "<string>" }`	Append `content` to the displayed assistant message
`tool_call`	A function call is about to run	`{ "type": "tool_call", "name": "<string>" }`	Optional: show “Calling <name>…”
`file_search`	Optional: file_search searching/completed	`{ "type": "file_search", "status": "searching" \| "completed" }`	Optional: show “Searching…”
`done`	End of response	`{ "type": "done", "answer": "<str>", "continue": bool, "complete": bool, "session": [{}], "message_type"?, "formData"?, "clickableForms"?, "clickableServices"?, "phoneData"?, ... }`	Finalize message, update session, handle `message_type` and extras like non‑streaming
`error`	On exception	`{ "type": "error", "message": "<str>" }`	Show error and stop

Note: EventSource does not support POST or custom headers. Use fetch("/query/stream", { method: "POST", body: JSON.stringify(QueryRequest), headers: { "Content-Type": "application/json", "Authorization": "Bearer <token>" } }) and read response.body with ReadableStream + TextDecoder, parsing SSE data: lines and JSON.parse on the data part.

POST /query/continue/stream

Streaming version of POST /query/continue. Returns SSE on text/event-stream.

Authentication: Required (JWT)

Request Body: Same as POST /query/continue (ContinueRequest: name, email, session, user_message, language, domain, user_id, tts, domain_metadata, chat_history).

Response: Same SSE event schema as POST /query/stream (delta, tool_call, file_search, done, error). The done event includes session with the updated conversation including the new user and assistant turns.

GET /query/language/{language_code}

Get language name from language code.

Authentication: None

Response:

{
  "language_code": "en",
  "language_name": "English"
}

GET /query/search

Search the knowledge base using FAISS.

Authentication: Optional (JWT)

Note: Unauthenticated requests are rate limited. Authenticated requests bypass rate limits.

Query Parameters:

query (required): Search query
domain (default: "aventora"): Domain to search
top_k (default: 3): Number of results to return

Response:

{
  "query": "business hours",
  "domain": "example",
  "results": [
    {
      "text": "Business hours: Monday-Friday 9-5",
      "score": 0.95
    }
  ],
  "total_results": 1
}

GET /query/cache/status

Get FAISS cache status.

Authentication: None

Response:

{
  "success": true,
  "cache_status": {
    "total_entries": 1000,
    "domains": ["example", "test"],
    "last_updated": "2025-01-17T10:00:00Z"
  }
}

GET /query/cache/test

Test cache functionality for debugging.

Authentication: None

Query Parameters:

domain (default: "kalano"): Domain to test cache for

Response:

{
  "success": true,
  "domain": "example",
  "results_count": 1,
  "cache_before": {
    "total_entries": 1000
  },
  "cache_after": {
    "total_entries": 1000
  }
}

POST /query/cache/clear

Clear FAISS cache.

Authentication: Required (Admin JWT)

Query Parameters:

domain (optional): Clear cache for specific domain

Response:

{
  "success": true,
  "message": "Cache cleared for domain: example"
}

POST /query/send-form-email

Send form email to user.

Authentication: Required (JWT)

Request Body:

{
  "form_id": "contact_form_1",
  "user_email": "user@example.com",
  "user_name": "John Doe",
  "language": "en",
  "domain": "example"
}

Response:

{
  "success": true,
  "message": "Email sent successfully"
}

POST /query/request-service

Process a service request.

Authentication: Required (JWT)

Request Body:

{
  "service_id": "consultation_1",
  "user_email": "user@example.com",
  "user_name": "John Doe",
  "language": "en",
  "domain": "example"
}

Response:

{
  "success": true,
  "message": "Service request processed"
}

Logs Endpoints (`/logs`)

GET /logs/

Get paginated chat logs.

Authentication: Required (Admin JWT)

Query Parameters:

page (required): Page number (1-based)
page_size (default: 20): Number of logs per page
ip (optional): Filter by IP address
start_time (optional): Filter from timestamp (ISO format)
end_time (optional): Filter until timestamp (ISO format)
question (optional): Filter by question text (partial match)
processed (optional): Filter by processed status
corrected (optional): Filter by correction status
domain (optional): Filter by domain name
from_archive (default: false): Get logs from archived table

Response:

{
  "logs": [
    {
      "id": 1,
      "question": "What are your hours?",
      "answer": "9 AM to 5 PM",
      "ip": "192.168.1.1",
      "domain": "example",
      "created_at": "2025-01-17T10:00:00Z",
      "processed": true,
      "corrected": false
    }
  ],
  "total": 100,
  "page": 1,
  "page_size": 20,
  "total_pages": 5
}

GET /logs/{log_id}

Get a specific log entry.

Authentication: Required (Admin JWT)

Response:

{
  "id": 1,
  "question": "What are your hours?",
  "answer": "9 AM to 5 PM",
  "ip": "192.168.1.1",
  "domain": "example",
  "created_at": "2025-01-17T10:00:00Z",
  "processed": true,
  "corrected": false
}

PATCH /logs/{log_id}

Update a log entry.

Authentication: Required (Admin JWT)

Request Body:

{
  "processed": true,
  "correct_answer": "9 AM to 6 PM"
}

Response:

{
  "id": 1,
  "question": "What are your hours?",
  "answer": "9 AM to 5 PM",
  "correct_answer": "9 AM to 6 PM",
  "processed": true,
  "corrected": true
}

POST /logs/archive

Archive logs older than a timestamp.

Authentication: Required (Admin JWT)

Query Parameters:

before_timestamp (required): Archive logs older than this (ISO format)

Response:

{
  "success": true,
  "archived_count": 1000,
  "timestamp": "2025-01-17T10:00:00Z"
}

Stats Endpoints (`/stats`)

GET /stats/{domain}

Get statistics for a specific domain.

Authentication: Required (Admin JWT)

Response:

{
  "domain": "example",
  "total_logs": 1000,
  "active_users": 50,
  "total_users": 100,
  "domain_data_count": 500
}

GET /stats/

Get comprehensive statistics for all domains (paginated).

Authentication: Required (Super Admin JWT)

Query Parameters:

page (default: 1): Page number
page_size (default: 25, max: 100): Domains per page
search (optional): Search query
sort_by (default: "created_at"): Field to sort by
sort_dir (default: "desc"): Sort direction (asc/desc)

Response:

{
  "domains": [
    {
      "domain_name": "example",
      "active_users": 50,
      "total_logs": 1000,
      "domain_data_count": 500,
      "created_at": "2025-01-01T00:00:00Z"
    }
  ],
  "total_count": 10,
  "page": 1,
  "page_size": 25,
  "total_pages": 1,
  "total_domains": 10,
  "total_active_users": 500,
  "total_users": 1000,
  "total_logs": 10000
}

GET /stats/domains

Get simple list of all domains.

Authentication: Required (Super Admin JWT)

Response:

[
  {
    "id": 1,
    "name": "example",
    "admin_id": 1,
    "created_at": "2025-01-01T00:00:00Z",
    "updated_at": "2025-01-17T10:00:00Z"
  }
]

GET /stats/metadata/{domain_name}

Get domain metadata.

Authentication: Required (JWT or API Key)

Response:

{
  "success": true,
  "domain_name": "example",
  "description": "Example domain",
  "logo_url": "https://example.com/logo.png",
  "welcome_message": "Welcome!",
  "contact_message": "Contact us",
  "top_k": 3,
  "temperature": 0.7
}

PUT /stats/metadata/{domain_name}

Update domain metadata.

Authentication: Required (Admin JWT)

Request Body:

{
  "domain_name": "example",
  "description": "Updated description",
  "welcome_message": "Updated welcome",
  "top_k": 5,
  "temperature": 0.8
}

Response:

{
  "success": true,
  "domain_name": "example",
  "description": "Updated description",
  "welcome_message": "Updated welcome"
}

POST /stats/upload-logo/{domain_name}

Upload domain logo.

Authentication: Required (Admin JWT)

Request: Multipart form data

file: Logo image file (PNG, JPG, etc.)

Response:

{
  "success": true,
  "message": "Logo uploaded successfully",
  "logo_url": "https://example.com/logo.png"
}

GET /stats/logo/{domain_name}

Get domain logo.

Authentication: None

Response: Image file (PNG/JPG)

POST /stats/upload-background-image/{domain_name}

Upload domain background image.

Authentication: Required (Admin JWT)

Request: Multipart form data

file: Background image (SVG, PNG, JPG, WEBP)

Response:

{
  "success": true,
  "message": "Background image uploaded successfully"
}

GET /stats/background-image/{domain_name}

Get domain background image.

Authentication: None

Response: Base64-encoded image with content type

POST /stats/upload-font/{domain_name}

Upload domain font.

Authentication: Required (Admin JWT)

Request: Multipart form data

file: Font file (TTF, OTF, WOFF, WOFF2, EOT)
font_family: Font family name

Response:

{
  "success": true,
  "message": "Font uploaded successfully",
  "font_filename": "custom-font.ttf"
}

GET /stats/font/{domain_name}/{font_filename}

Get domain font file.

Authentication: None

Response: Font file with appropriate content type

GET /stats/fonts/{domain_name}

List all fonts for a domain.

Authentication: Required (Admin JWT)

Response:

{
  "fonts": [
    {
      "filename": "custom-font.ttf",
      "font_family": "Custom Font",
      "size": 102400
    }
  ]
}

Calendar Endpoints (`/api/calendar`)

GET /api/calendar/users

Get user information by ID.

Authentication: Required (JWT)

Query Parameters:

user_id (optional): Registered user ID
anonymous_user_id (optional): Anonymous user ID

Response:

{
  "user_id": 1,
  "name": "John Doe",
  "email": "john@example.com"
}

POST /api/calendar/availability

Create or update availability.

Authentication: Required (JWT)

Request Body:

{
  "user_id": 1,
  "day_of_week": 1,
  "start_time": "09:00",
  "end_time": "17:00"
}

Response:

{
  "id": 1,
  "user_id": 1,
  "day_of_week": 1,
  "start_time": "09:00",
  "end_time": "17:00"
}

GET /api/calendar/users/{user_id}/availability

Get availability for a user.

Authentication: Required (JWT)

Response:

[
  {
    "id": 1,
    "user_id": 1,
    "day_of_week": 1,
    "start_time": "09:00",
    "end_time": "17:00"
  }
]

PUT /api/calendar/availability/{availability_id}

Update availability.

Authentication: Required (JWT)

Request Body:

{
  "start_time": "10:00",
  "end_time": "18:00"
}

Response:

{
  "id": 1,
  "start_time": "10:00",
  "end_time": "18:00"
}

POST /api/calendar/users/{user_id}/set-default-availability

Set default weekday availability for a user.

If a user has no assistant_working_hours or legacy availability rows, calendar reads (assistant calendar view, day availability, and available-slot lookup) persist Monday–Friday 09:00–17:00 (ISO weekday 1–5) and return only remaining slots after the current time in the user's timezone. Saturday and Sunday stay closed until hours are saved.

Authentication: Required (JWT)

Path Parameters:

user_id (required): User ID

Query Parameters:

weekdays (optional): List of weekday numbers (0=Monday, 6=Sunday)
start_time (default: "09:00"): Start time
end_time (default: "17:00"): End time

Response:

{
  "message": "Default availability set successfully"
}

POST /api/calendar/users/{user_id}/set-availability

Set availability for multiple days.

Authentication: Required (JWT)

Request Body:

{
  "user_id": 1,
  "availability_slots": [
    {
      "day_of_week": 1,
      "start_time": "09:00",
      "end_time": "17:00"
    },
    {
      "day_of_week": 2,
      "start_time": "09:00",
      "end_time": "17:00"
    }
  ]
}

Response:

{
  "message": "Availability set successfully"
}

POST /api/calendar/appointments

Create a new appointment.

Authentication: Required (JWT)

Request Body:

{
  "admin_id": 1,
  "user_id": 2,
  "start_time": "2025-01-20T10:00:00Z",
  "duration_minutes": 30,
  "description": "Consultation"
}

Response:

{
  "id": 1,
  "admin_id": 1,
  "user_id": 2,
  "start_time": "2025-01-20T10:00:00Z",
  "duration_minutes": 30,
  "status": "scheduled"
}

POST /api/calendar/appointments/book

Book an appointment (chatbot-friendly).

Authentication: Required (JWT)

Request Body:

{
  "admin_id": 1,
  "user_id": 2,
  "date": "2025-01-20",
  "time": "10:00",
  "duration_minutes": 30,
  "description": "Consultation"
}

Response:

{
  "success": true,
  "appointment_id": 1,
  "message": "Appointment booked successfully"
}

GET /api/calendar/appointments/{appointment_id}

Get an appointment by ID.

Authentication: Required (JWT)

Response:

{
  "id": 1,
  "admin_id": 1,
  "user_id": 2,
  "start_time": "2025-01-20T10:00:00Z",
  "duration_minutes": 30,
  "status": "scheduled"
}

GET /api/calendar/users/{user_id}/appointments

Get appointments for a user.

Authentication: Required (JWT)

Query Parameters:

limit (default: 50): Maximum results

Response:

[
  {
    "id": 1,
    "admin_id": 1,
    "start_time": "2025-01-20T10:00:00Z",
    "status": "scheduled"
  }
]

GET /api/calendar/admins/{admin_id}/appointments

Get appointments for an admin.

Authentication: Required (JWT)

Query Parameters:

limit (default: 50): Maximum results

Response:

[
  {
    "id": 1,
    "user_id": 2,
    "start_time": "2025-01-20T10:00:00Z",
    "status": "scheduled"
  }
]

PUT /api/calendar/appointments/{appointment_id}

Update an appointment.

Authentication: Required (JWT)

Request Body:

{
  "start_time": "2025-01-20T11:00:00Z",
  "status": "confirmed"
}

Response:

{
  "id": 1,
  "start_time": "2025-01-20T11:00:00Z",
  "status": "confirmed"
}

DELETE /api/calendar/appointments/{appointment_id}

Cancel an appointment.

Authentication: Required (JWT)

Response:

{
  "message": "Appointment cancelled successfully"
}

POST /api/calendar/appointments/{appointment_id}/cancel

Cancel an appointment with domain/language support.

Authentication: Required (JWT)

Query Parameters:

domain (default: "default")
language (default: "en")

Response:

{
  "success": true,
  "message": "Appointment cancelled successfully"
}

GET /api/calendar/admins/{admin_id}/available-slots

Get available time slots for an admin.

Authentication: Required (JWT)

Query Parameters:

date (required): Date in YYYY-MM-DD format
duration_minutes (default: 30): Appointment duration

Response:

[
  {
    "start_time": "2025-01-20T09:00:00Z",
    "end_time": "2025-01-20T09:30:00Z",
    "available": true
  }
]

GET /api/calendar/users/{user_id}/overview

Get calendar overview for a user.

Authentication: Required (JWT)

Response:

{
  "user_id": 1,
  "total_appointments": 10,
  "upcoming_appointments": 3,
  "past_appointments": 7,
  "next_appointment": {
    "id": 1,
    "start_time": "2025-01-20T10:00:00Z"
  }
}

GET /api/calendar/domains/{domain}/admins

Get all admin users for a domain.

Authentication: Required (JWT)

Response:

[
  {
    "id": 1,
    "name": "Admin Name",
    "email": "admin@example.com",
    "availability": []
  }
]

GET /api/calendar/health

Health check endpoint.

Response:

{
  "status": "healthy",
  "service": "calendar"
}

Microsoft Calendar Endpoints (`/microsoft/calendar`)

Note: These endpoints are currently commented out in main.py and may not be active. They are included here for reference.

GET /microsoft/calendar/next-available

Get the next available time slot from Microsoft Calendar.

Response:

{
  "success": true,
  "date": "2025-01-20",
  "time": "10:00",
  "scheduling_url": "https://outlook.office.com/..."
}

GET /microsoft/calendar/first-available/{date}

Get the first available slot on a specific day.

Path Parameters:

date: Date in YYYY-MM-DD format

Response:

{
  "success": true,
  "date": "2025-01-20",
  "time": "09:00",
  "scheduling_url": "https://outlook.office.com/..."
}

POST /microsoft/calendar/book-appointment

Book an appointment via Microsoft Calendar.

Request Body:

{
  "date": "2025-01-20",
  "time": "10:00",
  "duration": 30,
  "name": "John Doe",
  "email": "john@example.com",
  "description": "Consultation"
}

Response:

{
  "success": true,
  "appointment_id": "appt_123",
  "scheduling_url": "https://outlook.office.com/..."
}

Google Calendar Endpoints (`/google/calendar`)

Note: These endpoints may not be included in the main router. They are included here for reference.

GET /google/calendar/next-available-slot

Get the next available time slot from Google Calendar.

Response:

{
  "success": true,
  "date": "2025-01-20",
  "time": "10:00",
  "scheduling_url": "https://calendar.google.com/..."
}

POST /google/calendar/book-appointment

Book an appointment via Google Calendar.

Request Body:

{
  "date": "2025-01-20",
  "time": "10:00",
  "duration": 30,
  "name": "John Doe",
  "email": "john@example.com",
  "description": "Consultation"
}

Response:

{
  "success": true,
  "appointment_id": "appt_123",
  "scheduling_url": "https://calendar.google.com/..."
}

Calendly Endpoints (`/calendly`)

GET /calendly/next-slot

Get the next available time slot.

Response:

{
  "success": true,
  "date": "2025-01-20",
  "time": "10:00",
  "scheduling_url": "https://calendly.com/..."
}

GET /calendly/first-slot/{date}

Get the first available slot on a specific day.

Path Parameters:

date: Date in YYYY-MM-DD format

Response:

{
  "success": true,
  "date": "2025-01-20",
  "time": "09:00",
  "scheduling_url": "https://calendly.com/..."
}

POST /calendly/book

Generate a Calendly scheduling link.

Query Parameters:

date (required): Date
time (required): Time
duration (required): Duration in minutes
name (required): Attendee name
email (required): Attendee email
description (optional): Meeting description

Response:

{
  "success": true,
  "scheduling_url": "https://calendly.com/...",
  "event_id": "event_123"
}

Submissions Endpoints (`/submissions`)

POST /submissions/

Create a new submission.

Authentication: Required (JWT)

Note: Contact forms should generate tokens via /api/chatbot-token endpoint on page load.

Request Body:

{
  "type": "contact_form",
  "data": {
    "name": "John Doe",
    "email": "john@example.com",
    "message": "Hello"
  },
  "metadata": {
    "ip": "192.168.1.1",
    "user_agent": "Mozilla/5.0..."
  }
}

Response:

{
  "id": 1,
  "type": "contact_form",
  "data": {
    "name": "John Doe",
    "email": "john@example.com",
    "message": "Hello"
  },
  "user_id": null,
  "created_at": "2025-01-17T10:00:00Z"
}

GET /submissions/{submission_id}

Get a submission by ID.

Authentication: Required (JWT)

Response:

{
  "id": 1,
  "type": "contact_form",
  "data": {
    "name": "John Doe",
    "email": "john@example.com"
  },
  "created_at": "2025-01-17T10:00:00Z"
}

GET /submissions/

Get submissions with filtering.

Authentication: Required (JWT)

Query Parameters:

skip (default: 0): Number of records to skip
limit (default: 100, max: 1000): Maximum results
ip (optional): Filter by IP
type (optional): Filter by type
start_time (optional): Filter by start time (ISO format)
end_time (optional): Filter by end time (ISO format)

Response:

[
  {
    "id": 1,
    "type": "contact_form",
    "data": {},
    "created_at": "2025-01-17T10:00:00Z"
  }
]

PUT /submissions/{submission_id}

Update a submission.

Authentication: Required (JWT)

Request Body:

{
  "data": {
    "status": "processed"
  }
}

Response:

{
  "id": 1,
  "type": "contact_form",
  "data": {
    "status": "processed"
  }
}

DELETE /submissions/{submission_id}

Delete a submission.

Authentication: Required (Admin JWT)

Response:

{
  "success": true,
  "message": "Submission deleted"
}

GET /submissions/count/total

Get submission count.

Authentication: Required (JWT)

Query Parameters:

ip (optional): Filter by IP
type (optional): Filter by type
start_time (optional): Filter by start time
end_time (optional): Filter by end time

Response:

{
  "count": 100
}

STT Preprocessing Endpoints (`/sttpreprocess`)

POST /sttpreprocess/

Preprocess a single STT text.

Authentication: Required (JWT)

Request Body:

{
  "text": "helo world",
  "domain": "example",
  "language": "en",
  "session_id": "session_123"
}

Response:

{
  "original_text": "helo world",
  "processed_text": "hello world",
  "corrections": [
    {
      "original": "helo",
      "corrected": "hello",
      "confidence": 0.95
    }
  ],
  "domain": "example",
  "language": "en"
}

POST /sttpreprocess/batch

Preprocess multiple STT texts in batch.

Authentication: Required (JWT)

Request Body:

{
  "texts": ["helo world", "goodby"],
  "domain": "example",
  "language": "en",
  "session_id": "session_123"
}

Response:

{
  "results": [
    {
      "original_text": "helo world",
      "processed_text": "hello world",
      "corrections": []
    },
    {
      "original_text": "goodby",
      "processed_text": "goodbye",
      "corrections": []
    }
  ],
  "total_processed": 2,
  "successful": 2,
  "failed": 0
}

GET /sttpreprocess/stats

Get preprocessing statistics.

Authentication: Required (JWT)

Query Parameters:

session_id (optional): Session identifier

Response:

{
  "total_processed": 1000,
  "total_corrections": 500,
  "average_confidence": 0.92,
  "session_stats": {
    "session_123": {
      "processed": 10,
      "corrections": 5
    }
  }
}

GET /sttpreprocess/languages

Get initialized languages.

Authentication: Required (JWT)

Query Parameters:

domain (optional): Filter by domain

Response:

{
  "initialized_languages": ["en", "fa", "de"],
  "total_initialized": 3,
  "lazy_loading_enabled": true,
  "initialized_domains": ["example", "test"]
}

GET /sttpreprocess/health

Health check endpoint.

Response:

{
  "status": "healthy",
  "service": "STT Preprocessing",
  "message": "Service is running"
}

POST /sttpreprocess/formalize-farsi

Convert informal Farsi to formal Farsi.

Authentication: Required (JWT)

Request Body:

{
  "text": "چطوری؟"
}

Response:

{
  "original_text": "چطوری؟",
  "formal_text": "چطور هستید؟"
}

POST /sttpreprocess/files/upload

Upload custom words or priority corrections file.

Authentication: Required (JWT)

Request: Multipart form data

domain (required): Domain name
language (required): Language code
file_type (required): "custom_words" or "priority_corrections"
file (required): Text file (.txt)

Response:

{
  "success": true,
  "message": "File uploaded successfully",
  "file_path": "/path/to/file.txt"
}

GET /sttpreprocess/files/download

Download custom words or priority corrections file.

Authentication: Required (JWT)

Query Parameters:

domain (required): Domain name
language (required): Language code
file_type (required): "custom_words" or "priority_corrections"

Response: Text file download

GET /sttpreprocess/files/list

List available files.

Authentication: Required (JWT)

Query Parameters:

domain (optional): Filter by domain

Response:

{
  "files": [
    {
      "domain": "example",
      "language": "en",
      "file_type": "custom_words",
      "file_path": "/path/to/file.txt"
    }
  ],
  "total_files": 1
}

POST /sttpreprocess/files/update

Update file content.

Authentication: Required (JWT)

Request Body:

{
  "domain": "example",
  "language": "en",
  "file_type": "custom_words",
  "content": "word1\nword2\nword3"
}

Response:

{
  "success": true,
  "message": "File updated successfully"
}

GET /sttpreprocess/files/content

Get file content.

Authentication: Required (JWT)

Query Parameters:

domain (required): Domain name
language (required): Language code
file_type (required): "custom_words" or "priority_corrections"

Response:

{
  "domain": "example",
  "language": "en",
  "file_type": "custom_words",
  "content": "word1\nword2\nword3",
  "line_count": 3
}

Index Management Endpoints (`/regenerate-index`)

POST /regenerate-index/

Regenerate index for a domain.

Authentication: Required (Admin JWT)

Query Parameters:

domain_name (required): Domain name

Response:

{
  "success": true,
  "message": "Index regenerated successfully",
  "domain": "example"
}

POST /regenerate-index/async-indexing/{domain_name}

Start asynchronous indexing process.

Authentication: Required (Admin JWT)

Query Parameters:

language (default: "en"): Language code

Response:

{
  "success": true,
  "task_id": "task_123",
  "message": "Indexing started",
  "domain": "example"
}

GET /regenerate-index/indexing-status/{task_id}

Get indexing task status.

Authentication: Required (Admin JWT)

Response:

{
  "task_id": "task_123",
  "status": "completed",
  "progress": 100,
  "message": "Indexing completed successfully"
}

POST /regenerate-index/backup

Create a backup of the knowledge base.

Authentication: Required (Admin JWT)

Response:

{
  "success": true,
  "backup_location": "/backups/20250117_100000",
  "timestamp": "20250117_100000"
}

POST /regenerate-index/deduplicate

Deduplicate entries.

Authentication: Required (Admin JWT)

Request Body:

{
  "entries": [
    {"text": "Entry 1"},
    {"text": "Entry 2"},
    {"text": "Entry 1"}
  ]
}

Response:

{
  "success": true,
  "original_count": 3,
  "deduplicated_count": 2,
  "removed_count": 1,
  "entries": [
    {"text": "Entry 1"},
    {"text": "Entry 2"}
  ]
}

POST /regenerate-index/add-domain

Add a new domain.

Authentication: Required (Admin JWT)

Request Body:

{
  "domain_name": "new_domain",
  "admin_username": "admin@example.com",
  "admin_email": "admin@example.com",
  "admin_password": "secure_password"
}

Response:

{
  "success": true,
  "domain": "new_domain",
  "admin_user": {
    "id": 1,
    "username": "admin@example.com"
  }
}

POST /regenerate-index/add-anonymous-user/{domain_name}

Add or update anonymous user for a domain.

Authentication: Required (Admin JWT)

Query Parameters:

active (default: true): Active status

Response:

{
  "success": true,
  "message": "Anonymous user added/updated",
  "domain": "example",
  "active": true
}

GET /regenerate-index/anonymous-user-status/{domain_name}

Get anonymous user status.

Authentication: None (public endpoint)

Response:

{
  "active": true
}

POST /regenerate-index/add-data-from-url/{domain_name}

Crawl URL and add content to domain.

Authentication: Required (Admin JWT)

Query Parameters:

url (required): Starting URL to crawl
regenerate (default: false): Regenerate index after processing
language (default: "en"): Language code
max_pages (optional): Maximum pages to crawl

Response:

{
  "success": true,
  "message": "Data added successfully",
  "pages_crawled": 10,
  "qa_pairs_added": 50
}

POST /regenerate-index/upload-file/{domain_name}

Upload file and add to domain data.

Authentication: Required (Admin JWT)

Request: Multipart form data

file (required): Text, PDF, or MS Word file
regenerate (default: false): Regenerate index
language (default: "en"): Language code

Response:

{
  "success": true,
  "message": "File uploaded and processed",
  "qa_pairs_added": 20
}

POST /regenerate-index/update-domain-data/{domain_name}

Update domain-data.txt file.

Authentication: Required (Admin JWT)

Query Parameters:

regenerate (default: false): Regenerate index
language (default: "en"): Language code

Request Body:

{
  "content": "Q: Question 1?\nA: Answer 1.\n\nQ: Question 2?\nA: Answer 2."
}

Response:

{
  "success": true,
  "message": "Domain data updated"
}

GET /regenerate-index/get-domain-data/{domain_name}

Get domain-data.txt content.

Authentication: Required (Admin JWT)

Response:

{
  "content": "Q: Question 1?\nA: Answer 1.\n\nQ: Question 2?\nA: Answer 2.",
  "domain": "example"
}

POST /regenerate-index/set-embedding-version/{domain_name}

Set active embedding version.

Authentication: Required (Admin JWT)

Request Body:

{
  "version": "text-embedding-3-large"
}

Response:

{
  "success": true,
  "message": "Embedding version set",
  "version": "text-embedding-3-large"
}

GET /regenerate-index/get-domain-versions/{domain_name}

Get all available embedding versions.

Authentication: Required (Admin JWT)

Response:

{
  "versions": [
    {
      "version": "text-embedding-3-large",
      "active": true,
      "created_at": "2025-01-17T10:00:00Z"
    }
  ],
  "active_version": "text-embedding-3-large"
}

POST /regenerate-index/build-faiss-index/{domain_name}

Build FAISS index from knowledge sources.

Authentication: Required (Admin JWT)

Response:

{
  "success": true,
  "message": "FAISS index built successfully"
}

POST /regenerate-index/upload-to-vector-store/{domain_name}

Upload domain data to OpenAI vector store.

Authentication: Required (Admin JWT)

Response:

{
  "success": true,
  "message": "Data uploaded to vector store",
  "vector_store_id": "vs_123"
}

Agent Server Endpoints

The Agent Server provides real-time communication via WebSocket and WebRTC protocols.

WebSocket Endpoints

WebSocket Connection: `/ws`

URL: ws://localhost:7861/ws (or configured domain)

Authentication:

If SECURE_AGENT=true: Token required via query parameter or Authorization header
- Query: ?token=<jwt_token>
- Header: Authorization: Bearer <jwt_token>
If SECURE_AGENT=false: No authentication required

Connection Flow:

Connect: Client establishes WebSocket connection
Authentication (if secure): Token validated, connection accepted or rejected

Metadata: Client sends metadata message:

{
  "type": "metadata",
  "data": {
    "language": "en",
    "domain": "example",
    "user": {
      "name": "John Doe",
      "email": "john@example.com",
      "id": 1
    },
    "domain_metadata": {
      "welcome_message": "Welcome!",
      "contact_message": "Contact us"
    }
  }
}

Or direct format:

{
  "language": "en",
  "domain": "example",
  "user": {
    "name": "John Doe",
    "email": "john@example.com"
  }
}

Welcome Message: Server sends welcome message:

{
  "type": "message",
  "data": {
    "id": null,
    "text": "Welcome! How can I help you?",
    "timestamp": 1705492800000,
    "isComplete": true,
    "isStreaming": false
  }
}

Message Exchange: Client sends messages:

{
  "type": "message",
  "data": {
    "text": "What are your hours?"
  }
}

Server responds:

{
  "type": "message",
  "data": {
    "id": "response_id",
    "text": "Our hours are 9 AM to 5 PM.",
    "role": "assistant",
    "timestamp": 1705492801000,
    "isComplete": true,
    "isStreaming": false,
    "message_type": "form_request",
    "formData": {
      "form_id": "contact_form",
      "fields": [...]
    }
  }
}

Heartbeat: Client can send heartbeat:

{
  "type": "heartbeat",
  "timestamp": 1705492800000
}

Server responds:

{
  "type": "heartbeat_ack",
  "timestamp": 1705492800000
}

Message Types:

connection: Connection status
message: Text message
heartbeat: Keep-alive
heartbeat_ack: Heartbeat acknowledgment
token_renewed: Token auto-renewal (for anonymous users)
error: Error message
thinking: Processing indicator

GET /health

Health check endpoint.

Response:

{
  "status": "ok"
}

GET /ws-test

Test endpoint to verify WebSocket availability.

Response:

{
  "message": "WebSocket endpoint available at /ws"
}

GET /

Root endpoint with server information.

Response:

{
  "message": "Dual-transport server running",
  "endpoints": ["/ws", "/health", "/ws-test", "/telegram/webhook"],
  "transports": ["websocket", "webrtc"],
  "websocket_port": 7861,
  "webrtc_port": 7860
}

WebSocket /ws-simple

Simple WebSocket endpoint for testing basic connectivity.

URL: ws://localhost:7861/ws-simple

Authentication: None

Description: Basic test endpoint that accepts connection and sends a simple message.

WebSocket /ws-test-simple

Another simple WebSocket test endpoint.

URL: ws://localhost:7861/ws-test-simple

Authentication: None

WebRTC Endpoints

WebRTC connections are handled via Pipecat framework. Clients connect through:

POST /api/offer (via Offer Proxy on port 7862)

URL: http://localhost:7862/api/offer (or configured domain)

Note: This endpoint is provided by the Offer Proxy server, which forwards requests to the Pipecat backend.

Authentication:

Token can be passed in metadata
If SECURE_AGENT=true: Token validation required

Request Body:

{
  "sdp": "webRTC_offer_sdp",
  "metadata": {
    "language": "en",
    "domain": "example",
    "stt_provider": "openai",
    "tts_provider": "openai",
    "user": {
      "name": "John Doe",
      "email": "john@example.com",
      "id": 1
    },
    "token": "jwt_token_here"
  }
}

Response:

{
  "sdp": "webRTC_answer_sdp",
  "session_id": "session_123"
}

WebRTC Connection Flow:

Client creates WebRTC offer
Client sends offer to /api/offer with metadata
Server processes offer and returns answer
Client establishes WebRTC connection
Audio/video streams are exchanged

App messages can be sent via data channel:

{
  "type": "metadata",
  "data": {
    "language": "en",
    "domain": "example"
  }
}

Transport Selection:

WebSocket (/ws): Used for text-only sessions (no STT/TTS)
WebRTC (/api/offer): Used for audio/video sessions (STT/TTS enabled)

GET /health (Offer Proxy)

Health check endpoint for the Offer Proxy server.

URL: http://localhost:7862/health

Response:

{
  "status": "ok"
}

Telegram Integration Endpoints

POST /telegram/webhook

Telegram webhook endpoint for receiving messages.

Authentication: None (Telegram webhook)

Path Parameters:

domain (optional): Domain identifier in path

Query Parameters:

domain (optional): Domain identifier in query
bot (optional): Bot identifier mapped to domain

Request Body:

{
  "update_id": 123456789,
  "message": {
    "message_id": 1,
    "from": {
      "id": 123456789,
      "first_name": "John",
      "username": "johndoe"
    },
    "chat": {
      "id": 123456789,
      "type": "private"
    },
    "text": "Hello"
  }
}

Response:

{
  "ok": true
}

Description: Handles incoming Telegram messages, voice messages, and callback queries. Supports domain-based routing and user management.

POST /telegram/webhook/{domain}

Telegram webhook with domain in path.

Path Parameters:

domain (required): Domain identifier

Request/Response: Same as /telegram/webhook

POST /telegram/callback

Handle Telegram callback queries from inline keyboards.

Authentication: None

Request Body:

{
  "callback_query": {
    "id": "callback_123",
    "from": {
      "id": 123456789
    },
    "message": {
      "chat": {
        "id": 123456789
      }
    },
    "data": "share_email"
  }
}

Response:

{
  "ok": true
}

Callback Actions:

share_email: Request email collection
skip_email: Skip email and create anonymous user
confirm_email: Confirm email
cancel_email: Cancel email collection

GET /telegram/status

Get Telegram webhook status.

Response:

{
  "status": "ok",
  "webhook": "active",
  "endpoint": "/telegram/webhook"
}

WhatsApp Integration Endpoints

POST /whatsapp/webhook

WhatsApp webhook endpoint for receiving messages via Twilio.

Authentication: None (Twilio webhook signature validation)

Path Parameters:

domain (optional): Domain identifier in path

Query Parameters:

domain (optional): Domain identifier in query

Request: Form data from Twilio

From=whatsapp:+14165551234
Body=Hello
AccountSid=AC...

Response:

{
  "ok": true
}

Description: Handles incoming WhatsApp messages, creates users automatically, and processes messages through the chatbot.

POST /whatsapp/webhook/{domain}

WhatsApp webhook with domain in path.

Path Parameters:

domain (required): Domain identifier

Request/Response: Same as /whatsapp/webhook

GET /whatsapp/status

Get WhatsApp webhook status.

Response:

{
  "status": "ok",
  "webhook": "active",
  "endpoint": "/whatsapp/webhook"
}

Phone/Voice Integration Endpoints

Note: These endpoints are only available when PHONE_INTEGRATION_ENABLED=true environment variable is set.

GET /phone/static/{filename}

Serve static audio files for phone greetings.

Authentication: None

Path Parameters:

filename (required): Audio filename

Response: Audio file (WAV/MP3)

Description: Serves audio files from Agent/phone/static/ directory for phone call greetings.

POST /voice/webhook/{domain}

TwiML webhook for incoming Twilio voice calls.

Authentication: None (Twilio webhook)

Path Parameters:

domain (required): Domain identifier

Request: Form data from Twilio

CallSid=CA123
From=+14165551234
To=+14165551235

Response: TwiML XML

<Response>
  <Connect>
    <Stream url="wss://example.com/voice/stream/domain" />
  </Connect>
</Response>

Description: Returns TwiML to establish Media Streams connection for real-time audio processing.

WebSocket /voice/stream/{domain}

WebSocket endpoint for Twilio Media Streams.

URL: wss://localhost:7861/voice/stream/{domain}

Authentication: None (established via Twilio)

Path Parameters:

domain (required): Domain identifier

Description: Handles real-time bidirectional audio streaming for phone calls. Processes audio through STT/TTS pipeline.

POST /voice/status/{domain}

Call status callback from Twilio.

Authentication: None (Twilio webhook)

Path Parameters:

domain (required): Domain identifier

Request: Form data from Twilio

CallSid=CA123
CallStatus=completed
Duration=120

Response:

{
  "ok": true
}

Description: Receives call status updates (ringing, in-progress, completed, etc.) from Twilio.

GET /voice/status

Get phone integration status.

Response:

{
  "status": "ok",
  "phone_integration": "active",
  "endpoints": {
    "webhook": "/voice/webhook/{domain}",
    "stream": "/voice/stream/{domain}",
    "status": "/voice/status/{domain}"
  }
}

Piper TTS Endpoints

Note: These endpoints are part of the Piper TTS service, typically running on a separate port.

GET /api/tts

Generate TTS audio via GET request.

Query Parameters:

text (required): Text to synthesize
index (optional): Voice index

Response: Audio/WAV stream

Example:

GET /api/tts?text=Hello%20world&index=0

POST /api/tts

Generate TTS audio via POST request.

Request Body (JSON):

{
  "text": "Hello world",
  "index": 0
}

Or raw text:

POST /api/tts
Content-Type: text/plain

Hello world

Query Parameters:

index (optional): Voice index (if not in body)

Response: Audio/WAV stream

GET /bench

Benchmark TTS performance.

Query Parameters:

index (default: 0): Voice index
seconds (default: 6.0): Duration of test text

Response:

{
  "index": 0,
  "elapsed_sec": 2.345,
  "session_providers": ["CPUExecutionProvider"]
}

GET /diag

Get TTS diagnostic information.

Response:

{
  "ort_version": "1.16.0",
  "ort_build_device": "CPU",
  "ort_available_providers": ["CPUExecutionProvider"],
  "voices": [
    {
      "index": 0,
      "model": "path/to/model.onnx",
      "config": "path/to/config.json",
      "providers": ["CPUExecutionProvider"]
    }
  ]
}

Error Handling

Standard Error Response Format

{
  "detail": "Error message description"
}

HTTP Status Codes

200 OK: Successful request
201 Created: Resource created successfully
204 No Content: Successful deletion
400 Bad Request: Invalid request data
401 Unauthorized: Authentication required
403 Forbidden: Insufficient permissions
404 Not Found: Resource not found
500 Internal Server Error: Server error
503 Service Unavailable: Service temporarily unavailable

Common Error Scenarios

Authentication Errors

{
  "detail": "Could not validate credentials"
}

Validation Errors

{
  "detail": "Invalid domain: example"
}

Not Found Errors

{
  "detail": "Log not found"
}

Rate Limiting

Submission Endpoints

Unauthenticated users: Rate limited (configurable)
Authenticated users: No rate limiting

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1705492800

Other Endpoints

Most endpoints do not have rate limiting, except:

Public query endpoints may have rate limiting based on IP
Authentication endpoints may have rate limiting to prevent brute force

Security Notes

JWT Tokens:
- Tokens expire based on ACCESS_TOKEN_EXPIRE_MINUTES setting
- Anonymous tokens can be auto-renewed if expired
- Tokens should be stored securely on the client
Domain API Keys:
- API keys are shown only once at creation
- Revoked keys cannot be reused
- Keys can have expiration dates
Secure Agent Mode:
- When SECURE_AGENT=true, all agent connections require authentication
- WebSocket and WebRTC connections validate tokens
- Anonymous tokens are auto-renewed if expired
CORS:
- API server has CORS configured for allowed origins
- Agent server allows all origins in development mode
- Production should restrict origins
Admin Endpoints:
- Admin endpoints require is_admin=true in user token
- Super admin endpoints require is_admin=true and no domain assigned
- Domain admin endpoints require is_admin=true and matching domain

Changelog

Date	Change
2026-08-13	Calendar: empty availability records persist Monday–Friday 09:00–17:00 on first read; today's slots start after the current local time.

Additional Resources

Technical Documentation: See Technical-documentation.md
User Guide: See Userguide.md
Features: See Features.md
Deployment: See Deployment.md

Document Version: 1.0
Last Updated: 2026-08-13

Endpoint	Used By	Location
POST /regenerate-index/	aventora-admin	Via `/api/api-server/regenerate-index/` proxy
POST /regenerate-index/async-indexing/{domain_name}	aventora-admin	Via `/api/api-server/regenerate-index/async-indexing/{domain_name}` proxy
GET /regenerate-index/indexing-status/{task_id}	aventora-admin	Via `/api/api-server/regenerate-index/indexing-status/{task_id}` proxy
POST /regenerate-index/backup	aventora-admin	Via `/api/api-server/regenerate-index/backup` proxy
POST /regenerate-index/deduplicate	aventora-admin	Via `/api/api-server/regenerate-index/deduplicate` proxy
POST /regenerate-index/add-domain	aventora-admin	Via `/api/api-server/regenerate-index/add-domain` proxy
POST /regenerate-index/add-anonymous-user/{domain_name}	aventora-admin	Via `/api/api-server/regenerate-index/add-anonymous-user/{domain_name}` proxy
GET /regenerate-index/anonymous-user-status/{domain_name}	Internal	Used for checking anonymous user status
POST /regenerate-index/add-data-from-url/{domain_name}	aventora-admin	Via `/api/api-server/regenerate-index/add-data-from-url/{domain_name}` proxy
POST /regenerate-index/upload-file/{domain_name}	aventora-admin	Via `/api/api-server/regenerate-index/upload-file/{domain_name}` proxy
POST /regenerate-index/update-domain-data/{domain_name}	aventora-admin	Via `/api/api-server/regenerate-index/update-domain-data/{domain_name}` proxy
GET /regenerate-index/get-domain-data/{domain_name}	aventora-admin	Via `/api/api-server/regenerate-index/get-domain-data/{domain_name}` proxy
POST /regenerate-index/set-embedding-version/{domain_name}	aventora-admin	Via `/api/api-server/regenerate-index/set-embedding-version/{domain_name}` proxy
GET /regenerate-index/get-domain-versions/{domain_name}	aventora-admin	Via `/api/api-server/regenerate-index/get-domain-versions/{domain_name}` proxy
POST /regenerate-index/build-faiss-index/{domain_name}	aventora-admin	Via `/api/api-server/regenerate-index/build-faiss-index/{domain_name}` proxy
POST /regenerate-index/upload-to-vector-store/{domain_name}	aventora-admin	Via `/api/api-server/regenerate-index/upload-to-vector-store/{domain_name}` proxy

Table of Contents​

Overview​

Base URLs​

API Server​

Agent Server​

Authentication​

JWT Token Authentication​

Token Types​

Token Generation​

Login (OAuth2 Password Flow)​

Autologin (Temporary Token)​

Domain API Key Authentication​

Security Summary​

API Server - Core​

Authentication Endpoints​

Query Endpoints​

Logs Endpoints​

Stats Endpoints​

Calendar Endpoints​

Calendly Endpoints​

Submissions Endpoints​

STT Preprocessing Endpoints​

Index Management Endpoints​

Agent Server - WebSocket​

Agent Server - WebRTC​

Telegram Integration​

WhatsApp Integration​

Phone/Voice Integration​

Piper TTS Endpoints​

Endpoints by Security Category​

Cat1 - Public (No Authentication Required)​

Cat2 - JWT Token (Authenticated User Required)​

Cat3 - Domain API Key​

Cat4 - System API Key (Platform-Wide Admin)​

Cat5 - Other Security Models​

Security Category Details​

Endpoint Usage Across Projects​

Authentication Endpoints​

Query Endpoints​

Stats Endpoints​

Calendar Endpoints​

Calendly Endpoints​

Submissions Endpoints​

STT Preprocessing Endpoints​

Index Management Endpoints​

Logs Endpoints​

Agent Server Endpoints​

Piper TTS Endpoints​

Unused Endpoints​

Notes​

API Server Endpoints​

Health Check​

GET /health​

Authentication Endpoints (/auth)​

POST /auth/register​

POST /auth/activate​

POST /auth/login​

POST /auth/validate-token​

POST /auth/refresh-token​

POST /auth/request-password-reset​

POST /auth/reset-password​

POST /auth/change-password​

GET /auth/user/settings​

POST /auth/user/settings​

DELETE /auth/user/settings/{key}​

GET /auth/active-users​

GET /auth/inactive-users​

PUT /auth/users/{user_id}​

GET /auth/domain/{domain}/users​

GET /auth/user-by-email/{email}​

POST /auth/admin/generate-temp-token​

GET /auth/admin/tokens​

DELETE /auth/admin/tokens/{token_id}​

POST /auth/admin/domain-api-keys​

GET /auth/admin/domain-api-keys​

DELETE /auth/admin/domain-api-keys/{key_id}​

POST /auth/api/v1/tokens/generate​

Query Endpoints (/query)​

POST /query/​

POST /query/continue​

Table of Contents

Overview

Base URLs

API Server

Agent Server

Authentication

JWT Token Authentication

Token Types

Token Generation

Login (OAuth2 Password Flow)

Autologin (Temporary Token)

Domain API Key Authentication

Security Summary

API Server - Core

Authentication Endpoints

Query Endpoints

Logs Endpoints

Stats Endpoints

Calendar Endpoints

Calendly Endpoints

Submissions Endpoints

STT Preprocessing Endpoints

Index Management Endpoints

Agent Server - WebSocket

Agent Server - WebRTC

Telegram Integration

WhatsApp Integration

Phone/Voice Integration

Piper TTS Endpoints

Endpoints by Security Category

Cat1 - Public (No Authentication Required)

Cat2 - JWT Token (Authenticated User Required)

Cat3 - Domain API Key

Cat4 - System API Key (Platform-Wide Admin)

Cat5 - Other Security Models

Security Category Details

Endpoint Usage Across Projects

Authentication Endpoints

Query Endpoints

Stats Endpoints

Calendar Endpoints

Calendly Endpoints

Submissions Endpoints

STT Preprocessing Endpoints

Index Management Endpoints

Logs Endpoints

Agent Server Endpoints

Piper TTS Endpoints

Unused Endpoints

Notes

API Server Endpoints

Health Check

GET /health

Authentication Endpoints (`/auth`)

POST /auth/register

POST /auth/activate

POST /auth/login

POST /auth/validate-token

POST /auth/refresh-token

POST /auth/request-password-reset

POST /auth/reset-password

POST /auth/change-password

GET /auth/user/settings

POST /auth/user/settings

DELETE /auth/user/settings/{key}

GET /auth/active-users

GET /auth/inactive-users

PUT /auth/users/{user_id}

GET /auth/domain/{domain}/users

GET /auth/user-by-email/{email}

POST /auth/admin/generate-temp-token

GET /auth/admin/tokens

DELETE /auth/admin/tokens/{token_id}

POST /auth/admin/domain-api-keys

GET /auth/admin/domain-api-keys

DELETE /auth/admin/domain-api-keys/{key_id}

POST /auth/api/v1/tokens/generate

Query Endpoints (`/query`)

POST /query/

POST /query/continue