HTTP API overview
In plain terms: REST endpoints for the browser UI and custom apps — capture, search, chat, and admin operations over standard HTTP with session cookies or API keys.
Eigen Mesh exposes REST endpoints alongside MCP. All routes require an authenticated session (browser cookie) or API key where noted. Base URL: https://<your-app-origin>.
This page summarizes the public surface. OpenAPI or generated specs, if maintained, live in the eigen repository.
Who this is for
- Integrators building custom apps against Eigen Mesh REST endpoints
- Operators reviewing auth modes and route inventory
Health
| Method |
Path |
Auth |
Purpose |
| GET |
/api/health |
None |
Liveness check for load balancers |
Capture
| Method |
Path |
Auth |
Body |
Purpose |
| POST |
/api/capture/submit |
Session |
{ "raw": "..." } |
Capture new thought; optional NDJSON progress stream with Accept: application/x-ndjson |
| POST |
/api/capture/edit |
Session |
{ "thoughtId", "instruction" } |
Natural-language edit |
| POST |
/api/capture/relink |
Session |
{ "thoughtId" } |
Re-sync graph without text change |
Browser capture also uses a client-side IndexedDB queue with Background Sync — see contributor Capture queue.
Retrieval
| Method |
Path |
Auth |
Body |
Purpose |
| POST |
/api/retrieval/search |
Session |
{ "query", "topK" } |
Hybrid search; same engine as MCP retrieve_thoughts |
Chat
| Method |
Path |
Auth |
Purpose |
| POST |
/api/chat |
Session |
Memory assistant stream (agent tool loop: retrieve_thoughts, thought CRUD, Notes tools) |
| GET/POST |
/api/chat/sessions/* |
Session |
Session management |
Chat uses an extended tool surface internally (Notes tools, etc.). HTTP MCP clients see only the four thought tools — see MCP overview.
Thoughts and entities
| Method |
Path |
Auth |
Purpose |
| GET/POST |
/api/thoughts/* |
Session |
Thought CRUD helpers |
| GET/POST |
/api/entities/* |
Session |
Entity graph operations |
MCP
| Method |
Path |
Auth |
Purpose |
| POST |
/api/mcp |
Bearer API key |
MCP Streamable HTTP — see MCP tools reference |
Push notifications (optional)
| Method |
Path |
Auth |
Purpose |
| GET |
/api/push/vapid-public-key |
Session |
VAPID public key |
| POST |
/api/push/subscribe |
Session |
Register push subscription |
| POST |
/api/push/unsubscribe |
Session |
Remove subscription |
Requires VAPID_* environment variables.
Admin
| Method |
Path |
Auth |
Purpose |
| POST |
/api/admin/consolidate |
X-Admin-Key header |
Trigger nightly consolidation (also scheduled via pg_cron) |
Embeddings visualization (not MCP)
| Method |
Path |
Auth |
Purpose |
| GET |
/api/embeddings/snapshot |
Session |
Graph embedding map UI only — vectors for authorized visualization, not exposed via MCP or chat LLM |
Authentication patterns
| Surface |
Mechanism |
| Browser UI |
Better Auth session cookie |
| MCP |
Authorization: Bearer <user_api_key> |
| Admin consolidate |
X-Admin-Key: <ADMIN_CONSOLIDATION_KEY> |
Create API keys at /api-keys in the product UI.
Troubleshooting
See Troubleshooting for auth, MCP, and deployment issues.
Next steps
