Easy Data Import
(no code required)
Before you touch the SDK, you can get value from Converra by pointing it at your existing data - all from the Integrations page in the app.
This gives prompt engineers and PMs a way to diagnose issues and see improvement opportunities without waiting for a release cycle.
Paste Data
On the Integrations page, paste chat transcripts or logs directly into the app.
Converra parses prompts and conversations and prepares them for optimization.
You get immediate visibility into performance issues and opportunities.
Upload File
Upload .txt, .csv, .xlsx, or .zip files (up to 10MB each).
See how many prompts and conversations were processed.
Click straight into the resulting prompt records and insights.
Node.js SDK (server-side integration)
Use the official TypeScript SDK from your backend or worker processes.
npm install converraimport { 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.
MCP server for AI assistants
Attach Converra as an MCP server so tools like Claude or Cursor can manage optimizations on your behalf.
# Attach Converra to Claude Code
claude mcp add converra -- npx -y mcp-remote@latest https://converra.ai/api/mcp \
--header "Authorization:Bearer YOUR_API_KEY"Then you can ask your assistant:
- "List my prompts and show which ones are underperforming."
- "Optimize my onboarding prompt for task completion and clarity."
- "Compare these two prompts head-to-head and recommend a winner."
- "Analyze this prompt for weaknesses and edge cases."
Under the hood, the assistant calls tools like list_prompts, trigger_optimization, analyze_prompt, and run_head_to_head on your behalf.
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.
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:
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": "run_head_to_head",
"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, run_head_to_head, 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
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.