Persona API Endpoints

Personas define the personality, skills, and model preferences of AI coding agents. Each persona can be assigned to workflow pipeline steps to control how agents behave during execution. The Persona API provides 9 endpoints for full lifecycle management.

Endpoints

GET /api/v1/personas/list

List all personas for the project.

curl -H "Authorization: Bearer cc_live_..." \
  https://<deployment>.convex.site/api/v1/personas/list

GET /api/v1/personas/get

Retrieve a single persona by ID.

Query parameters:

• id (required) -- The persona document ID

curl -H "Authorization: Bearer cc_live_..." \
  "https://<deployment>.convex.site/api/v1/personas/get?id=..."

GET /api/v1/personas/analytics

View analytics and usage statistics for a persona.

Query parameters:

• id (required) -- The persona document ID
• days (optional) -- Number of days to look back (default: all time)

POST /api/v1/personas/create

Create a new persona.

curl -X POST -H "Authorization: Bearer cc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Senior Architect",
    "description": "Expert in system design and code review",
    "type": "checker",
    "cliId": "claude_code",
    "model": "claude-sonnet-4-20250514",
    "thinkingEffort": "high",
    "instructions": "Focus on architecture, performance, and security.",
    "selectedSkills": ["code-review", "architecture"],
    "isEnabled": true
  }' \
  https://<deployment>.convex.site/api/v1/personas/create

Body fields:

• name (string, required) -- Display name
• description (string, optional) -- Human-readable description
• type (string, required) -- Persona type (e.g., designer, checker, optimizer)
• cliId (string, optional) -- CLI tool identifier
• model (string, optional) -- LLM model ID
• thinkingEffort (string, optional) -- Thinking effort level
• instructions (string, optional) -- Custom instructions
• selectedSkills (array, optional) -- Skill identifiers
• isEnabled (boolean, optional) -- Whether the persona is active

POST /api/v1/personas/update

Update an existing persona. All body fields except personaId are optional.

{
  "personaId": "...",
  "name": "Updated Name",
  "model": "claude-opus-4-20250514",
  "learningsEnabled": true
}

Additional fields: description, type, thinkingEffort, instructions, selectedSkills, isEnabled, learningsEnabled.

POST /api/v1/personas/delete

Delete a persona.

{ "personaId": "..." }

POST /api/v1/personas/duplicate

Create a copy of an existing persona.

{ "personaId": "..." }

POST /api/v1/personas/toggle

Toggle a persona's enabled/disabled state.

{ "personaId": "..." }

POST /api/v1/personas/bulk-delete

Delete multiple personas in one request.

{ "personaIds": ["id1", "id2", "id3"] }