Fathom Context API Documentation

Overview

The Context API provides intelligent conversation tracking, resolution management, and similarity search capabilities. It uses a graph-based knowledge system to understand customer issues, track solution attempts, and provide recommendations based on historical data.

Base URL

https://fathom-ai-465017.el.r.appspot.com/api/v1/context

Authentication

All endpoints require authentication using an API key:

X-API-Key: your-api-key

Endpoints

1. Track Conversation

Track customer conversations incrementally and build knowledge about issues and solutions. This endpoint accepts incremental conversation updates (new messages only) and automatically identifies issue types, tracks solution attempts, updates success/failure statistics, and builds resolution patterns.

POST/track

Request Body

{
  "conversationId": "unique-conversation-id",
  "messages": [
    {
      "role": "user",
      "content": "My payment is being declined"
    },
    {
      "role": "assistant",
      "content": "I'll help you with that. Can you check if your card is expired?"
    }
  ],
  "userId": "optional-user-id"
}

Parameters

Parameter	Required	Description
conversationId	Yes	Unique identifier for the conversation
messages	Yes	Array of new messages to add (max 10 per request). Each message must have a `role` ("user" or "assistant") and `content` (string).
userId	No	Identifier for the user

Response

{
  "success": true,
  "message": "Conversation tracking initiated",
  "data": {
    "conversationId": "unique-conversation-id",
    "messagesReceived": 2,
    "isIncremental": true
  },
  "requestId": "req-123"
}

Usage Example

curl -X POST https://fathom-ai-465017.el.r.appspot.com/api/v1/context/track \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{"conversationId": "conv-001","messages": [
      {"role": "user", "content": "My card keeps getting declined"},
      {"role": "assistant", "content": "Let me check that for you"},
      {"role": "assistant", "content": "I see the issue - your card appears to be expired"},
      {"role": "user", "content": "Oh! I didn't realize that"}
    ]
  }'

2. Mark Conversation as Resolved

Mark a conversation as resolved and optionally provide resolution notes. If no resolution notes are provided, the system will auto-generate them based on the conversation history.

POST/resolve

Request Body

{
  "conversationId": "unique-conversation-id",
  "resolutionNotes": "Customer's card was expired. Updated payment method resolved the issue."
}

Parameters

Parameter	Required	Description
conversationId	Yes	The conversation to mark as resolved
resolutionNotes	No	Custom resolution notes (auto-generated if not provided)

Response

{
  "success": true,
  "message": "Conversation marked as resolved",
  "data": {
    "conversationId": "unique-conversation-id",
    "resolutionNotes": "Customer's card was expired. Updated payment method resolved the issue."
  },
  "requestId": "req-124"
}

Usage Example

curl -X POST https://fathom-ai-465017.el.r.appspot.com/api/v1/context/resolve \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{"conversationId": "conv-001","resolutionNotes": "Resolved by updating expired card"
  }'

3. Find Similar Conversations

Search for similar conversations and get AI-powered recommendations based on historical patterns. Uses semantic search to find similar customer issues and provides actionable recommendations based on successful resolutions.

POST/similarity

Request Body

{
  "message": "Customer says their payment is not going through",
  "limit": 10
}

Parameters

Parameter	Required	Description
message	Yes	The customer message or issue description to search for
limit	No	Maximum number of results to return (default: 10, max: 100)

Response

{
  "success": true,
  "message": "Similar conversations retrieved successfully",
  "data": {
    "query": "Customer says their payment is not going through",
    "totalFound": 3,
    "conversations": [
      {
        "resolutionNotes": "Card was expired. Customer updated payment method.",
        "issueDetails": {
          "name": "payment_declined",
          "description": "Payment card declined by bank or payment processor",
          "occurrences": 45,
          "symptoms": [
            "card declined",
            "payment failed",
            "transaction rejected"
          ],
          "causes": [
            "expired card",
            "insufficient funds",
            "incorrect details"
          ]
        },
        "attemptedSolutions": [
          {
            "solution": "verify_card_details",
            "outcome": "success",
            "confidence": 0.85,
            "solutionDetails": {
              "description": "Guide customer to verify and update card information",
              "steps": [
                "Ask customer to check card expiration date",
                "Verify billing address matches bank records",
                "Check for sufficient funds"
              ],
              "prerequisites": [
                "Access to card",
                "Online account access"
              ],
              "successIndicators": [
                "Payment processes successfully"
              ],
              "stats": {
                "successCount": 38,
                "failureCount": 7,
                "totalAttempts": 45,
                "successRate": 0.84
              }
            }
          }
        ]
      }
    ],
    "recommendations": {
      "issueType": "payment_declined",
      "recommendedActions": [
        {
          "action": "verify_card_details",
          "successProbability": 0.84,
          "averageTimeToResolve": 5
        },
        {
          "action": "check_bank_restrictions",
          "successProbability": 0.72,
          "averageTimeToResolve": 10
        }
      ],
      "escalationPoint": 3,
      "historicalSuccessRate": 0.78,
      "similarResolutions": []
    }
  },
  "requestId": "req-125"
}

Usage Example

curl -X POST https://fathom-ai-465017.el.r.appspot.com/api/v1/context/similarity \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{"message": "My payment keeps failing","limit": 5
  }'

Rate Limits and Quotas

API usage is subject to your subscription plan limits:

Requests: Number of API calls per month
Tokens: Total tokens processed for AI operations
Retrievals: Number of similarity searches per month

When limits are exceeded, you'll receive a 429 status code with details about which limit was reached.

Error Responses

All errors follow this format:

{
  "success": false,
  "message": "Error description",
  "requestId": "req-123"
}

Common Error Codes

400: Bad Request - Invalid parameters
401: Unauthorized - Invalid or missing API key
404: Not Found - Conversation not found (for resolve endpoint)
409: Conflict - Conversation already resolved
429: Too Many Requests - Rate limit exceeded
500: Internal Server Error

Best Practices

Incremental Updates: Send only new messages to the track endpoint, not the entire conversation history
Conversation IDs: Use unique, persistent IDs for each conversation
Message Order: Maintain chronological order when sending messages
Resolution: Always mark conversations as resolved when completed for better pattern recognition
Error Handling: Implement exponential backoff for rate limit errors

Integration Example

Here's a complete example of tracking a conversation from start to resolution:

const API_KEY = 'your-api-key';
const BASE_URL = 'https://fathom-ai-465017.el.r.appspot.com/api/v1/context';

// 1. Start tracking a new conversation
async function trackConversation(conversationId, messages) {
  const response = await fetch(`${BASE_URL}/track`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': API_KEY
    },
    body: JSON.stringify({
      conversationId,
      messages
    })
  });
  return response.json();
}

// 2. Find similar issues for recommendations
async function findSimilar(message) {
  const response = await fetch(`${BASE_URL}/similarity`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': API_KEY
    },
    body: JSON.stringify({
      message,
      limit: 5
    })
  });
  return response.json();
}

// 3. Mark as resolved when done
async function resolveConversation(conversationId, notes) {
  const response = await fetch(`${BASE_URL}/resolve`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': API_KEY
    },
    body: JSON.stringify({
      conversationId,
      resolutionNotes: notes
    })
  });
  return response.json();
}

// Example workflow
async function handleCustomerIssue() {
  const conversationId = 'conv-' + Date.now();
  
  // Track initial messages
  await trackConversation(conversationId, [
    { role: 'user', content: 'My payment is failing' },
    { role: 'assistant', content: 'I can help with that' }
  ]);
  
  // Get recommendations
  const similar = await findSimilar('payment failing');
  console.log('Recommended solutions:', similar.data.recommendations);
  
  // Continue conversation...
  await trackConversation(conversationId, [
    { role: 'user', content: 'It was my expired card!' },
    { role: 'assistant', content: 'Great! Please update your card details' }
  ]);
  
  // Mark as resolved
  await resolveConversation(conversationId, 'Expired card - customer updated payment method');
}