Personas API

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

GET /api/sdk/personas

List all available personas.

Query Parameters

| Parameter | Type | Description | |-----------|------|-------------| | status | string | Filter by status (draft, active, archived) |

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_sales",
      "name": "Sales Assistant",
      "slug": "sales-assistant",
      "description": "Friendly sales expert focused on product recommendations",
      "avatar": "https://cdn.example.com/avatars/sales.png",
      "isDefault": false,
      "expertise": ["products", "pricing", "recommendations"],
      "voice": {
        "tone": "friendly",
        "verbosity": "balanced",
        "formality": "neutral"
      },
      "behavior": {
        "showCitations": true,
        "proactiveEngagement": true,
        "askClarifyingQuestions": true
      },
      "welcomeMessage": "Hi! I'm here to help you find the perfect product.",
      "suggestedQuestions": [
        "What's your best-selling product?",
        "Help me find something for a gift",
        "What's on sale right now?"
      ],
      "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/sales-assistant" \
  -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
  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?: {
    showCitations: boolean;        // Include source citations
    proactiveEngagement: boolean;  // Suggest related topics
    askClarifyingQuestions: boolean;
    maxResponseLength?: number;    // Max tokens in response
  };

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

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

Example

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": "Technical Support",
    "systemPrompt": "You are a technical support specialist. Help users troubleshoot issues with our software. Be patient and thorough. Always ask clarifying questions before providing solutions.",
    "expertise": ["troubleshooting", "software", "technical"],
    "voice": {
      "tone": "professional",
      "verbosity": "detailed",
      "formality": "neutral"
    },
    "behavior": {
      "showCitations": true,
      "askClarifyingQuestions": true
    },
    "welcomeMessage": "Hi! I'\''m here to help with any technical issues.",
    "suggestedQuestions": [
      "I'\''m having trouble logging in",
      "The app is running slowly",
      "How do I export my data?"
    ],
    "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 '{
    "welcomeMessage": "Hello! How can I assist you today?",
    "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"

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: 'I need help with my order',
    personaId: 'persona_support'  // or use slug: 'technical-support'
  })
});

Voice Settings

| Setting | Options | Description | |---------|---------|-------------| | tone | professional, friendly, casual, formal, playful, empathetic | Overall communication style | | verbosity | concise, balanced, detailed | Response length preference | | formality | formal, neutral, informal | Language formality level |

Behavior Settings

| Setting | Type | Description | |---------|------|-------------| | showCitations | boolean | Include source references | | proactiveEngagement | boolean | Suggest related topics | | askClarifyingQuestions | boolean | Ask for more details | | maxResponseLength | number | Token limit for responses |

Best Practices

1. Write clear system prompts - Be specific about expertise and limitations
2. Use appropriate voice settings - Match your brand and audience
3. Add suggested questions - Help users get started
4. Test thoroughly - Verify persona behavior before going live
5. Create specialized personas - Different use cases benefit from focused expertise