Fathom Upgrade & Migration

Overview

Fathom is an AI meeting assistant that records, transcribes, and summarizes meetings. The API operates under /external/v1 and exposes endpoints for meetings, transcripts, and action items. Tracking API changes is important because Fathom iterates rapidly on transcript schema fields (speaker attribution, sentiment data, highlight clips) and breaking changes to response shapes can silently corrupt downstream integrations that consume meeting data for CRM sync or analytics pipelines.

Version Detection

const FATHOM_BASE = "https://api.fathom.video/external/v1";

interface FathomVersionCheck {
  apiVersion: string;
  knownFields: string[];
  detectedFields: string[];
  newFields: string[];
  removedFields: string[];
}

async function detectFathomApiChanges(apiKey: string): Promise<FathomVersionCheck> {
  const res = await fetch(`${FATHOM_BASE}/meetings?limit=1`, {
    headers: { Authorization: `Bearer ${apiKey}` },
  });
  const data = await res.json();
  const knownFields = ["id", "title", "created_at", "duration", "attendees", "transcript_url"];
  const detectedFields = data.meetings?.[0] ? Object.keys(data.meetings[0]) : [];
  return {
    apiVersion: res.headers.get("x-api-version") ?? "v1",
    knownFields,
    detectedFields,
    newFields: detectedFields.filter((f) => !knownFields.includes(f)),
    removedFields: knownFields.filter((f) => !detectedFields.includes(f)),
  };
}

Migration Checklist

• Review Fathom product updates for API changes and deprecations
• Audit all endpoints referencing /external/v1 in codebase
• Verify meeting list response schema matches current field expectations
• Check transcript endpoint for new speaker attribution fields
• Validate action item extraction format (structured vs. plain text)
• Update OAuth token refresh flow if auth endpoints changed
• Test webhook payloads for meeting completion events
• Verify pagination parameters (cursor vs. offset) are current
• Update CRM sync mappings if meeting metadata fields renamed
• Run integration tests against Fathom sandbox environment

Schema Migration

// Fathom transcript response evolved: flat text → speaker-attributed segments
interface OldTranscript {
  meeting_id: string;
  text: string;
  created_at: string;
}

interface NewTranscript {
  meeting_id: string;
  segments: Array<{
    speaker: string;
    text: string;
    start_time: number;
    end_time: number;
    confidence: number;
  }>;
  summary: string;
  action_items: Array<{ text: string; assignee?: string }>;
  created_at: string;
}

function migrateTranscript(old: OldTranscript): NewTranscript {
  return {
    meeting_id: old.meeting_id,
    segments: [{ speaker: "Unknown", text: old.text, start_time: 0, end_time: 0, confidence: 1.0 }],
    summary: "",
    action_items: [],
    created_at: old.created_at,
  };
}

Rollback Strategy

class FathomClient {
  private baseUrl: string;
  private fallbackUrl: string;

  constructor(private apiKey: string) {
    this.baseUrl = "https://api.fathom.video/external/v1";
    this.fallbackUrl = "https://api.fathom.video/external/v1"; // same base, version in path
  }

  async getMeetings(limit = 20): Promise<any> {
    try {
      const res = await fetch(`${this.baseUrl}/meetings?limit=${limit}`, {
        headers: { Authorization: `Bearer ${this.apiKey}` },
      });
      if (!res.ok) throw new Error(`Fathom API ${res.status}`);
      return await res.json();
    } catch (err) {
      console.warn("Primary endpoint failed, attempting fallback:", err);
      const res = await fetch(`${this.fallbackUrl}/meetings?limit=${limit}`, {
        headers: { Authorization: `Bearer ${this.apiKey}`, Accept: "application/json; version=legacy" },
      });
      return await res.json();
    }
  }
}

Error Handling

Resources

• Fathom Product Updates
• Fathom API Documentation

Next Steps

For CI pipeline integration, see fathom-ci-integration.