Personas API

Manage custom personas and use them in chat completions.

Using Personas in Chat

Pass personas via the konnect.personas parameter in chat completions.

JSON

{
  "model": "konnect-ensemble",
  "messages": [{"role": "user", "content": "Your question"}],
  "konnect.pattern": "ensemble",
  "konnect.models": ["gpt-4o", "claude-sonnet-4-5-20250929"],
  "konnect.personas": [
    {"personaId": "technical_expert", "modelId": "gpt-4o"},
    {"personaId": "business_strategist", "modelId": "claude-sonnet-4-5-20250929"}
  ]
}

Persona Config Object

personaIdrequired

ID of a built-in or custom persona.

modelIdrequired

Model ID to use with this persona.

Built-in Persona IDs

ID	Name	Category
`default`	Default	General
`technical_expert`	Technical Expert	General
`business_strategist`	Business Strategist	General
`devils_advocate`	Devil's Advocate	General
`optimist`	Optimist	General
`pragmatist`	Pragmatist	General
`analyst`	Analyst	General
`cto`	CTO	Domain Expert
`cfo`	CFO	Domain Expert
`advocate`	Advocate	Debate
`critic`	Critic	Debate
`impartial_judge`	Judge	Debate
`attacker`	Attacker	Red Team
`defender`	Defender	Red Team

List Personas

GET/api/personas

Returns all built-in and custom personas available to the authenticated user.

Response

{
  "personas": [
    {
      "id": "technical_expert",
      "name": "Technical Expert",
      "description": "Implementation focus, best practices",
      "category": "general",
      "isBuiltIn": true
    },
    {
      "id": "my_custom_persona",
      "name": "My Custom Persona",
      "description": "Custom persona for my use case",
      "category": "custom",
      "isBuiltIn": false
    }
  ]
}

Create Persona

POST/api/personasPro

Create a custom persona. Requires Pro or Power tier.

Request Body

idrequired

Unique identifier (lowercase, underscores allowed).

namerequired

Display name for the persona.

descriptionoptional

Short description of the persona's focus.

systemPromptrequired

System prompt that defines the persona's behavior.

Example

curl -X POST https://api.konnect.ai/api/personas \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "security_auditor",
    "name": "Security Auditor",
    "description": "Security vulnerabilities and compliance",
    "systemPrompt": "You are a security auditor. Analyze all suggestions for security implications, identify potential vulnerabilities, and recommend security best practices."
  }'

Update Persona

PUT/api/personas/{persona_id}

Update a custom persona. Only custom personas can be modified.

Delete Persona

DELETE/api/personas/{persona_id}

Delete a custom persona. Built-in personas cannot be deleted.

Personas overview and built-in list Chat Completions API Using personas in Debate mode