Developer
API Reference
REST API endpoints exposed by the Retrace server.
The Retrace server exposes a REST API on localhost:1420. All endpoints return JSON. The API is used by the React frontend, the Chrome extension, and the MCP server.
| Method | Path | Description |
|---|
GET | /search | Search conversations (keyword, semantic, or hybrid) |
GET | /conversations | List all conversations (paginated) |
GET | /conversations/:id | Get a single conversation with messages |
DELETE | /conversations | Delete all conversations for a platform |
GET | /sync-status | Check sync status per platform |
POST | /rebuild | Rebuild conversation index |
| Method | Path | Description |
|---|
POST | /import/preview | Upload a file and preview parsed conversations |
POST | /import/preview-from-path | Preview conversations from a local file path |
POST | /import/confirm | Confirm and execute a pending import |
GET | /import/pending/:id | Get status of a pending import |
GET | /import/batches | List past import batches |
| Method | Path | Description |
|---|
GET | /people | List all people |
GET | /people/:id | Get a person with conversation stats |
POST | /people | Create a new person |
PUT | /people/:id | Update a person |
POST | /people/avatars | Scrape profile pictures |
POST | /people/:id/merge | Merge two person records |
| Method | Path | Description |
|---|
GET | /social-graph | Get the full social graph (nodes + edges with tie strength) |
GET | /social-graph/timeline | Get graph snapshots over time for timelapse |
| Method | Path | Description |
|---|
GET | /conversations/:id/segments | Get segments for a conversation |
GET | /segments/recent | Get recently processed segments |
POST | /processing/start | Start knowledge extraction for a conversation |
POST | /processing/stop | Stop processing |
GET | /processing/status | Get processing status |
POST | /processing/bulk-start | Start bulk processing |
POST | /segments/backfill | Backfill missing segments |
| Method | Path | Description |
|---|
GET | /embeddings/status | Get embedding generation status |
POST | /embeddings/backfill | Generate missing embeddings |
| Method | Path | Description |
|---|
GET | /labels | List all labels |
POST | /labels | Create a label |
PUT | /labels/:id | Update a label |
GET | /labels/resource/:type/:id | Get labels for a resource |
POST | /labels/resource/:type/:id | Attach labels to a resource |
| Method | Path | Description |
|---|
GET | /consumers | List consumers |
POST | /consumers | Create a consumer |
PUT | /consumers/:id | Update a consumer |
DELETE | /consumers/:id | Delete a consumer |
GET | /consumers/:id/permissions | Get permission rules |
PUT | /consumers/:id/permissions | Update permission rules |
| Method | Path | Description |
|---|
GET | /reflections | List reflections |
GET | /reflections/:id | Get a single reflection |
GET | /reflections/dimensions | Get reflection dimensions |
GET | /time-capsules | List time capsules |
GET | /time-capsules/:id | Get a single time capsule |
| Method | Path | Description |
|---|
GET | /chat/status | Check if Claude is available |
POST | /chat/stream | Start a streaming chat session (SSE) |
| Method | Path | Description |
|---|
GET | /whatsapp/status | Get connection status |
POST | /whatsapp/start | Start WhatsApp connection (generates QR) |
POST | /whatsapp/stop | Disconnect |
POST | /whatsapp/disconnect | Disconnect and clear session |
GET | /whatsapp/conversations | List synced WhatsApp conversations |
PUT | /whatsapp/exclusions | Set chat exclusion rules |
| Method | Path | Description |
|---|
GET | /obsidian/status | Get Obsidian integration status |
POST | /obsidian/configure | Configure vault path |
POST | /obsidian/sync | Trigger manual sync |
GET | /obsidian/vault/status | Get vault watch status |
POST | /obsidian/watch/start | Start watching vault for changes |
POST | /obsidian/watch/stop | Stop watching |
| Method | Path | Description |
|---|
GET | /stats | Get overall statistics |
GET | /analytics | Get weekly analytics data |
GET | /topics | List extracted topics |
GET | /config | Get app configuration |
PUT | /config | Update app configuration |
GET | /models | List available local LLM models |
POST | /models/download | Download a model |
GET | /auth/token | Get API token |
POST | /ingest | Ingest data from Chrome extension |