F1
Fig1 SDK

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?: {                   // Conversation history
    messages: Array<{           // Previous messages
      role: 'user' | 'assistant';
      content: string;
    }>;
    summary?: string;           // AI-generated summary of older conversation
  };

  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 identifier
    referrer?: string;          // How user arrived

    // Product context
    productIds?: string[];      // Product IDs user is viewing

    // Content context (CMS items)
    contentIds?: string[];      // Content IDs user is viewing (exercises, articles, etc.)

    // Video context - for video training apps
    video?: {
      videoId: string;          // Video ID being watched
      currentTimestamp?: number;// Playback position in seconds
      title?: string;           // Video title for context
      duration?: number;        // Total duration in seconds
    };

    // User authentication context
    user?: {
      uid?: string;             // Firebase user ID
      isAuthenticated?: boolean;
      subscriptions?: string[]; // Active subscription IDs
    };

    // Custom app-specific data
    metadata?: Record<string, unknown>;
  };
}

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"
}

Example: Video Training with Content Context

Pass the exercise/content being viewed along with the current video position:

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 technique is being shown here?",
    "context": {
      "page": "/exercises/rear-naked-choke",
      "contentIds": ["content_exercise_123"],
      "video": {
        "videoId": "video_abc123",
        "currentTimestamp": 40,
        "title": "Rear Naked Choke Tutorial",
        "duration": 360
      }
    }
  }'

The AI agent will:

  1. Know the user is viewing the "Rear Naked Choke" exercise
  2. Understand they're at 0:40 of a 6-minute video
  3. Search video content near that timestamp for relevant techniques
  4. Provide context-aware answers referencing the specific moment

Response:

{
  "success": true,
  "data": {
    "message": "At 0:40, the instructor is demonstrating the hand placement for securing the rear naked choke. Notice how the choking arm wraps around the neck with the bicep aligned against one side of the throat and the forearm against the other.\n\nKey points at this moment:\n- Chin placement: Pull your chin down to your choking hand\n- Elbow position: Keep it directly under the opponent's chin\n- Hand grip: Grab your own bicep, not your forearm\n\nWould you like me to explain the next step at 0:55 where he shows the finishing squeeze?",
    "sessionId": "sess_video_training_123",
    "actions": [
      {
        "type": "play_video",
        "payload": {
          "videoId": "video_abc123",
          "timestamp": 55
        },
        "label": "Jump to finishing technique"
      }
    ]
  }
}

Example: E-commerce with Product Context

Pass products the user is viewing for personalized recommendations:

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": "Is this a good laptop for video editing?",
    "context": {
      "page": "/products/macbook-pro-16",
      "productIds": ["prod_macbook_16_m3"]
    },
    "preferences": {
      "computing": {
        "likes": ["performance", "portability"],
        "priceRange": { "min": 1500, "max": 3500 }
      }
    }
  }'

Example: Subscription-Aware Responses

Pass user context for content access control:

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": "Show me advanced techniques",
    "context": {
      "user": {
        "uid": "firebase_user_123",
        "isAuthenticated": true,
        "subscriptions": ["premium_monthly"]
      }
    }
  }'

The AI will only recommend content the user has access to based on their subscription.

Example: React Integration with Video Player

import { useState, useEffect } from 'react';

function VideoTrainingChat({ exercise, videoPlayer }) {
  const [sessionId, setSessionId] = useState(null);

  const sendMessage = async (message: string) => {
    // Get current video position from player
    const currentTime = videoPlayer.getCurrentTime();

    const response = await fetch('/api/chat', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        message,
        sessionId,
        context: {
          page: `/exercises/${exercise.slug}`,
          contentIds: [exercise._id],
          video: {
            videoId: exercise.videoId,
            currentTimestamp: currentTime,
            title: exercise.title,
            duration: videoPlayer.getDuration()
          }
        }
      })
    });

    const data = await response.json();
    setSessionId(data.data.sessionId);

    // Handle video navigation actions
    if (data.data.actions) {
      for (const action of data.data.actions) {
        if (action.type === 'play_video' && action.payload.timestamp) {
          videoPlayer.seekTo(action.payload.timestamp);
        }
      }
    }

    return data.data.message;
  };

  return (/* Chat UI */);
}

Example: Passing Custom Metadata

Use metadata for app-specific context:

const response = await chat({
  message: "Help me with this recipe",
  context: {
    contentIds: ["recipe_pasta_carbonara"],
    metadata: {
      // Recipe-specific context
      servings: 4,
      dietaryRestrictions: ["vegetarian"],
      availableIngredients: ["eggs", "parmesan", "pasta"],
      cookingSkillLevel: "intermediate",
      // Equipment available
      equipment: ["stovetop", "large-pot", "pan"]
    }
  }
});

Context Best Practices

Video Training Apps

  1. Always pass currentTimestamp - This allows the AI to reference specific moments
  2. Include contentIds - Link to the exercise/lesson being viewed
  3. Pass duration - Helps AI understand video progress (e.g., "you're halfway through")
  4. Update context on seek - When user scrubs the video, send updated timestamp

E-commerce Apps

  1. Pass productIds for the current page - AI can discuss specific products
  2. Include preferences - Price ranges, style preferences, restrictions
  3. Use metadata for filters - Currently applied filters, sort order, etc.

Content/Learning Apps

  1. Pass contentIds for current article/lesson
  2. Include user context for access control
  3. Track progress in metadata - Completion percentage, quiz scores, etc.

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
  6. Update context when state changes - Video position, page navigation, etc.
  7. Pass content IDs when user is viewing specific CMS items