Authenticated API

This endpoint requires a valid JWT Bearer token with content_creator roles. Accessible via the API gateway.

Creator Personas API

Create, train, and manage AI-powered digital personas for creators with customizable personalities and voice synthesis.

Overview

Attribute	Value
Base Path	`/api/v1/personas`
Authentication	Bearer Token
Required Roles	`content_creator`, `marketing`, `brand_manager`, `manager`, `tenant_admin`, `platform_admin`, `system_admin`, `super_admin`

Personas

List Personas

GET /api/v1/personas

Query Parameters

Parameter	Type	Description
`creator_id`	uuid	Filter by creator
`status`	string	`draft`, `training`, `active`, `archived`
`type`	string	`conversational`, `broadcast`, `interactive`

Response

{
  "personas": [
    {
      "id": "persona_001",
      "creator_id": "creator_abc",
      "name": "Chef Marco",
      "display_name": "Chef Marco's Kitchen",
      "avatar_url": "https://...",
      "type": "conversational",
      "status": "active",
      "personality": {
        "tone": "warm_professional",
        "expertise": ["italian_cuisine", "cooking_tips", "wine_pairing"],
        "interaction_style": "mentoring"
      },
      "voice": {
        "id": "voice_marco",
        "provider": "elevenlabs",
        "status": "ready"
      },
      "engagement": {
        "total_conversations": 15420,
        "avg_session_length_minutes": 8.5,
        "satisfaction_score": 4.7
      },
      "created_at": "2025-08-15T00:00:00Z",
      "last_active": "2026-01-24T18:30:00Z"
    }
  ],
  "total": 3
}

Create Persona

POST /api/v1/personas

Request Body

{
  "name": "Chef Marco",
  "display_name": "Chef Marco's Kitchen",
  "type": "conversational",
  "personality": {
    "base_tone": "warm",
    "formality": "professional",
    "humor_level": "moderate",
    "expertise_areas": ["italian_cuisine", "cooking_techniques"],
    "interaction_style": "mentoring",
    "response_length": "detailed"
  },
  "knowledge_base": {
    "training_documents": ["doc_001", "doc_002"],
    "content_sources": ["youtube_channel", "blog_posts"],
    "excluded_topics": ["politics", "religion"]
  },
  "guardrails": {
    "content_policy": "family_friendly",
    "response_boundaries": ["no_medical_advice", "no_financial_advice"],
    "escalation_triggers": ["emergency", "distress"]
  },
  "avatar_settings": {
    "upload_id": "upload_avatar_001",
    "background_color": "#F5E6D3"
  }
}

Response

{
  "id": "persona_002",
  "name": "Chef Marco",
  "status": "draft",
  "training_required": {
    "voice_samples": true,
    "knowledge_base": true,
    "personality_tuning": true
  },
  "next_steps": [
    {
      "step": "upload_voice_samples",
      "description": "Upload 3-5 minutes of voice samples",
      "endpoint": "/api/v1/personas/persona_002/voice/samples"
    },
    {
      "step": "add_training_content",
      "description": "Add content for knowledge base training",
      "endpoint": "/api/v1/personas/persona_002/training/content"
    }
  ],
  "created_at": "2026-01-24T19:30:00Z"
}

Get Persona

GET /api/v1/personas/{persona_id}

Response

{
  "id": "persona_001",
  "creator_id": "creator_abc",
  "name": "Chef Marco",
  "display_name": "Chef Marco's Kitchen",
  "bio": "Your personal Italian cooking mentor with 20 years of experience",
  "avatar_url": "https://...",
  "type": "conversational",
  "status": "active",
  "personality": {
    "base_tone": "warm",
    "formality": "professional",
    "humor_level": "moderate",
    "expertise_areas": ["italian_cuisine", "cooking_techniques", "wine_pairing"],
    "interaction_style": "mentoring",
    "response_length": "detailed",
    "greeting_style": "Welcome to my kitchen! What shall we cook today?",
    "signature_phrases": ["Perfetto!", "Let me show you a trick..."]
  },
  "voice": {
    "id": "voice_marco",
    "provider": "elevenlabs",
    "voice_id": "el_voice_xyz",
    "status": "ready",
    "settings": {
      "stability": 0.75,
      "similarity_boost": 0.80,
      "style": 0.35
    },
    "sample_url": "https://..."
  },
  "knowledge_base": {
    "document_count": 45,
    "last_trained": "2026-01-20T00:00:00Z",
    "topics": ["recipes", "techniques", "ingredients", "equipment"],
    "content_sources": [
      {"type": "youtube", "count": 120},
      {"type": "blog_posts", "count": 85},
      {"type": "recipes", "count": 200}
    ]
  },
  "guardrails": {
    "content_policy": "family_friendly",
    "response_boundaries": ["no_medical_advice", "no_financial_advice"],
    "escalation_triggers": ["emergency", "distress"],
    "blocked_topics": ["politics", "religion"]
  },
  "capabilities": {
    "text_chat": true,
    "voice_chat": true,
    "video_avatar": false,
    "image_generation": true,
    "real_time_streaming": true
  },
  "integrations": {
    "platforms": ["web", "mobile", "smart_speaker"],
    "channels": ["audience_shell", "embedded_widget"]
  },
  "metrics": {
    "total_conversations": 15420,
    "unique_users": 4250,
    "avg_session_length_minutes": 8.5,
    "satisfaction_score": 4.7,
    "response_latency_p95_ms": 850,
    "messages_today": 342
  },
  "monetization": {
    "enabled": true,
    "model": "subscription",
    "tiers": ["free", "premium"]
  },
  "created_at": "2025-08-15T00:00:00Z",
  "updated_at": "2026-01-24T00:00:00Z"
}

Update Persona

PUT /api/v1/personas/{persona_id}

Delete Persona

DELETE /api/v1/personas/{persona_id}

Voice Configuration

Upload Voice Samples

POST /api/v1/personas/{persona_id}/voice/samples

Request (multipart/form-data)

file: voice_sample.mp3
description: "Introduction monologue"
duration_seconds: 45

Response

{
  "sample_id": "sample_001",
  "status": "processing",
  "duration_seconds": 45,
  "quality_check": {
    "status": "pending",
    "estimated_completion": "2026-01-24T19:35:00Z"
  }
}

Start Voice Training

POST /api/v1/personas/{persona_id}/voice/train

Request Body

{
  "provider": "elevenlabs",
  "settings": {
    "stability": 0.75,
    "similarity_boost": 0.80,
    "style": 0.35,
    "use_speaker_boost": true
  },
  "sample_ids": ["sample_001", "sample_002", "sample_003"]
}

Response

{
  "training_job_id": "train_voice_001",
  "status": "queued",
  "estimated_duration_minutes": 15,
  "webhook_url": "https://..."
}

Get Voice Status

GET /api/v1/personas/{persona_id}/voice

Response

{
  "voice_id": "voice_marco",
  "provider": "elevenlabs",
  "status": "ready",
  "quality_score": 0.92,
  "samples_used": 5,
  "total_duration_minutes": 4.5,
  "settings": {
    "stability": 0.75,
    "similarity_boost": 0.80,
    "style": 0.35
  },
  "preview_url": "https://...",
  "created_at": "2025-08-15T00:00:00Z",
  "last_updated": "2026-01-15T00:00:00Z"
}

Synthesize Speech

POST /api/v1/personas/{persona_id}/voice/synthesize

Request Body

{
  "text": "Welcome to my kitchen! Today we're making fresh pasta from scratch.",
  "output_format": "mp3",
  "settings": {
    "stability": 0.75,
    "speed": 1.0
  }
}

Response

{
  "audio_url": "https://...",
  "duration_seconds": 5.2,
  "characters_used": 68,
  "cost": {
    "credits": 68,
    "remaining": 9932
  }
}

Personality Training

Add Training Content

POST /api/v1/personas/{persona_id}/training/content

Request Body

{
  "content_type": "youtube_video",
  "source_url": "https://youtube.com/watch?v=...",
  "metadata": {
    "title": "Perfect Pasta Dough",
    "topics": ["pasta", "technique"]
  },
  "processing": {
    "extract_transcript": true,
    "extract_knowledge": true,
    "learn_style": true
  }
}

Start Personality Training

POST /api/v1/personas/{persona_id}/training/start

Request Body

{
  "training_type": "full",
  "content_ids": ["content_001", "content_002"],
  "personality_adjustments": {
    "increase_warmth": true,
    "more_detailed_explanations": true
  }
}

Response

{
  "training_job_id": "train_personality_001",
  "status": "in_progress",
  "progress": 0,
  "stages": [
    {"stage": "content_analysis", "status": "in_progress"},
    {"stage": "knowledge_extraction", "status": "pending"},
    {"stage": "style_learning", "status": "pending"},
    {"stage": "model_fine_tuning", "status": "pending"},
    {"stage": "validation", "status": "pending"}
  ],
  "estimated_completion": "2026-01-24T21:00:00Z"
}

Get Training Status

GET /api/v1/personas/{persona_id}/training/status

Persona Testing

Test Conversation

POST /api/v1/personas/{persona_id}/test

Request Body

{
  "message": "How do I make the perfect risotto?",
  "include_voice": true,
  "test_mode": true
}

Response

{
  "response": {
    "text": "Ah, risotto! The secret is patience and constant stirring. Let me walk you through my technique...",
    "voice_url": "https://...",
    "latency_ms": 650
  },
  "evaluation": {
    "on_brand": true,
    "tone_match": 0.95,
    "expertise_demonstrated": true,
    "guardrails_passed": true
  },
  "suggestions": []
}

Analytics

Get Persona Analytics

GET /api/v1/personas/{persona_id}/analytics

Query Parameters

Parameter	Type	Description
`period`	string	`day`, `week`, `month`
`metrics`	string[]	Specific metrics to include

Response

{
  "period": "week",
  "engagement": {
    "total_conversations": 2450,
    "unique_users": 890,
    "returning_users": 520,
    "avg_session_length_minutes": 8.5,
    "messages_per_session": 12.3
  },
  "satisfaction": {
    "avg_rating": 4.7,
    "ratings_count": 450,
    "sentiment_distribution": {
      "positive": 0.82,
      "neutral": 0.15,
      "negative": 0.03
    }
  },
  "performance": {
    "avg_response_latency_ms": 750,
    "p95_latency_ms": 1200,
    "error_rate": 0.002,
    "escalation_rate": 0.01
  },
  "content": {
    "top_topics": [
      {"topic": "pasta_recipes", "count": 450},
      {"topic": "cooking_techniques", "count": 380},
      {"topic": "ingredient_substitutions", "count": 290}
    ],
    "unanswered_questions": 12
  },
  "monetization": {
    "revenue": 2450.00,
    "conversions": 45,
    "conversion_rate": 0.05
  }
}

Webhooks

Event	Description
`persona.created`	New persona created
`persona.status_changed`	Persona status changed
`persona.training_complete`	Training finished
`persona.voice_ready`	Voice synthesis ready
`persona.conversation_started`	User started conversation
`persona.escalation_triggered`	Escalation to human needed

Error Responses

Status	Code	Description
400	`insufficient_voice_samples`	Need more voice samples
400	`training_in_progress`	Training already running
404	`persona_not_found`	Persona ID not found
409	`voice_training_failed`	Voice training failed
422	`content_policy_violation`	Content violates policy
429	`voice_quota_exceeded`	Voice synthesis quota exceeded

Content API - Content management
Social Publishing API - Distribution
Knowledge Base API - RAG training

Overview​

Personas​

List Personas​

Create Persona​

Get Persona​

Update Persona​

Delete Persona​

Voice Configuration​

Upload Voice Samples​

Start Voice Training​

Get Voice Status​

Synthesize Speech​

Personality Training​

Add Training Content​

Start Personality Training​

Get Training Status​

Persona Testing​

Test Conversation​

Analytics​

Get Persona Analytics​

Webhooks​

Error Responses​

Related Documentation​

Overview

Personas

List Personas

Create Persona

Get Persona

Update Persona

Delete Persona

Voice Configuration

Upload Voice Samples

Start Voice Training

Get Voice Status

Synthesize Speech

Personality Training

Add Training Content

Start Personality Training

Get Training Status

Persona Testing

Test Conversation

Analytics

Get Persona Analytics

Webhooks

Error Responses

Related Documentation