Settings API

Configure optimization and general settings for your account.

Get Settings

Retrieve your current settings.

GET /api/v1/settings

Response

{
  "general": {
    "name": "My Company",
    "industry": "SaaS",
    "preferredLLM": "gpt-4o",
    "objectives": "Improve customer support efficiency",
    "kpis": "Reduce response time, increase satisfaction",
    "insightRequirements": "Focus on user engagement metrics",
    "excludedDataAndTopics": "Sensitive PII, competitor mentions"
  },
  "optimization": {
    "optimizationStrategy": "exploratory",
    "variantsPerGeneration": 3,
    "deploymentMode": "manual",
    "maxIterations": 10,
    "simulation": {
      "personaCount": 5,
      "scenariosPerSimulation": 3,
      "maxTurns": 10,
      "confidenceMode": "moderate"
    }
  }
}

---

Update Settings

Update specific settings. Only provided fields are updated.

PATCH /api/v1/settings

Request Body

{
  "general": {
    "preferredLLM": "claude-3-5-sonnet"
  },
  "optimization": {
    "variantsPerGeneration": 5,
    "simulation": {
      "personaCount": 10
    }
  }
}

Response

{
  "success": true,
  "settings": {
    "general": { ... },
    "optimization": { ... }
  }
}

---

Settings Reference

General Settings

Field	Type	Description
name	string	Organization name
industry	string	Your industry/vertical (e.g., "SaaS", "E-commerce")
preferredLLM	string	Default LLM model for new prompts
objectives	string	Business objectives for optimization
kpis	string	Key performance indicators to optimize for
insightRequirements	string	What insights matter most
excludedDataAndTopics	string	Data/topics to exclude from analysis

Optimization Settings

Field	Type	Default	Description
optimizationStrategy	string	exploratory	Default mode: exploratory or validation
variantsPerGeneration	number	3	Variants per optimization (1-5)
deploymentMode	string	manual	manual or semi-automatic
maxIterations	number	10	Maximum optimization iterations

Simulation Settings

Field	Type	Default	Description
personaCount	number	5	Personas per simulation
scenariosPerSimulation	number	3	Scenarios per simulation
maxTurns	number	10	Max conversation turns
confidenceMode	string	moderate	low, moderate, or high

---

Optimization Strategies

Exploratory Mode

Best for quick iteration and testing ideas:

• Faster execution (fewer simulations)
• Lower statistical rigor
• Good for initial optimization

{
  "optimization": {
    "optimizationStrategy": "exploratory",
    "variantsPerGeneration": 3
  }
}

Validation Mode

Best for production-critical prompts:

• More thorough testing
• Higher statistical confidence
• Slower but more reliable results

{
  "optimization": {
    "optimizationStrategy": "validation",
    "variantsPerGeneration": 3,
    "simulation": {
      "confidenceMode": "high"
    }
  }
}

---

Deployment Modes

Manual

Review and approve all changes before deployment:

{
  "optimization": {
    "deploymentMode": "manual"
  }
}

Workflow:

1. Optimization completes
2. Review results in dashboard
3. Click "Apply" to deploy winner

Semi-Automatic

Automatically stage winning variants for review:

{
  "optimization": {
    "deploymentMode": "semi-automatic"
  }
}

Workflow:

1. Optimization completes
2. Winner is staged (not live)
3. Approve to make live

---

SDK Usage

// Get settings
const settings = await converra.settings.get();
console.log('Strategy:', settings.optimization.optimizationStrategy);

// Update settings
await converra.settings.update({
  optimization: {
    variantsPerGeneration: 5,
    simulation: {
      personaCount: 10
    }
  }
});

---

Sync from Website

Automatically extract business context from your website:

POST /api/v1/settings/sync-context

Request Body

{
  "url": "https://example.com",
  "overwrite": false
}

Parameters

Field	Type	Default	Description
url	string	required	Your company website URL
overwrite	boolean	false	Overwrite existing values

Response

{
  "success": true,
  "extracted": {
    "industry": "SaaS",
    "objectives": "Help developers ship faster"
  }
}

This uses AI to analyze your website and populate:

• Industry
• Business objectives
• KPIs

---

Error Responses

Invalid Settings

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid settings",
    "details": {
      "optimization.variantsPerGeneration": "Must be between 1 and 5"
    }
  }
}

Unknown Field

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Unknown field: optimization.unknownField"
  }
}

---

Related

• Account & Usage - Plan limits and usage stats
• Webhooks - Event notifications