API Reference

Complete reference for all SDK methods.

Client

wrap(client, options?)

Wrap an LLM client for automatic run capture and A/B testing.

const openai = converra.wrap(new OpenAI());
const anthropic = converra.wrap(new Anthropic());

// With explicit prompt ID (for dynamic prompts)
const openai = converra.wrap(new OpenAI(), { promptId: 'support-agent' });

Supports OpenAI, Anthropic, and their async variants. Returns the same client type — fully transparent.

trace(name?, sessionId?)

Create a trace context for multi-agent run tracking.

const result = await converra.trace('session-123').run(async () => {
  // All LLM calls inside are linked into one trace
  const r1 = await openai.chat.completions.create({...});
  const r2 = await openai.chat.completions.create({...});
  return r2;
});

createInterceptor(options?)

Create an interceptor for framework-specific middleware (e.g., Vercel AI SDK).

import { createConverraMiddleware } from 'converra/ai-sdk';

const interceptor = converra.createInterceptor({ promptId: 'p_123' });
const middleware = createConverraMiddleware(interceptor);

shutdown()

Flush pending data and shut down the transport. Call on process exit.

await converra.shutdown();

initSdk()

Eagerly load SDK configuration from the server. Optional — configuration loads lazily on first wrap() call.

await converra.initSdk();

verifyWebhookSignature(payload, signature, secret)

Verify a webhook signature manually.

const isValid = converra.verifyWebhookSignature(rawBody, signature, secret);

Traces

traces.create(data)

Ingest a trace with spans for automatic multi-agent analysis. Useful for sending traces from any source (OpenTelemetry, custom instrumentation).

const result = await converra.traces.create({
  traceId: 'trace-abc-123',
  spans: [
    {
      spanId: '1',
      name: 'Router',
      type: 'llm',
      input: '...',
      output: '...',
      startTime: new Date().toISOString(),
    },
    {
      spanId: '2',
      name: 'Sales Agent',
      type: 'llm',
      parentSpanId: '1',
      input: '...',
      output: '...',
      startTime: new Date().toISOString(),
    },
  ],
});

The server performs topology inference to detect routers vs responders, final-response agents, and step-level execution flow.

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 run for insights and optimization.

await converra.runs.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-4o',
  status: 'completed'
});

conversations.getInsights(id)

Get insights for a specific run.

const insights = await converra.runs.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';