> Markdown export: /developers/http-api.md
> HTML: /developers/http-api
---
description: Authenticated REST endpoints exposed by the Eigen Mesh product app for browser UI and custom integrations.
audience: integrator
---

# 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](https://github.com/your-org/eigen)**.

## 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](/developers/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](/developers/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](/developers/mcp-tools) |

## 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](/developers/troubleshooting) for auth, MCP, and deployment issues.

## Next steps

- [MCP tools reference](/developers/mcp-tools)
- [Environment variables](/developers/environment-variables)