API & Server

Run it headless.
Watch it live.

A self-hosted Axum control plane for autonomous workers: start and steer sessions, inspect durable jobs and memory, apply governance, and integrate through REST, SSE and AG-UI event streams. Coworkers, schedules, notifications and computer relay controls are available when configured.

Authentication

API keys + rate limiting

Set FATHOM_API_KEYS (comma-separated) to require a key on each /api/v1/* request — Bearer token or X-Api-Key header. Sliding-window rate limiting uses FATHOM_RATE_LIMIT requests per minute per principal and returns 429 when exhausted. If no keys are configured, the self-hosted server permits open access; add authentication before exposing it beyond a trusted network.

curl -H "Authorization: Bearer $KEY" \
  http://localhost:8080/api/v1/sessions

curl -H "X-Api-Key: $KEY" \
  http://localhost:8080/api/v1/memories/stats

Endpoints

Everything is an endpoint

Worker sessions

POST/api/v1/sessionsStart a worker session with query and optional output_dir (returns 202 Accepted)

GET/api/v1/sessionsList worker sessions with status and progress

GET/api/v1/sessions/:idSession state, worker tree and token usage

GET/api/v1/sessions/:id/resultsCompleted worker output and exported artifacts

DELETE/api/v1/sessions/:idCancel a running session

Worker tree

GET/api/v1/agentsAll agents across sessions (tree view)

GET/api/v1/agents/:idAgent details, messages, tool calls

Operator control plane

POST/api/v1/sessions/:id/steerMid-run steering — redirect a running session

POST/api/v1/sessions/:id/answerAnswer an agent `question` tool call

POST/api/v1/sessions/:id/approveApprove/deny a side-effect tool (approval flow)

Live worker events

GET/api/v1/eventsGlobal SSE stream of all agent events

GET/api/v1/sessions/:id/eventsPer-session SSE stream (deltas, tool calls, findings)

Memory

GET/api/v1/memoriesSearch the semantic memory store

POST/api/v1/memories/absorbIngest facts through the semantic memory pipeline (dedup + supersedes chains)

GET/api/v1/memories/statsStore size, scopes, graph stats

POST/api/v1/memories/distillDistill run-facts into durable knowledge

POST/api/v1/memories/gcArchive stale facts, compact scope groups

GET / DELETE/api/v1/memories/:idInspect / archive a single memory

Durable jobs

POST/api/v1/jobsSubmit a durable background job (task, attempts)

GET/api/v1/jobsList jobs

GET/api/v1/jobs/:idJob status

GET/api/v1/jobs/:id/logstdout + stderr of all attempts

DELETE/api/v1/jobs/:idCancel an active job

POST/api/v1/jobs/:id/rerunRe-run a finished/stuck job

Governance & worker collaboration

GET / PUT/api/v1/governance/policyRead or replace the governance policy

POST/api/v1/governance/decideEvaluate a governed action

GET/api/v1/governance/auditRead governance audit events

GET / POST/api/v1/coworkersList or create persistent coworker profiles

GET / PUT / PATCH / DELETE/api/v1/coworkers/:idInspect or update a coworker profile

GET / POST/api/v1/channelsList or create collaboration channels

PUT / PATCH / DELETE/api/v1/channels/:idUpdate or remove a channel

GET / POST/api/v1/schedulesList or create cron-like coworker schedules

GET / PUT / PATCH / DELETE/api/v1/schedules/:idInspect, update, or remove a schedule

POST/api/v1/schedules/claimAtomically claim due schedules for a scheduler tick

GET/api/v1/ag-ui/eventsStream the Fathom AG-UI-compatible event subset over SSE

GET/api/v1/ag-ui/healthProbe AG-UI bridge and advertised event-only capabilities

Credentials, notifications & audit

GET / POST/api/v1/credentialsList redacted credential metadata or store a secret

DELETE/api/v1/credentials/:idDelete a stored credential

GET/api/v1/replayList redacted governed actions; filter by session or agent

GET/api/v1/observability/summaryRead bounded live metrics and audit counts

POST/api/v1/notifications/testOperator-triggered bounded test through one configured webhook, email or Telegram channel

Configured computer relay

POST/api/v1/computers/sessionStart a session on a configured computer relay

GET/api/v1/computers/healthCheck whether the configured computer relay is reachable

GET/api/v1/computers/snapshotRead the current snapshot from a configured relay

POST/api/v1/computers/navigateNavigate the configured computer relay

POST/api/v1/computers/clickClick through the configured computer relay

POST/api/v1/computers/typeType through the configured computer relay

POST/api/v1/computers/keySend a keyboard action through a configured relay

POST/api/v1/computers/secretEnter a secret through a configured relay without returning or logging its value

GET/api/v1/computers/screenshotCapture a screenshot from a configured relay

GET / POST/api/v1/computers/tabs*List, open, activate, or close tabs on a configured browser relay

POST/api/v1/computers/control/take|releaseTake or release operator control of the configured relay

GET / PUT / DELETE/api/v1/computers/files*List, read, write, or delete confined workspace files on the relay

GET/api/v1/computersList configured computers; supervisor lifecycle requires COMPUTER_TOKEN

System

GET/healthLiveness probe

GET/metricsPrometheus metrics

GET/dashboardRead-only single-file view over sessions, worker tree, memory, jobs and live SSE events

Example

Start a session, steer it mid-run

Sessions start asynchronously. Follow worker progress on SSE, then steer, answer a question, or approve a governed side effect while the run is still active.

Full API reference

curl -X POST localhost:8080/api/v1/sessions \
  -H "Content-Type: application/json" \
  -d '{"query":"Find VPs of Engineering
       at Series B fintech startups in SF"}'

# follow the live event stream
curl -N localhost:8080/api/v1/sessions/abc/events

# redirect mid-run
curl -X POST localhost:8080/api/v1/sessions/abc/steer \
  -d '{"message":"Focus on Berlin instead"}'

Observability

Prometheus metrics

Scrape /metrics from your self-hosted runtime for request, session and tool telemetry. The authenticated API also exposes /api/v1/observability/summary for bounded live counters and governance-audit totals.

Metric	Type	What it counts
pr_http_requests_total	counter	requests by route and status
pr_request_duration_seconds	histogram	latency distribution
pr_sessions_total	counter	sessions started
pr_sessions_active	gauge	sessions running right now
pr_agents_spawned_total	counter	sub-agents across all trees
pr_tool_calls_total	counter	tool executions by name
pr_tokens_used_total	counter	LLM tokens consumed

Prometheus

/metrics exposes request counts, latencies, session and tool gauges for Grafana dashboards.

SSE streaming

Worker lifecycle events, tool calls and findings arrive as server-sent events; use SSE when you need live progress without polling.

Web dashboard

GET /dashboard serves the read-only single-file HTML view over the same API: sessions, worker tree, memory, jobs and live events. It uses your configured API key when auth is enabled.

CORS

Cross-origin access is configurable via [server] settings; set an explicit allowlist when operators access the runtime from another origin.

Run it headless.Watch it live.