fathom

# Fathom Access the Fathom API with managed OAuth authentication. Retrieve meeting recordings, transcripts, summaries, action items, and manage webhooks for notifications. ## Quick Start ```bash # List recent meetings python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/fathom/external/v1/meetings') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ## Base URL ``` https://gateway.maton.ai/fathom/{native-api-path} ``` Replace `{native-api-path}` with the actual Fathom API endpoint path. The gateway proxies requests to `api.fathom.ai` and automatically injects your OAuth token. ## Authentication All requests require the Maton API key in the Authorization header: ``` Authorization: Bearer $MATON_API_KEY ``` **Environment Variable:** Set your API key as `MATON_API_KEY`: ```bash export MATON_API_KEY="YOUR_API_KEY" ``` ### Getting Your API Key 1. Sign in or create an account at [maton.ai](https://maton.ai) 2. Go to [maton.ai/settings](https://maton.ai/settings) 3. Copy your API key ## Connection Management Manage your Fathom OAuth connections at `https://ctrl.maton.ai`. ### List Connections ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections?app=fathom&status=ACTIVE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ### Create Connection ```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'app': 'fathom'}).encode() req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ### Get Connection ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` **Response:** ```json { "connection": { "connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80", "status": "ACTIVE", "creation_time": "2025-12-08T07:20:53.488460Z", "last_updated_time": "2026-01-31T20:03:32.593153Z", "url": "https://connect.maton.ai/?session_token=...", "app": "fathom", "metadata": {} } } ``` Open the returned `url` in a browser to complete OAuth authorization. ### Delete Connection ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ### Specifying Connection If you have multiple Fathom connections, specify which one to use with the `Maton-Connection` header: ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/fathom/external/v1/meetings') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` If omitted, the gateway uses the default (oldest) active connection. ## API Reference ### Meetings #### List Meetings ```bash GET /fathom/external/v1/meetings ``` Query parameters: - `cursor` - Cursor for pagination - `created_after` - Filter to meetings created after this timestamp (e.g., `2025-01-01T00:00:00Z`) - `created_before` - Filter to meetings created before this timestamp - `calendar_invitees_domains[]` - Filter by company domains (pass once per value) - `calendar_invitees_domains_type` - Filter by invitee type: `all`, `only_internal`, `one_or_more_external` - `recorded_by[]` - Filter by email addresses of users who recorded meetings - `teams[]` - Filter by team names **Note:** OAuth users cannot use `include_transcript`, `include_summary`, `include_action_items`, or `include_crm_matches` parameters on this endpoint. Use the `/recordings/{recording_id}/summary` and `/recordings/{recording_id}/transcript` endpoints instead. **Example with filters:** ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/fathom/external/v1/meetings?created_after=2025-01-01T00:00:00Z&teams[]=Sales') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` **Response:** ```json { "limit": 10, "next_cursor": "eyJwYWdlX251bSI6Mn0=", "items": [ { "title": "Quarterly Business Review", "meeting_title": "QBR 2025 Q1", "recording_id": 123456789, "url": "https://fathom.video/xyz123", "share_url": "https://fathom.video/share/xyz123", "created_at": "2025-03-01T17:01:30Z", "scheduled_start_time": "2025-03-01T16:00:00Z", "scheduled_end_time": "2025-03-01T17:00:00Z", "recording_start_time": "2025-03-01T16:01:12Z", "recording_end_time": "2025-03-01T17:00:55Z", "calendar_invitees_domains_type": "one_or_more_external", "transcript_language": "en", "transcript": null, "default_summary": null, "action_items": null, "crm_matches": null, "recorded_by": { "name": "Alice Johnson", "email": "alice.johnson@acme.com", "email_domain": "acme.com", "team": "Marketing" }, "calendar_invitees": [ { "name": "Alice Johnson", "email": "alice.johnson@acme.com", "email_domain": "acme.com", "is_external": false, "matched_speaker_display_name": null } ] } ] } ``` ### Recordings #### Get Summary ```bash GET /fathom/external/v1/recordings/{recording_id}/summary ``` Query parameters: - `destination_url` - Optional URL for async callback. If provided, the summary will be POSTed to this URL. **Synchronous example:** ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/fathom/external/v1/recordings/123456789/summary') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` **Response:** ```json { "summary": { "template_name": "general", "markdown_formatted": "## Summary\n\nWe reviewed Q1 OKRs, identified budget risks, and agreed to revisit projections next month." } } ``` **Async example:** ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/fathom/external/v1/recordings/123456789/summary?destination_url=https://example.com/webhook') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` #### Get Transcript ```bash GET /fathom/external/v1/recordings/{recording_id}/transcript ``` Query parameters: - `destination_url` - Optional URL for async callback. If provided, the transcript will be POSTed to this URL. **Synchronous example:** ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/fathom/external/v1/recordings/123456789/transcript') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` **Response:** ```json { "transcript": [ { "speaker": { "display_name": "Alice Johnson", "matched_calendar_invitee_email": "alice.johnson@acme.com" }, "text": "Let's revisit the budget allocations.", "timestamp": "00:05:32" } ] } ``` ### Teams #### List Teams ```bash GET /fathom/external/v1/teams ``` Query parameters: - `cursor` - Cursor for pagination **Example:** ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/fathom/external/v1/teams') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` **Response:** ```json { "limit": 25, "next_cursor": null, "items": [ { "name": "Sales", "created_at": "2023-11-10T12:00:00Z" } ] } ``` ### Team Members #### List Team Members ```bash GET /fathom/external/v1/team_members ``` Query parameters: - `cursor` - Cursor for pagination - `team` - Team name to filter by **Example:** ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/fathom/external/v1/team_members?team=Sales')