Agent Chat API

The Agent Chat API provides AI-powered conversational capabilities using Claude.

POST /api/sdk/agent/chat

Send a message to the AI agent and receive a response.

Request

POST /api/sdk/agent/chat
Content-Type: application/json
X-Fig1-API-Key: your-api-key

Request Body

{
  // Required
  message: string;              // User's message

  // Optional - Session Management
  sessionId?: string;           // Continue existing conversation

  // Optional - AI Persona
  personaId?: string;           // Use specific AI persona

  // Optional - Context
  history?: Array<{             // Previous messages for context
    role: 'user' | 'assistant';
    content: string;
  }>;

  preferences?: {               // User preferences (per-request)
    [category: string]: {
      likes?: string[];
      dislikes?: string[];
      priceRange?: { min: number; max: number };
      restrictions?: string[];
    };
  };

  context?: {                   // Page/app context
    page?: string;              // Current page/screen
    products?: string[];        // Relevant product IDs
    referrer?: string;          // How user arrived
    [key: string]: any;         // Custom context data
  };
}

Response

{
  success: true;
  data: {
    message: string;            // AI response text
    sessionId: string;          // Session ID for continuity

    toolCalls?: Array<{         // If tools were used
      name: string;
      input: object;
      output: object;
    }>;

    actions?: Array<{           // Client actions (navigation, etc.)
      type: 'navigate' | 'open_url' | 'play_video' | 'show_product' | 'custom';
      payload: object;
      immediate?: boolean;
    }>;

    intent?: {                  // Extracted intent
      name: string;
      confidence: number;
    };

    metadata: {
      model: string;            // Model used
      tokensUsed: number;       // Total tokens consumed
      proxyLatencyMs: number;   // Request latency
    };
  };
}

Example: Basic Chat

curl -X POST https://app.fig1.ai/api/sdk/agent/chat \
  -H "Content-Type: application/json" \
  -H "X-Fig1-API-Key: fig1_sdk_abc123" \
  -d '{
    "message": "What red wines pair well with steak?"
  }'

Response:

{
  "success": true,
  "data": {
    "message": "For steak, I recommend bold red wines with good tannin structure:\n\n1. **Cabernet Sauvignon** - The classic choice\n2. **Malbec** - Softer tannins with plum notes\n3. **Syrah** - Peppery and robust\n\nWould you like specific bottle recommendations?",
    "sessionId": "sess_abc123def456",
    "metadata": {
      "tokensUsed": 156,
      "proxyLatencyMs": 1234
    }
  }
}

Example: With Session

curl -X POST https://app.fig1.ai/api/sdk/agent/chat \
  -H "Content-Type: application/json" \
  -H "X-Fig1-API-Key: fig1_sdk_abc123" \
  -d '{
    "message": "Yes, show me Cabernet options under $50",
    "sessionId": "sess_abc123def456"
  }'

Example: With Preferences

curl -X POST https://app.fig1.ai/api/sdk/agent/chat \
  -H "Content-Type: application/json" \
  -H "X-Fig1-API-Key: fig1_sdk_abc123" \
  -d '{
    "message": "Recommend a wine for tonight",
    "preferences": {
      "wine": {
        "likes": ["full-bodied", "oaky"],
        "dislikes": ["sweet"],
        "priceRange": { "min": 20, "max": 75 }
      }
    }
  }'

Error Responses

Missing Message (400)

{
  "success": false,
  "error": "message is required"
}

Invalid API Key (401)

{
  "success": false,
  "error": "Invalid API key"
}

Service Unavailable (503)

{
  "success": false,
  "error": "Agent service not configured"
}

Best Practices

1. Use session IDs for multi-turn conversations
2. Pass preferences per-request rather than storing user data
3. Include relevant context to improve response quality
4. Handle actions returned in responses for navigation/UI triggers
5. Use webhook tools to extend agent capabilities with your APIs