Fathom API

Everything the Fathom web app does, it does through this API. Create samples, upload reads, run analyses, and read results and artifacts from your own scripts and pipelines.

Authentication

Every call carries a bearer token in the Authorization header. There are two kinds:

API tokens (recommended)

In the app, open your account from the header (your email address) and create a token under API tokens. Give it a name and an expiry (30, 90 or 365 days, or none). The token starts with fthm_ and is shown once; copy it then. It works however you sign in to the app, including with Google or Microsoft.

TOKEN=fthm_...          # from Account → API tokens
curl -s https://app.fathomgenomics.com/api/account \
  -H "Authorization: Bearer $TOKEN"

• A token has the reach of your account, except that it cannot create, list or revoke tokens, link or unlink sign-in methods, connect or disconnect Box or S3, or buy credits. Those calls answer 403 {"code":"session_required"}; do them in the app.
• Revoke a token in the same place at any time; the next call with it fails immediately. The account page shows when each token was last used.
• Keep tokens secret: one lets its holder read everything in your account, upload reads and spend your credits on analyses. Fathom stores only a hash of it and can never show it again.

Session tokens

Accounts with a password can also sign in from a script. The answer is the same 30-day session token the web app uses; sign in again to get a new one (there is no refresh call).

curl -s https://app.fathomgenomics.com/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","password":"your-password"}'
# → {"token":"eyJhbGciOi...","user":{"user_id":"...","email":"...","credit_balance":2,...}}

With either kind, a missing or malformed header answers 401 {"error":"Unauthorized"}; an expired token 401 {"error":"Token expired"}; anything else invalid 401 {"error":"Invalid token"}.

Quickstart: upload paired reads and run a human pathogen analysis

The whole flow with curl and jq. Each step is documented in full further down.

API=https://app.fathomgenomics.com/api

# Your API token, from Account → API tokens in the app (or a session token from /api/auth/login)
TOKEN=fthm_...
AUTH="Authorization: Bearer $TOKEN"

# Create a sample (accession is your own identifier, unique within your account)
SAMPLE=$(curl -s $API/samples -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"accession":"RUN-2026-001","description":"nasopharyngeal swab"}' | jq -r .sample.sample_id)

# Upload a read file: presign → PUT the bytes → finalize. Repeat with asset_type fastq_r2 for R2.
FILE=reads_R1.fastq.gz
SIZE=$(stat -c%s $FILE 2>/dev/null || stat -f%z $FILE)
PRESIGN=$(curl -s $API/samples/$SAMPLE/assets/presign -H "$AUTH" -H 'Content-Type: application/json' \
  -d "{\"filename\":\"$FILE\",\"asset_type\":\"fastq_r1\",\"size_bytes\":$SIZE}")
ASSET=$(echo "$PRESIGN" | jq -r .asset.asset_id)
curl -s -X PUT "$(echo "$PRESIGN" | jq -r .upload.url)" \
  -H 'Content-Type: application/octet-stream' --data-binary @$FILE
curl -s -X POST $API/samples/$SAMPLE/assets/$ASSET/finalize -H "$AUTH"

# Ask the price (dry_run), then submit with that price as expected_credits
BODY='{"analysis_type":"human_pathogens","input_refs":{"fastq_asset_ids":["'$ASSET'"]},"parameters":{}}'
CREDITS=$(curl -s $API/samples/$SAMPLE/analyses -H "$AUTH" -H 'Content-Type: application/json' \
  -d "$(jq -c '. + {dry_run:true}' <<<"$BODY")" | jq -r .credits)
ANALYSIS=$(curl -s $API/samples/$SAMPLE/analyses -H "$AUTH" -H 'Content-Type: application/json' \
  -d "$(jq -c --argjson c $CREDITS '. + {expected_credits:$c}' <<<"$BODY")" | jq -r .analysis_id)

# Poll until status is complete (or failed), then read the result
curl -s $API/samples/$SAMPLE/analyses/$ANALYSIS -H "$AUTH" | jq '.analysis.status'
curl -s $API/samples/$SAMPLE/analyses/$ANALYSIS -H "$AUTH" | jq '.result | keys'

# Download an artifact (the answer is a 15-minute pre-signed URL)
curl -s $API/samples/$SAMPLE/analyses/$ANALYSIS/artifacts/bacteria_classification.json -H "$AUTH" | jq -r .url | xargs curl -sO -J

Errors & codes

Every error is JSON with a human-readable error. Many also carry a stable code to branch on, and validation errors name the offending field.

{"error": "This analysis costs 2 credits. Press Run again to confirm.", "code": "quote_required", "credits": 2, "quote": {...}}

Service

Auth & account

API tokens

All three need a session token (sign in with a password, or do it in the app); an API token answers 403 session_required.

Projects

A project is a label you can attach to samples and filter by. Names are unique per account (case-insensitive), at most 60 characters, at most 200 projects.

Samples

A sample holds one set of reads (uploaded FASTQ or BAM files, or an NCBI SRA run) and any number of analyses over them.

The sample object

Assets & uploads

An asset is one file attached to a sample. Bytes are uploaded straight to S3 through pre-signed URLs; the API only mints the URLs and records the result.

Asset types

A sample holds at most one file per read slot (fastq_r1, fastq_r2, reads_bam); a second upload to an occupied slot is refused with 409 slot_taken. The first read file to become ready moves the sample to ready.

The asset object

Single-request upload (files up to upload.single_put_max_bytes, 5 GiB)

Multipart upload (any size)

For read files larger than multipart_threshold_bytes, or whenever you prefer resumable parts. The whole upload must complete within upload.window_hours (48 h) of starting.

Pricing & credits

Analyses are paid in credits. The price of an analysis is base[type] × bands, where the bands are unit_bytes (10 GiB) of gzipped reads and anything up to first_unit_bytes (16 GiB) counts as one band. human_pathogens has a base of 2; every other type 1. A plain, uncompressed FASTQ is priced on an estimate of its compressed size until its upload has been sampled. The server quotes every price; nothing is charged until you submit with the quoted expected_credits, and a failed analysis is refunded automatically.

Buying credits

Credits are bought by card through Stripe. The flow is browser-oriented (it needs Stripe's client-side confirmation), so use the app's Buy credits dialog; the endpoints are listed for completeness.

For volume pricing or invoicing, contact sales@fathom-genomics.com.

Analyses

Analysis types

Older type names (pathogen_classification, who_priority, bacteria, viral, fungal) are retired: existing results still load, new submissions answer 400 naming the replacement.

The analysis object

Results & artifacts

The result object

A JSON document assembled by the pipeline. Its top-level sections depend on the analysis type; the common ones are:

NCBI SRA input

Instead of uploading, a sample can point at a public SRA run. The reads are downloaded fresh for each analysis and never stored. Availability is per account while the feature rolls out: check allowed first.

Then POST /api/samples with sra_accession, and submit analyses with "input_refs": {"sra_accession": "SRR..."}. Pricing uses the run's compressed size as frozen on the sample.

Box, S3 & single sign-on

These flows involve a browser redirect or a stored connection and are meant to be driven from the app. They are listed so the surface is complete.