title: HTTP API
description: Every endpoint the Fathom api exposes. Generated from the running stack's OpenAPI schema.
audience: developer
quadrant: reference
last_verified: 2026-04-25
owners: [api/server.py, api/routes/]
HTTP API
Fathom's api exposes a REST-shaped HTTP API at http://localhost:8201 by default. Authentication is via Authorization: Bearer <token> (mint tokens in Settings → API Keys) for any endpoint that requires auth; some endpoints are public.
The interactive Swagger UI lives at /docs and is the canonical reference for request/response bodies. This page is the at-a-glance index.
/
| Method |
Path |
Summary |
GET |
/ |
Ui Root |
GET |
/health |
Health |
/v1/agent-instructions
| Method |
Path |
Summary |
GET |
/v1/agent-instructions |
Get Agent Instructions |
/v1/agents
| Method |
Path |
Summary |
GET |
/v1/agents/latest-version |
Agents Latest Version |
GET |
/v1/agents/status |
Agents Status |
/v1/auth
| Method |
Path |
Summary |
POST |
/v1/auth/bootstrap |
Bootstrap |
GET |
/v1/auth/bootstrap-status |
Bootstrap Status |
GET |
/v1/auth/me |
Auth Me |
POST |
/v1/auth/register |
Register |
/v1/chat
| Method |
Path |
Summary |
POST |
/v1/chat/completions |
Chat Completions |
POST |
/v1/chat/rename |
Chat Rename |
/v1/contact-proposals
| Method |
Path |
Summary |
GET |
/v1/contact-proposals |
List Contact Proposals |
POST |
/v1/contact-proposals |
Propose Contact |
POST |
/v1/contact-proposals/{proposal_id}/accept |
Accept Contact Proposal |
POST |
/v1/contact-proposals/{proposal_id}/reject |
Reject Contact Proposal |
/v1/contacts
| Method |
Path |
Summary |
GET |
/v1/contacts |
List Contacts |
POST |
/v1/contacts |
Create Contact |
DELETE |
/v1/contacts/{slug} |
Delete Contact |
GET |
/v1/contacts/{slug} |
Get Contact |
PATCH |
/v1/contacts/{slug} |
Update Contact |
DELETE |
/v1/contacts/{slug}/handles |
Remove Contact Handle |
GET |
/v1/contacts/{slug}/handles |
List Contact Handles |
POST |
/v1/contacts/{slug}/handles |
Add Contact Handle |
/v1/crystal
| Method |
Path |
Summary |
GET |
/v1/crystal |
Get Crystal |
GET |
/v1/crystal/events |
Get Crystal Events |
POST |
/v1/crystal/refresh |
Refresh Crystal |
/v1/deltas
| Method |
Path |
Summary |
GET |
/v1/deltas |
Proxy Query Deltas |
POST |
/v1/deltas |
Proxy Write Delta |
GET |
/v1/deltas/{delta_id} |
Proxy Get Delta |
/v1/drift
| Method |
Path |
Summary |
GET |
/v1/drift |
Get Drift |
GET |
/v1/drift/history |
Get Drift History |
/v1/engagement
| Method |
Path |
Summary |
POST |
/v1/engagement |
Write Engagement |
/v1/feed
| Method |
Path |
Summary |
GET |
/v1/feed/confidence/history |
Feed Confidence History |
GET |
/v1/feed/crystal |
Get Feed Crystal |
GET |
/v1/feed/crystal/events |
Feed Crystal Events |
POST |
/v1/feed/crystal/refresh |
Refresh Feed Crystal |
GET |
/v1/feed/drift |
Feed Drift |
GET |
/v1/feed/drift/history |
Feed Drift History |
POST |
/v1/feed/engagement |
Write Feed Engagement |
GET |
/v1/feed/engagement/history |
Feed Engagement History |
POST |
/v1/feed/refresh |
Refresh Feed |
GET |
/v1/feed/status |
Feed Status |
GET |
/v1/feed/stories |
Get Feed Stories |
POST |
/v1/feed/visit |
Feed Visit |
/v1/me
| Method |
Path |
Summary |
GET |
/v1/me/profile |
Get My Profile |
PATCH |
/v1/me/profile |
Update My Profile |
/v1/media
| Method |
Path |
Summary |
GET |
/v1/media/{media_hash} |
Proxy Media |
POST |
/v1/media/capture-context |
Capture Context |
POST |
/v1/media/upload |
Upload Media |
/v1/models
| Method |
Path |
Summary |
GET |
/v1/models |
List Models |
/v1/moods
| Method |
Path |
Summary |
GET |
/v1/moods/history |
Get Mood History |
GET |
/v1/moods/latest |
Get Latest Mood |
POST |
/v1/moods/synthesize |
Force Mood Synthesis |
/v1/pair
| Method |
Path |
Summary |
GET |
/v1/pair |
Pair List |
POST |
/v1/pair |
Pair Create |
POST |
/v1/pair/redeem |
Pair Redeem |
/v1/plan
| Method |
Path |
Summary |
POST |
/v1/plan |
Proxy Plan |
/v1/pressure
| Method |
Path |
Summary |
GET |
/v1/pressure/history |
Get Pressure History |
/v1/recall
| Method |
Path |
Summary |
GET |
/v1/recall/history |
Get Recall History |
/v1/routines
| Method |
Path |
Summary |
GET |
/v1/routines |
List Routines Endpoint |
POST |
/v1/routines |
Create Routine Endpoint |
DELETE |
/v1/routines/{routine_id} |
Delete Routine Endpoint |
PUT |
/v1/routines/{routine_id} |
Update Routine Endpoint |
POST |
/v1/routines/{routine_id}/fire |
Fire Routine Endpoint |
POST |
/v1/routines/preview-schedule |
Preview Schedule Endpoint |
/v1/scopes
| Method |
Path |
Summary |
GET |
/v1/scopes |
List Scopes |
/v1/search
| Method |
Path |
Summary |
POST |
/v1/search |
Search Endpoint |
/v1/sessions
| Method |
Path |
Summary |
GET |
/v1/sessions |
List Sessions |
POST |
/v1/sessions |
Create Session |
DELETE |
/v1/sessions/{session_id} |
Delete Session |
GET |
/v1/sessions/{session_id} |
Get Session |
PATCH |
/v1/sessions/{session_id} |
Update Session |
/v1/settings
| Method |
Path |
Summary |
GET |
/v1/settings/models |
Settings Models |
PUT |
/v1/settings/models/{tier} |
Settings Models Put |
GET |
/v1/settings/providers/{provider}/models |
Settings Provider Models |
/v1/sources
| Method |
Path |
Summary |
GET |
/v1/sources |
List Sources |
POST |
/v1/sources |
Create Source |
DELETE |
/v1/sources/{source_id} |
Delete Source |
PUT |
/v1/sources/{source_id} |
Update Source |
GET |
/v1/sources/{source_id}/detail |
Source Detail |
POST |
/v1/sources/{source_id}/pause |
Pause Source |
POST |
/v1/sources/{source_id}/poll |
Poll Source |
POST |
/v1/sources/{source_id}/resume |
Resume Source |
GET |
/v1/sources/types |
List Source Types |
/v1/stats
| Method |
Path |
Summary |
GET |
/v1/stats |
Proxy Stats |
/v1/tags
| Method |
Path |
Summary |
GET |
/v1/tags |
Proxy Tags |
/v1/tokens
| Method |
Path |
Summary |
GET |
/v1/tokens |
List Tokens |
POST |
/v1/tokens |
Create Token |
DELETE |
/v1/tokens/{token_id} |
Delete Token |
/v1/tools
| Method |
Path |
Summary |
GET |
/v1/tools |
List Tools |
/v1/usage
| Method |
Path |
Summary |
GET |
/v1/usage |
Usage |
GET |
/v1/usage/history |
Get Usage History |
Notes
- Authentication: most endpoints require
Authorization: Bearer <token>. A few (/health, /v1/tools, install assets) are deliberately public.
- CORS: the api allows browser requests from the dashboard origin by default. For other origins, configure via the api environment.
- Rate limits: none enforced in self-host. The lake is yours; pace your own clients.
- Schema details: open
/docs in a browser for full request/response shapes, parameter types, and example payloads.