Personas API

Personas define how your AI assistant communicates—its voice, expertise, behavior, and specialization.

Application Types

Personas can be specialized for different use cases using the appType field:

Capability Tiers

Instead of selecting raw model names, choose a capability tier:

GET /api/sdk/personas

List all available personas.

Query Parameters

Example Request

curl -X GET "https://app.fig1.ai/api/sdk/personas?status=active" \
  -H "X-Fig1-API-Key: fig1_sdk_abc123"

Response

{
  "success": true,
  "data": [
    {
      "_id": "persona_coach",
      "name": "MMA Training Coach",
      "slug": "mma-coach",
      "description": "Expert MMA coach specializing in technique breakdown",
      "appType": "video-training",
      "capabilityTier": "smart",
      "isDefault": true,
      "expertise": ["MMA", "striking", "grappling"],
      "voice": {
        "tone": "friendly",
        "verbosity": "balanced",
        "formality": "neutral"
      },
      "behavior": {
        "showCitations": true,
        "proactiveEngagement": true
      },
      "videoConfig": {
        "domain": "MMA / Combat Sports",
        "skillLevels": ["beginner", "intermediate"],
        "coachingStyle": "encouraging",
        "timestampCitations": true,
        "techniqueHighlighting": true
      },
      "status": "active"
    }
  ]
}

GET /api/sdk/personas/:id

Get a single persona by ID or slug.

curl -X GET "https://app.fig1.ai/api/sdk/personas/mma-coach" \
  -H "X-Fig1-API-Key: fig1_sdk_abc123"

POST /api/sdk/personas

Create a new persona.

Request Body

{
  name: string;                    // Display name
  systemPrompt: string;            // Instructions for the AI

  // Optional
  slug?: string;                   // URL-friendly identifier
  description?: string;            // Human-readable description
  avatar?: string;                 // Avatar image URL
  isDefault?: boolean;             // Use as default persona
  appType?: 'general' | 'video-training' | 'product-catalog' | 'documentation' | 'custom';
  capabilityTier?: 'fast' | 'smart';  // AI capability level
  expertise?: string[];            // Areas of knowledge

  voice?: {
    tone: 'professional' | 'friendly' | 'casual' | 'formal' | 'playful' | 'empathetic';
    verbosity: 'concise' | 'balanced' | 'detailed';
    formality: 'formal' | 'neutral' | 'informal';
    personality?: string;          // Custom personality traits
  };

  behavior?: {
    reasoningEffort: 'minimal' | 'low' | 'medium' | 'high';
    showCitations: boolean;        // Include source citations
    proactiveEngagement: boolean;  // Suggest related topics
    askClarifyingQuestions: boolean;
    maxResponseLength?: number;    // Max tokens in response
  };

  // For video-training app type
  videoConfig?: {
    domain?: string;               // e.g., "MMA", "Cooking", "Music"
    skillLevels?: string[];        // e.g., ["beginner", "intermediate"]
    coachingStyle?: 'encouraging' | 'analytical' | 'strict' | 'custom';
    timestampCitations?: boolean;  // Include MM:SS timestamps
    techniqueHighlighting?: boolean;
    digestionInstructions?: string; // Instructions for video processor
    customCoachingPrompt?: string;  // For 'custom' coaching style
  };

  // For product-catalog app type
  catalogConfig?: {
    productCategories?: string[];
    comparisonBehavior?: 'detailed' | 'quick' | 'tabular';
    pricingDisplay?: 'always' | 'on-request' | 'ranges' | 'hidden';
    inventoryAwareness?: boolean;
    upsellGuidelines?: string;
  };

  // SDK-specific response settings
  sdkResponseConfig?: {
    citationStyle?: 'inline' | 'footer' | 'timestamps' | 'none';
    responseFormat?: 'conversational' | 'structured' | 'hybrid';
    includeSourceMetadata?: boolean;
    domainGlossary?: Record<string, string>;
  };

  welcomeMessage?: string;         // Initial greeting
  suggestedQuestions?: string[];   // Starter questions to show

  status?: 'draft' | 'active' | 'archived';
}

Example: Video Training Coach

curl -X POST https://app.fig1.ai/api/sdk/personas \
  -H "Content-Type: application/json" \
  -H "X-Fig1-API-Key: fig1_sdk_abc123" \
  -d '{
    "name": "MMA Training Coach",
    "appType": "video-training",
    "capabilityTier": "smart",
    "systemPrompt": "You are an experienced MMA coach who helps students learn techniques from video content.",
    "expertise": ["MMA", "striking", "grappling", "submissions"],
    "voice": {
      "tone": "friendly",
      "verbosity": "balanced"
    },
    "videoConfig": {
      "domain": "MMA / Combat Sports",
      "skillLevels": ["beginner", "intermediate", "advanced"],
      "coachingStyle": "encouraging",
      "timestampCitations": true,
      "techniqueHighlighting": true,
      "digestionInstructions": "Focus on identifying specific techniques, stances, and movements. Note training drills and combinations."
    },
    "welcomeMessage": "Ready to train? Ask me about any technique in the video!",
    "status": "active"
  }'

Example: Product Catalog Assistant

curl -X POST https://app.fig1.ai/api/sdk/personas \
  -H "Content-Type: application/json" \
  -H "X-Fig1-API-Key: fig1_sdk_abc123" \
  -d '{
    "name": "Shopping Assistant",
    "appType": "product-catalog",
    "capabilityTier": "fast",
    "systemPrompt": "You are a helpful shopping assistant who helps customers find the perfect products.",
    "expertise": ["products", "recommendations", "comparisons"],
    "catalogConfig": {
      "comparisonBehavior": "detailed",
      "pricingDisplay": "always",
      "inventoryAwareness": true,
      "upsellGuidelines": "Suggest complementary products when relevant, but do not be pushy."
    },
    "welcomeMessage": "Hi! Looking for something specific or want recommendations?",
    "status": "active"
  }'

PUT /api/sdk/personas/:id

Update an existing persona.

curl -X PUT https://app.fig1.ai/api/sdk/personas/persona_abc123 \
  -H "Content-Type: application/json" \
  -H "X-Fig1-API-Key: fig1_sdk_abc123" \
  -d '{
    "capabilityTier": "smart",
    "videoConfig": {
      "coachingStyle": "analytical"
    },
    "status": "active"
  }'

DELETE /api/sdk/personas/:id

Delete a persona.

curl -X DELETE https://app.fig1.ai/api/sdk/personas/persona_abc123 \
  -H "X-Fig1-API-Key: fig1_sdk_abc123"

GET /api/sdk/personas/templates

Get pre-built persona templates to help you get started quickly.

Query Parameters

Example Request

# Get all templates
curl -X GET "https://app.fig1.ai/api/sdk/personas/templates" \
  -H "X-Fig1-API-Key: fig1_sdk_abc123"

# Get video training templates
curl -X GET "https://app.fig1.ai/api/sdk/personas/templates?category=video-training" \
  -H "X-Fig1-API-Key: fig1_sdk_abc123"

# Get specific template
curl -X GET "https://app.fig1.ai/api/sdk/personas/templates?id=video-training-mma" \
  -H "X-Fig1-API-Key: fig1_sdk_abc123"

Response

{
  "success": true,
  "data": [
    {
      "id": "video-training-mma",
      "name": "MMA Training Coach",
      "description": "Expert coach for martial arts video training",
      "appType": "video-training",
      "category": "video-training",
      "tags": ["mma", "martial-arts", "coaching", "sports"],
      "systemPrompt": "You are an experienced MMA coach...",
      "videoConfig": {
        "domain": "MMA / Combat Sports",
        "skillLevels": ["beginner", "intermediate", "advanced"],
        "coachingStyle": "encouraging"
      }
    }
  ],
  "count": 9,
  "categories": ["video-training", "product-catalog", "documentation", "general"]
}

Using Personas in Chat

Pass the personaId when sending messages:

const response = await fetch('https://app.fig1.ai/api/sdk/agent/chat', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Fig1-API-Key': 'fig1_sdk_abc123'
  },
  body: JSON.stringify({
    message: 'Show me the jab technique',
    personaId: 'mma-coach'
  })
});

Voice Settings

Behavior Settings

Video Training Config

For personas with appType: "video-training":

Product Catalog Config

For personas with appType: "product-catalog":

Best Practices

1. Choose the right app type - Use specialized types for better results
2. Select appropriate capability tier - Use "smart" for complex queries, "fast" for simple ones
3. Write clear system prompts - Be specific about expertise and limitations
4. Use appropriate voice settings - Match your brand and audience
5. Configure domain-specific settings - Use videoConfig or catalogConfig for specialized personas
6. Start from templates - Use the templates API to get started quickly
7. Test thoroughly - Verify persona behavior before going live