API Reference

The Converra REST API allows you to programmatically manage agents, run optimizations, and log runs.

Base URL

https://converra.ai/api/v1

Authentication

All API requests require a Bearer token:

curl https://converra.ai/api/v1/agents \
  -H "Authorization: Bearer YOUR_API_KEY"

Get your API key from Integrations → API Keys inside your Converra workspace.

Endpoints

Agents

Method	Endpoint	Description
GET	/agents	List all agents
POST	/agents	Create an agent
GET	/agents/:id	Get an agent
PATCH	/agents/:id	Update an agent
GET	/agents/:id/insights	Get agent insights

Optimizations

Method	Endpoint	Description
GET	/optimizations	List optimizations
POST	/optimizations	Trigger optimization
GET	/optimizations/:id	Get optimization details
GET	/optimizations/:id/variants	Get variant details
POST	/optimizations/:id/apply	Apply winning variant
POST	/optimizations/:id/stop	Stop running optimization

Conversations

Method	Endpoint	Description
GET	/conversations	List runs
POST	/conversations	Log a run
GET	/conversations/:id	Get run details
GET	/conversations/:id/insights	Get run insights

Insights

Method	Endpoint	Description
GET	/agents/:id/insights	Get aggregated agent insights (includes fleet intelligence, business impact, issues)
GET	/conversations/:id/insights	Get run-level insights
POST	/conversations/:id/insights/regenerate	Regenerate insights for a run
POST	/agents/:id/insights/regenerate	Batch regenerate insights for all runs
GET	/agents/:id/step-failures	Get step failure aggregation (last 30 days)

Benchmarks

Method	Endpoint	Description
GET	/benchmarks	List benchmarks
POST	/benchmarks	Create a benchmark
GET	/benchmarks/:id	Get benchmark details
POST	/benchmarks/bulk	Bulk delete benchmarks (pass action and jobIds in body)

Account & Settings

Method	Endpoint	Description
GET	/settings	Get settings
PATCH	/settings	Update settings
GET	/account	Get account info
GET	/usage	Get usage stats
GET	/webhooks	List webhooks
POST	/webhooks	Create webhook
DELETE	/webhooks/:id	Delete webhook

Rate Limits

Rate limits vary by plan:

Plan	Requests/minute
Free	60
Pro	300
Enterprise	Custom

Additional limits:

• Concurrent optimizations: 10 per account

See Authentication for rate limit headers and handling.

Error Responses

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid"
  }
}

Next Steps

• Authentication - Auth guide with rate limits
• Agents API - Manage agents and get insights
• Optimizations API - Run and manage optimizations
• Runs API - Log and retrieve runs
• Settings API - Configure account settings