Fathom API Ruby library

Fathom is an AI meeting assistant that records, transcribes, highlights, and summarizes your meetings so you can focus on the conversation.

This is a comprehensive Ruby gem for interacting with the Fathom API. This gem provides easy access to Fathom's REST API for managing meetings, recordings, teams, webhooks, and more.

Features

• 🔄 Automatic rate limiting with configurable retries
• 🛡️ Comprehensive error handling
• 📝 Full support for all the existing Fathom API resources
• 🎯 Simple and intuitive API
• ✅ Verified against official Fathom API documentation

Requirements

• Ruby >= 3.1.0

Installation

Add this line to your application's Gemfile:

gem'fathom-ruby'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install fathom-ruby

Configuration

Basic Setup

Configure the gem with your Fathom API key:

require'fathom'Fathom.api_key="your_api_key_here"

Configuration Options

Fathom.configuredo |config|
config.api_key="your_api_key_here"# Enable/disable automatic retries on rate limits (default: true)config.auto_retry=true# Maximum number of retry attempts (default: 3)config.max_retries=3# Enable debug logging (default: false)config.debug=Rails.env.development?# Enable HTTP request/response logging (default: false)config.debug_http=Rails.env.development?end

Rails Configuration

Create an initializer at config/initializers/fathom.rb:

require'fathom'Fathom.configuredo |config|
config.api_key=ENV['FATHOM_API_KEY']# ... rest of the settings (like above)end

Usage

📋 Important Notes:

• The Fathom API uses cursor-based pagination, not offset-based
• Response format is { items: [...] }, not { data: [...] }
• Team Members: No individual IDs - filter by team name instead
• Recordings: No list/retrieve endpoints - use specialized endpoints for summary/transcript

Meetings

List all meetings:

# Get all meetingsmeetings=Fathom::Meeting.all# With query parametersmeetings=Fathom::Meeting.all(cursor: "eyJwYWdlX251bSI6Mn0=",# Cursor-based paginationinclude_summary: true,# Include default_summaryinclude_transcript: true,# Include transcriptinclude_action_items: true,# Include action_itemsteams: ["Sales","Engineering"]# Filter by team names)# Filter by date rangemeetings=Fathom::Meeting.all(created_after: "2025-01-01T00:00:00Z",created_before: "2025-01-31T23:59:59Z")# Filter by calendar inviteesmeetings=Fathom::Meeting.all("calendar_invitees[]"=>"ceo@acme.com")

Access meeting data:

meeting=meetings.first# Basic fieldsputsmeeting.titleputsmeeting.recording_id# Embedded data (when requested with include_* params)putsmeeting.summary# Returns default_summary hashputsmeeting.summary["markdown_formatted"]putsmeeting.transcript# Returns transcript arrayputsmeeting.participants# Returns calendar_invitees arrayputsmeeting.action_items# Returns action_items array

Fetch recording data for a meeting:

meeting=meetings.first# Fetch summary from Recording APIifmeeting.recording?summary=meeting.fetch_summaryputssummary["template_name"]putssummary["markdown_formatted"]# Fetch transcript from Recording APItranscript=meeting.fetch_transcripttranscript.eachdo |segment|
puts"#{segment['speaker']['display_name']}: #{segment['text']}"endend

Recordings

Note: Recordings don't have standard list/retrieve endpoints. They're accessed via their specialized endpoints:

Get summary for a recording:

# Synchronous - returns summary immediatelysummary=Fathom::Recording.get_summary(123456789)putssummary["template_name"]# e.g., "general"putssummary["markdown_formatted"]# Formatted summary text

Get transcript for a recording:

# Synchronous - returns transcript immediatelytranscript=Fathom::Recording.get_transcript(123456789)transcript.eachdo |segment|
speaker=segment["speaker"]["display_name"]text=segment["text"]timestamp=segment["timestamp"]puts"[#{timestamp}] #{speaker}: #{text}"end

Async mode with webhooks:

# Async - sends result to your webhook URLFathom::Recording.get_summary(123456789,destination_url: "https://your-app.com/webhooks/summary")Fathom::Recording.get_transcript(123456789,destination_url: "https://your-app.com/webhooks/transcript")

Teams

List all teams:

teams=Fathom::Team.allteams.eachdo |team|
putsteam.nameputs"Created: #{team.created_at}"end

Get a specific team:

team=Fathom::Team.retrieve("team_id")putsteam.name

List team members:

team=Fathom::Team.retrieve("team_id")members=team.members# Automatically filters by team name# Or directly by team namemembers=Fathom::TeamMember.all(team: "Engineering")

Team Members

List all team members:

# List all team membersmembers=Fathom::TeamMember.allmembers.eachdo |member|
puts"#{member.name} (#{member.email})"puts"Created: #{member.created_at}"end

Filter by team name:

# Filter by specific team namemembers=Fathom::TeamMember.all(team: "Engineering")members.eachdo |member|
puts"#{member.name} - #{member.email}"end

Pagination with cursor:

# First pageresponse=Fathom::TeamMember.all(team: "Sales")# Next page (if cursor is available from API response)next_page=Fathom::TeamMember.all(team: "Sales",cursor: "next_cursor_value")

Note: Team members don't have individual IDs in the Fathom API. Use filtering instead of retrieving individual members.

Webhooks

List all webhooks:

webhooks=Fathom::Webhook.allwebhooks.eachdo |webhook|
puts"#{webhook.url}"puts" Includes transcript: #{webhook.include_transcript?}"puts" Includes summary: #{webhook.include_summary?}"puts" Active: #{webhook.active?}"end

Create a webhook:

webhook=Fathom::Webhook.create(url: "https://example.com/webhook",# Specify which recordings should trigger the webhook:# - my_recordings: Your own recordings# - shared_external_recordings: Recordings shared with you externally# - my_shared_with_team_recordings: Your recordings shared with your team# - shared_team_recordings: Team recordings shared with youtriggered_for: ["my_recordings","shared_external_recordings"],include_transcript: true,include_summary: true,include_action_items: true,include_crm_matches: false)putswebhook.idputswebhook.secretputswebhook.triggered_for# => ["my_recordings", "shared_external_recordings"]

Get a specific webhook:

webhook=Fathom::Webhook.retrieve("webhook_id")ifwebhook.active?puts"Webhook is active"end

Delete a webhook:

webhook=Fathom::Webhook.retrieve("webhook_id")webhook.delete

Check webhook configuration:

webhook=Fathom::Webhook.retrieve("webhook_id")puts"Active: #{webhook.active?}"puts"Triggered for: #{webhook.triggered_for.join(', ')}"puts"Includes transcript: #{webhook.include_transcript?}"puts"Includes summary: #{webhook.include_summary?}"puts"Includes action items: #{webhook.include_action_items?}"puts"Includes CRM matches: #{webhook.include_crm_matches?}"

Rate Limiting

The Fathom API has a rate limit of 60 requests per 60 seconds. This gem handles rate limiting automatically.

Automatic Retries (Default)

By default, the gem will automatically retry requests when rate limited:

Fathom.auto_retry=true# This is the defaultFathom.max_retries=3# Maximum retry attempts# Requests will automatically retry with exponential backoffmeetings=Fathom::Meeting.all

Manual Rate Limit Handling

Disable automatic retries and handle rate limits manually:

Fathom.auto_retry=falsebeginmeetings=Fathom::Meeting.allrescueFathom::RateLimitError=>e# Handle rate limit errorputs"Rate limited. Remaining: #{e.rate_limit_remaining}"puts"Reset in: #{e.rate_limit_reset} seconds"# Wait and retry manuallysleep(e.rate_limit_reset)retryend

Checking Rate Limit Info

Access rate limit information from any resource:

meetings=Fathom::Meeting.allrate_info=meetings.first.rate_limit_infoputs"Limit: #{rate_info[:limit]}"puts"Remaining: #{rate_info[:remaining]}"puts"Reset in: #{rate_info[:reset]} seconds"

Error Handling

The gem provides specific error classes for different scenarios:

beginmeeting=Fathom::Meeting.retrieve("invalid_id")rescueFathom::AuthenticationError=>e# 401 - Invalid API keyputs"Authentication failed: #{e.message}"rescueFathom::NotFoundError=>e# 404 - Resource not foundputs"Meeting not found: #{e.message}"rescueFathom::RateLimitError=>e# 429 - Rate limit exceededputs"Rate limited: #{e.message}"rescueFathom::BadRequestError=>e# 400 - Bad requestputs"Bad request: #{e.message}"rescueFathom::ForbiddenError=>e# 403 - Forbiddenputs"Access forbidden: #{e.message}"rescueFathom::ServerError=>e# 5xx - Server errorputs"Server error: #{e.message}"rescueFathom::Error=>e# Any other Fathom errorputs"Error: #{e.message}"end

All error objects include:

• message - Human-readable error message
• http_status - HTTP status code
• response - Raw response object

Dynamic Attribute Access

All resources support dynamic attribute access:

meeting=Fathom::Meeting.retrieve("meeting_id")# Access attributesmeeting.titlemeeting.summarymeeting["custom_field"]# Set attributesmeeting.title="New Title"meeting["custom_field"]="value"# Convert to hashmeeting.to_h# Convert to JSONmeeting.to_json

Debugging

Enable debug logging to see what's happening:

# Basic debug loggingFathom.debug=true# HTTP request/response loggingFathom.debug_http=true# Now all API calls will be loggedmeetings=Fathom::Meeting.all# [Fathom] Rate limit: 59/60, resets in 60s# [Fathom HTTP] GET https://api.fathom.ai/v1/meetings# [Fathom HTTP] Response: 200 OK

Testing live

Check Test Live API Readme for instructions to test the API using a real API Key.

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

Running Tests

bundle exec rspec

Running Rubocop

bundle exec rubocop

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/j4rs/fathom-ruby. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Fathom Ruby project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

Links

• Fathom API Documentation
• Gem Documentation
• GitHub Repository
• Bug Reports