Persona Agents

Create and interview high-fidelity synthetic personas for market research, product testing, and audience analysis.

Overview

Persona agents are synthetic representations of target demographics. Each persona has a detailed background, personality traits, preferences, and memory — enabling realistic conversational interviews that produce actionable qualitative data.

All endpoints require authentication via the X-API-Key header.

Authentication

X-API-Key: pl_live_your_key_here

Generate an API key from your dashboard.

Endpoints

POST

/api/v1/personas

Create Persona

Create a new synthetic persona. Cost: $1.00 per persona.

Request Body

{
  "name": "Urban Tech Professional",
  "category": "technology",
  "demographics": {
    "age_range": "28-35",
    "location": "San Francisco, CA",
    "income_bracket": "high",
    "education": "bachelors"
  },
  "traits": ["early-adopter", "price-conscious", "brand-loyal"],
  "fidelity_tier": "premium"
}

Example Request

curl -X POST "https://sociologic.ai/api/v1/personas" \
  -H "X-API-Key: pl_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Urban Tech Professional",
    "category": "technology",
    "demographics": { "age_range": "28-35", "location": "San Francisco, CA" },
    "traits": ["early-adopter", "price-conscious"],
    "fidelity_tier": "premium"
  }'

Response

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "slug": "urban-tech-professional",
  "name": "Urban Tech Professional",
  "category": "technology",
  "fidelity_tier": "premium",
  "status": "ready",
  "created_at": "2026-05-01T12:00:00Z"
}

GET

/api/v1/personas

List Personas

List all personas in your account with optional filtering.

Query Parameters

category — filter by category

fidelity_tier — filter by tier (standard, enhanced, premium, ultra)

search — search in name and description

page — page number (default: 1)

per_page — results per page (1-100, default: 20)

Example Request

curl -X GET "https://sociologic.ai/api/v1/personas?category=technology&fidelity_tier=premium" \
  -H "X-API-Key: pl_live_your_key_here"

GET

/api/v1/personas/:slug

Get Persona Details

Retrieve full details for a specific persona by slug.

Path Parameters

slug — the persona's unique identifier (e.g., "urban-tech-professional")

Example Request

curl -X GET "https://sociologic.ai/api/v1/personas/urban-tech-professional" \
  -H "X-API-Key: pl_live_your_key_here"

POST

/api/v1/personas/:slug/interview

Interview Persona

Conduct a conversational interview with a persona. Cost: $0.65 per interview message.

Path Parameters

slug — the persona's unique identifier

Request Body

{
  "message": "What factors influence your purchasing decisions for new tech?",
  "conversation_id": "optional-uuid-to-continue-conversation",
  "conversation_history": [
    { "role": "user", "content": "Previous question" },
    { "role": "assistant", "content": "Previous response" }
  ],
  "stream": false,
  "include_memory": true
}

Example Request

curl -X POST "https://sociologic.ai/api/v1/personas/urban-tech-professional/interview" \
  -H "X-API-Key: pl_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"message": "What factors influence your purchasing decisions for new tech?"}'

Response

{
  "response": "I tend to look at three main things: reviews from people I trust...",
  "conversation_id": "c9bf9e57-1685-4c89-bafb-ff5af830be8a",
  "persona_slug": "urban-tech-professional",
  "tokens_used": 342,
  "memory_fragments_used": 4
}

MCP Access

All persona endpoints are also available as tools via the SocioLogic Signal Relay MCP server. After running sociologic install claude-code, your AI client can call persona tools directly.

# Available MCP tools:
sociologic_list_personas
sociologic_get_persona
sociologic_create_persona
sociologic_interview_persona

Back to API docs · Research API