API Reference

Complete reference for all SDK methods.

Prompts

prompts.list()

List all prompts.

const { data: prompts } = await converra.prompts.list();

prompts.get(id, options?)

Get a specific prompt (cached by default).

const prompt = await converra.prompts.get('prompt_123');

// Bypass cache
const fresh = await converra.prompts.get('prompt_123', { bypassCache: true });

prompts.create(data)

Create a new prompt.

const prompt = await converra.prompts.create({
  name: 'Customer Support',
  content: 'You are a helpful customer support agent...',
  description: 'Main support chatbot prompt',
  tags: ['support', 'production']
});

prompts.update(id, data)

Update an existing prompt.

await converra.prompts.update('prompt_123', {
  content: 'Updated prompt content...'
});

Conversations

conversations.create(data)

Log a conversation for insights and optimization.

await converra.conversations.create({
  promptId: 'prompt_123',
  content: `User: I need help with my order
Assistant: I'd be happy to help! Could you provide your order number?
User: It's #12345
Assistant: Found it! Your order is scheduled for delivery tomorrow.`,
  llmModel: 'gpt-4',
  status: 'completed'
});

conversations.getInsights(id)

Get insights for a specific conversation.

const insights = await converra.conversations.getInsights('conv_456');
console.log(insights.sentiment); // 'positive'
console.log(insights.topics);    // ['order tracking', 'delivery']

Optimizations

optimizations.trigger(data)

Start an optimization process.

const optimization = await converra.optimizations.trigger({
  promptId: 'prompt_123',
  mode: 'exploratory',      // 'validation' for statistical rigor
  variantCount: 3,
  intent: {
    targetImprovements: ['clarity', 'task completion'],
    hypothesis: 'Adding examples will improve understanding'
  }
});

optimizations.get(id)

Get optimization status and details.

const status = await converra.optimizations.get(optimization.id);
console.log(status.progress);

optimizations.getVariants(id)

Get variants being tested.

const variants = await converra.optimizations.getVariants(optimization.id);
variants.forEach(v => {
  console.log(`${v.name}: ${v.metrics?.lift}% lift`);
});

optimizations.applyVariant(id, variantId?)

Apply the winning variant (or a specific variant).

await converra.optimizations.applyVariant(optimization.id);

Insights

insights.forPrompt(id, options?)

Get aggregated insights for a prompt.

const insights = await converra.insights.forPrompt('prompt_123', {
  days: 30
});

console.log(`Task completion: ${insights.metrics.taskCompletionRate}%`);
console.log(`Avg sentiment: ${insights.metrics.avgSentiment}`);

insights.overall(options?)

Get insights across all prompts.

const overall = await converra.insights.overall({ days: 7 });

Personas

personas.list(options?)

List simulation personas.

const { data: personas } = await converra.personas.list({
  tags: ['enterprise', 'frustrated']
});

personas.create(data)

Create a custom persona.

await converra.personas.create({
  name: 'Impatient Executive',
  description: 'A busy C-level executive who values brevity...',
  tags: ['enterprise', 'impatient', 'executive']
});

Webhooks

webhooks.create(data)

Register a webhook endpoint.

const webhook = await converra.webhooks.create({
  url: 'https://your-app.com/webhooks/converra',
  events: ['optimization.completed', 'prompt.updated'],
  description: 'Production webhook'
});

// Save the secret!
console.log('Secret:', webhook.secret);

Cache

cache.invalidate(promptId)

Invalidate a cached prompt.

converra.cache.invalidate('prompt_123');

cache.invalidateAll()

Clear all cached prompts.

converra.cache.invalidateAll();

cache.stats()

Get cache statistics.

const stats = converra.cache.stats();
// { size: 5, enabled: true, ttl: 300000 }

Error Handling

import { Converra, ConverraError } from 'converra';

try {
  await converra.prompts.get('nonexistent');
} catch (error) {
  if (error instanceof ConverraError) {
    console.error(`Error ${error.code}: ${error.message}`);
    console.error(`Status: ${error.statusCode}`);
    console.error(`Details:`, error.details);
  }
}

TypeScript Types

import type {
  Prompt,
  Conversation,
  Optimization,
  WebhookPayload,
  WebhookEvent,
  PromptUpdatedPayload,
  OptimizationCompletedPayload,
} from 'converra';