Connect Converra to Your Stack

SDK — One Line Integration

Easiest

Zero-code setup via auto-instrumentation, or wrap individual clients for explicit control.

terminal
npm install converra    # TypeScript
pip install converra    # Python
auto-instrument.ts
# .env
CONVERRA_API_KEY=sk_...

// One line at app startup — patches all LLM clients
import 'converra/auto';

// Or with Node.js flag (zero code changes):
// node --import converra/auto server.js

Why SDK wrapping?

  • One line of code to integrate — wrap your existing client, no other changes.
  • Supports OpenAI, Anthropic, Vercel AI SDK, and LangChain.
  • Multi-agent tracing with automatic agent boundary detection.
  • Fail-safe: if Converra is down, your agent is completely unaffected.
  • Your API keys pass through to the provider — never stored by Converra.

Observability Connectors

If you already trace runs + feedback in your observability platform, Converra can import it directly.

LangSmith

by LangChain

Continuous sync from LangSmith. Trace all LLM runs, discover agent systems, and diagnose the weakest link.

Langfuse

Open source LLM observability

Continuous sync from Langfuse Cloud. Region selection (EU/US), project-scoped API keys.

How it works

1

Connect API key

2

Select workspace & project

3

Configure sync (hourly → daily)

4

Review diagnosed failures & fixes

Multi-agent traces are grouped into agent systems with path visualization and weakest-link scoring.

MCP Server

Recommended

Works with Cursor, Claude Code, Windsurf, and any MCP-compatible client. Just tell your AI assistant to install Converra.

Copy this to your AI assistant:

“Install the Converra MCP server, then help me upload my prompts and optimize them.”

After signing up, you'll get an API key to include in the prompt.

Example prompts to try:

“Analyze my support agent prompt and tell me what's weak”
“Run a head-to-head test between my current prompt and this variant”
“Show me insights from my last 30 days of conversations”
“Create 3 variants of this prompt and test which performs best”
View Docs
Paste / Upload

Easy Data Import

(no code required)

You can also get value from Converra by uploading your existing data directly from the Integrations page in the app.

Great for prompt engineers and PMs who want to diagnose issues and see improvement opportunities without waiting for a release cycle.

Paste Data

1

On the Integrations page, paste chat transcripts or logs directly into the app.

2

Converra parses prompts and conversations and prepares them for optimization.

3

You get immediate visibility into performance issues and opportunities.

Upload File

1

Upload .txt, .csv, .xlsx, or .zip files (up to 10MB each).

2

See how many prompts and conversations were processed.

3

Click straight into the resulting prompt records and insights.

Node.js SDK

Node.js SDK (server-side integration)

Use the official TypeScript SDK from your backend or worker processes.

terminal
npm install converra
sdk.ts
import { Converra } from "converra";

const converra = new Converra({
  apiKey: process.env.CONVERRA_API_KEY!,
  // baseUrl: "https://api.converra.io/v1", // optional override
  // timeout: 30000, // ms, optional
});

// Prompts
const { data: prompts } = await converra.prompts.list();
const prompt = await converra.prompts.get("prompt_123");
const newPrompt = await converra.prompts.create({
  name: "Customer Support Agent",
  content: "You are a helpful customer support agent...",
  objective: "Resolve customer issues efficiently while maintaining satisfaction",
  tags: ["support", "production"],
});
await converra.prompts.update(newPrompt.id, { status: "active" });

// Optimizations
const optimization = await converra.optimizations.trigger({
  promptId: newPrompt.id,
  mode: "exploratory",
  variantCount: 3,
});
const results = await converra.optimizations.getVariants(optimization.id);
await converra.optimizations.applyVariant(optimization.id);

// Conversations & insights
await converra.conversations.create({
  promptId: newPrompt.id,
  content: "...",
  status: "completed",
});
const promptInsights = await converra.insights.forPrompt(newPrompt.id, { days: 30 });

Great for

  • AI app developers embedding optimization into existing services.
  • Platform teams who prefer typed, versioned integration with their infra.
REST API

REST / JSON-RPC for any stack

Use JSON-RPC over HTTPS to call the same tools Converra exposes to MCP clients - from any language, any stack.

terminal
curl -X POST https://converra.ai/api/mcp \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "trigger_optimization",
      "arguments": {
        "promptId": "prompt_123",
        "variantCount": 3,
        "mode": "exploratory",
        "intent": {
          "targetImprovements": ["clarity", "task completion"],
          "variationDegree": "moderate"
        }
      }
    }
  }'

Head-to-head testing is also available:

terminal
curl -X POST https://converra.ai/api/mcp \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "simulate_ab_test",
      "arguments": {
        "baselinePrompt": "You are a helpful assistant.",
        "variantPrompt": "You are an expert who gives precise, actionable answers.",
        "personaCount": 3,
        "scenarioCount": 5
      }
    }
  }'

Perfect for polyglot environments and custom infra.

Available tools

Prompts

list_prompts, get_prompt_status, create_prompt, update_prompt

Optimization

trigger_optimization, get_optimization_details, apply_variant, stop_optimization

Simulation

analyze_prompt, simulate_prompt, simulate_ab_test, regression_test, list_personas

Account / insights

get_usage, get_insights, create_webhook, get_stream_url

SDK surface area

Converra's SDK is intentionally small and predictable:

Prompts

  • prompts.list({ page, perPage, status })
  • prompts.get(promptId)
  • prompts.create({ name, content, tags, objective, ... })
  • prompts.update(promptId, { content, status, ... })
  • prompts.delete(promptId)

Optimizations

  • optimizations.trigger(input: TriggerOptimizationInput)
  • optimizations.get(id)
  • optimizations.list({ promptId, status })
  • optimizations.stop(id, reason?)
  • optimizations.getVariants(id)
  • optimizations.applyVariant(id, variantId?)
  • optimizations.getStreamUrl(id)

Conversations & insights

  • conversations.create({ promptId, content, ... })
  • conversations.get(id)
  • conversations.list({ promptId, status, ... })
  • conversations.getInsights(id)
  • insights.forPrompt(promptId, { days })
  • insights.overall({ days })

Personas & Webhooks

  • personas.list({ tags, search, page, perPage })
  • personas.create({ name, description, tags })
  • webhooks.list({ isActive, page, perPage })
  • webhooks.create({ url, events, description? })
  • webhooks.delete(id)

Everything is fully typed with exported TypeScript interfaces.

Error handling

error-handling.ts
import { Converra, ConverraError } from "converra";

try {
  await converra.prompts.get("nonexistent_prompt");
} catch (error) {
  if (error instanceof ConverraError) {
    console.error(`${error.code} (${error.statusCode}): ${error.message}`);
    console.error("Details:", error.details);
    // error.code examples: TIMEOUT, NETWORK_ERROR, NOT_FOUND, UNAUTHORIZED, VALIDATION_ERROR
  } else {
    throw error;
  }
}

Requirements

  • Node.js 18+ for the SDK.
  • A Converra API key (generated from the Integrations page in the app).
  • For MCP / JSON-RPC: any environment that can make HTTPS requests.

Ready to integrate?

Sign up to get your API key and start shipping tested prompt fixes.

Start for free

Already have access? Login here