API Schemas

Data structures used in API requests and responses.

LLMRequest

Request body for LLM calls.

interface LLMRequest {
  query: string;           // Required: The prompt
  model?: string;          // Model ID or "auto"
  provider?: string;       // Provider name
  messages?: Message[];    // Conversation history
  temperature?: number;    // 0-1, default 0.7
  max_tokens?: number;     // Max response length
  stream?: boolean;        // Stream response
}

interface Message {
  role: "user" | "assistant" | "system";
  content: string;
}

LLMResponse

Response from LLM calls.

interface LLMResponse {
  success: boolean;
  response: string;
  model: string;
  provider: string;
  usage: Usage;
  cost: number;
  latency_ms: number;
  routing?: RoutingDecision;
}

interface Usage {
  input_tokens: number;
  output_tokens: number;
  total_tokens: number;
}

interface RoutingDecision {
  is_auto_routed: boolean;
  model_chosen: string;
  confidence: number;
  reason?: string;
}

Agent

Agent configuration.

interface Agent {
  id: string;
  name: string;
  commercial_name: string;
  bio: string;
  type: AgentType;
  status: "draft" | "published" | "archived";
  llm_config: LLMConfig;
  metadata?: Record<string, any>;
  tags?: string[];
  visibility: "tenant" | "public";
  created_at: string;
  updated_at: string;
}

type AgentType =
  | "data_analyst"
  | "customer_support"
  | "sales"
  | "general";

interface LLMConfig {
  model: string;
  temperature?: number;
  max_tokens?: number;
}

DatabaseConfig

Database connection configuration.

interface DatabaseConfig {
  id: string;
  name: string;
  description?: string;
  provider: "postgresql";
  connection_config: ConnectionConfig;
  settings: DatabaseSettings;
  is_primary: boolean;
  is_active: boolean;
  created_at: string;
}

interface ConnectionConfig {
  host: string;
  port: number;
  database: string;
  username: string;
  password: string;
  ssl: boolean;
}

interface DatabaseSettings {
  allowed_tables: string[];
}

ErrorResponse

Standard error response.

interface ErrorResponse {
  error: string;
  message: string;
  details?: Record<string, any>;
  status: "error";
}

PaginatedResponse

Paginated list response.

interface PaginatedResponse<T> {
  data: T[];
  pagination: Pagination;
}

interface Pagination {
  page: number;
  limit: number;
  total: number;
  pages: number;
}

ModelInfo

Model information from /api/llm/models.

interface ModelInfo {
  id: string;
  name: string;
  provider: string;
  description: string;
  tier: "flagship" | "standard" | "economical";
  context: string;
  pricing: Pricing;
  capabilities: string[];
  performance: Performance;
  auto_routing_enabled: boolean;
}

interface Pricing {
  input: number;   // Cost per 1M tokens
  output: number;  // Cost per 1M tokens
}

interface Performance {
  latency: number;   // 1-10 scale
  quality: number;   // 1-10 scale
  cost: number;      // 1-10 scale
}

TelemetryMetrics

Aggregated metrics response.

interface TelemetryMetrics {
  totalRequests: number;
  totalTokens: number;
  totalCost: number;
  averageLatency: number;
  successRate: number;
  topModels: ModelStats[];
  topAgents: AgentStats[];
  costByProvider: ProviderCost[];
  usageByHour: HourlyUsage[];
}

interface ModelStats {
  model: string;
  requests: number;
  cost: number;
}

interface AgentStats {
  agent_id: string;
  requests: number;
  cost: number;
}

interface ProviderCost {
  provider: string;
  cost: number;
  percentage: number;
}

interface HourlyUsage {
  hour: string;
  requests: number;
  cost: number;
}

HealthStatus

Health check response.

interface HealthStatus {
  status: "operational" | "degraded" | "down";
  uptime: string;
  uptimeSeconds: number;
  memory: MemoryStats;
  providers: ProviderStats;
  models: ModelStats;
  cache: CacheStats;
  timestamp: string;
}

interface MemoryStats {
  used: string;
  total: string;
  rss: string;
}

interface ProviderStats {
  available: string[];
  count: number;
}

interface CacheStats {
  size: number;
  valid: number;
  expired: number;
}