API Objects

Complete reference for all Converra API objects and their schemas.

Agent

An agent managed by Converra, defined by its system prompt, objectives, and LLM settings.

interface Agent {
  id: string;                    // Unique identifier (e.g., "agent_abc123")
  name: string;                  // Display name
  content: string;               // The agent's system prompt text
  llmModel: string;              // Target LLM model
  description?: string;          // Optional description
  tags?: string[];               // Organization tags
  status: AgentStatus;           // Current status
  isActive: boolean;             // Whether agent is active
  createdAt: string;             // ISO 8601 timestamp
  updatedAt: string;             // ISO 8601 timestamp
  lastOptimizedAt?: string;      // Last optimization timestamp
  conversationCount?: number;    // Total logged conversations
}

type AgentStatus = 'draft' | 'active' | 'deprecated' | 'archived';

Example

{
  "id": "agent_abc123",
  "name": "Customer Support Agent",
  "content": "You are a helpful customer support agent...",
  "llmModel": "gpt-4o",
  "description": "Main support chatbot",
  "tags": ["support", "production"],
  "status": "active",
  "isActive": true,
  "createdAt": "2025-01-15T10:00:00Z",
  "updatedAt": "2025-01-20T14:30:00Z",
  "lastOptimizedAt": "2025-01-18T09:00:00Z",
  "conversationCount": 1247
}

---

Conversation

A logged conversation between a user and AI assistant.

interface Conversation {
  id: string;                    // Unique identifier
  agentId: string;               // Associated agent ID
  content: string;               // Full conversation transcript
  status: ConversationStatus;    // Conversation status
  llmModel?: string;             // Model used (if different from agent)
  companyName?: string;          // Customer company name
  hasInsights: boolean;          // Whether insights were generated
  createdAt: string;             // ISO 8601 timestamp
}

type ConversationStatus = 'completed' | 'abandoned' | 'in_progress';

Transcript Format

The content field should contain alternating user and assistant messages:

User: First user message
Assistant: First assistant response
User: Second user message
Assistant: Second assistant response

Acceptable labels: User/Assistant, Human/AI, Customer/Agent

Example

{
  "id": "conv_xyz789",
  "agentId": "agent_abc123",
  "content": "User: I need help with my order\nAssistant: I'd be happy to help! What's your order number?\nUser: #12345\nAssistant: Found it! Your order ships tomorrow.",
  "status": "completed",
  "llmModel": "gpt-4o",
  "companyName": "Acme Corp",
  "hasInsights": true,
  "createdAt": "2025-01-20T14:30:00Z"
}

---

Optimization

An optimization run that tests variants to improve an agent.

interface Optimization {
  id: string;                    // Unique identifier
  agentId: string;               // Target agent ID
  status: OptimizationStatus;    // Current status
  mode: OptimizationMode;        // Optimization mode
  variantCount: number;          // Number of variants tested
  currentIteration?: number;     // Current iteration (if running)
  maxIterations?: number;        // Maximum iterations
  winningVariantId?: string;     // Winner (if completed)
  improvement?: number;          // Improvement percentage
  createdAt: string;             // ISO 8601 timestamp
  completedAt?: string;          // Completion timestamp
}

type OptimizationStatus =
  | 'queued'
  | 'starting'
  | 'running'
  | 'completed'
  | 'failed'
  | 'stopped';

type OptimizationMode = 'exploratory' | 'validation';

Mode Differences

Mode	Purpose	Speed	Rigor
exploratory	Quick iteration, testing ideas	Fast	Lower
validation	Statistical significance	Slower	Higher

Example

{
  "id": "opt_def456",
  "agentId": "agent_abc123",
  "status": "completed",
  "mode": "exploratory",
  "variantCount": 3,
  "currentIteration": 5,
  "maxIterations": 5,
  "winningVariantId": "var_winner123",
  "improvement": 23.5,
  "createdAt": "2025-01-20T10:00:00Z",
  "completedAt": "2025-01-20T10:45:00Z"
}

---

Variant

A variant of an agent's system prompt generated during optimization.

interface Variant {
  id: string;                    // Unique identifier
  optimizationId: string;        // Parent optimization ID
  agentId: string;               // Original agent ID
  name: string;                  // Variant name (e.g., "Variant A")
  content: string;               // Modified system prompt content
  isControl: boolean;            // Whether this is the baseline
  isWinner: boolean;             // Whether this variant won
  metrics: VariantMetrics;       // Performance metrics
  changes?: string;              // Summary of changes from original system prompt
}

interface VariantMetrics {
  overall: number;               // Overall score (0-100)
  taskCompletion: number;        // Task completion rate (0-100)
  quality: number;               // Response quality (0-100)
  clarity: number;               // Clarity score (0-100)
  sentiment: number;             // Sentiment score (0-100)
  conversationCount: number;     // Simulated conversations
}

Example

{
  "id": "var_winner123",
  "optimizationId": "opt_def456",
  "agentId": "agent_abc123",
  "name": "Variant B",
  "content": "You are a helpful customer support agent. Always greet the customer warmly...",
  "isControl": false,
  "isWinner": true,
  "metrics": {
    "overall": 87,
    "taskCompletion": 89,
    "quality": 85,
    "clarity": 88,
    "sentiment": 86,
    "conversationCount": 15
  },
  "changes": "Added warm greeting, step-by-step instructions"
}

---

Insight

Performance insights for agents or conversations.

Agent Insights (Aggregated)

interface AgentInsights {
  agentId: string;
  period: string;                // e.g., "30d"
  metrics: {
    taskCompletion: number;      // Average task completion (0-100)
    sentiment: SentimentScore;   // Overall sentiment
    conversationCount: number;   // Total conversations
    averageTurns: number;        // Average conversation length
  };
  topics: string[];              // Common topics
  issues: string[];              // Identified issues
  recommendations: string[];     // Improvement suggestions
  generatedAt: string;           // ISO 8601 timestamp
}

type SentimentScore = 'positive' | 'neutral' | 'negative' | 'mixed';

Conversation Insights

interface ConversationInsights {
  conversationId: string;
  sentiment: SentimentScore;
  sentimentScore: number;        // Numeric score (0-1)
  taskCompleted: boolean;        // Whether task was completed
  topics: string[];              // Discussed topics
  summary: string;               // AI-generated summary
  issues: string[];              // Issues identified
  createdAt: string;             // ISO 8601 timestamp
}

Example (Conversation Insights)

{
  "conversationId": "conv_xyz789",
  "sentiment": "positive",
  "sentimentScore": 0.82,
  "taskCompleted": true,
  "topics": ["order status", "shipping"],
  "summary": "Customer inquired about order #12345. Agent provided shipping update. Customer satisfied.",
  "issues": [],
  "createdAt": "2025-01-20T14:35:00Z"
}

---

Webhook

A configured webhook endpoint.

interface Webhook {
  id: string;                    // Unique identifier
  url: string;                   // Endpoint URL (HTTPS)
  events: WebhookEvent[];        // Subscribed events
  active: boolean;               // Whether webhook is active
  description?: string;          // Optional description
  secret?: string;               // Signing secret (only on create)
  createdAt: string;             // ISO 8601 timestamp
}

type WebhookEvent =
  | 'optimization.completed'
  | 'optimization.failed'
  | 'agent.updated'
  | 'conversation.created'
  | 'insights.generated';

---

Pagination

All list endpoints use consistent pagination.

Request Parameters

Parameter	Type	Default	Description
limit	number	20	Max results per page (1-100)
offset	number	0	Number of results to skip

Response Format

interface PaginatedResponse<T> {
  data: T[];                     // Array of results
  pagination: {
    total: number;               // Total matching results
    limit: number;               // Current limit
    offset: number;              // Current offset
    hasMore: boolean;            // Whether more results exist
  };
}

Example

{
  "data": [
    { "id": "agent_1", "name": "Support Agent" },
    { "id": "agent_2", "name": "Sales Assistant" }
  ],
  "pagination": {
    "total": 25,
    "limit": 20,
    "offset": 0,
    "hasMore": true
  }
}

Pagination Examples

# First page
GET /api/v1/agents?limit=20

# Second page
GET /api/v1/agents?limit=20&offset=20

# Smaller page size
GET /api/v1/agents?limit=10&offset=0

---

Error Object

All errors follow a consistent format.

interface ErrorResponse {
  error: {
    code: ErrorCode;             // Machine-readable code
    message: string;             // Human-readable message
    details?: Record<string, string>; // Field-specific errors
  };
}

type ErrorCode =
  | 'UNAUTHORIZED'
  | 'FORBIDDEN'
  | 'NOT_FOUND'
  | 'VALIDATION_ERROR'
  | 'RATE_LIMIT_EXCEEDED'
  | 'INTERNAL_ERROR';

Example

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": {
      "name": "Required field",
      "llmModel": "Must be a supported model"
    }
  }
}

---

Timestamps

All timestamps use ISO 8601 format in UTC:

2025-01-20T14:30:00Z

When filtering by date, use the same format:

GET /api/v1/conversations?createdAfter=2025-01-01T00:00:00Z