API Reference

REST API

The Engram API runs at localhost:8000. All endpoints use JSON. Authenticated routes require an API key in the X-API-Key header.

Authentication

Set ENGRAM_API_KEY in your .env, then send it on every request via the X-API-Key header.

bash

# Generate a key once and add it to .env
echo "ENGRAM_API_KEY=$(openssl rand -hex 32)" >> .env

# Use it on every request
curl localhost:8000/api/memories \
  -H "X-API-Key: <your-key>"

Dev mode

If ENGRAM_API_KEY is not set, the API runs in dev mode: all requests are treated as a local admin user. Fine on an air-gapped machine, but set a key before exposing the port to your network.

Chat

Base: localhost:8000

Method	Endpoint	Description	Auth
POST	/chat	Ask a question grounded in your memories. Set stream: true for SSE token streaming; the final event carries context_used (sources).	🔒
POST	/v1/chat/completions	OpenAI-compatible chat endpoint — point any OpenAI SDK client at Engram.	🔒
POST	/v1/embeddings	OpenAI-compatible embeddings endpoint backed by nomic-embed-text.	🔒

Memory

Base: localhost:8000

Method	Endpoint	Description	Auth
GET	/api/memories	List memories with matter_id / type / classification filters and cursor pagination.	🔒
POST	/add-memory	Store a new memory explicitly. Body: { text, matter_id? }.	🔒
POST	/ingest	Ingest document text (used by the file ingestor). Supports document_keys for structured docs.	🔒
DELETE	/api/memory/:id	Delete a single memory point with ownership check.	🔒
DELETE	/api/memories	Batch-delete by matter_id with optional type filter.	🔒

Search

Base: localhost:8000

Method	Endpoint	Description	Auth
GET	/search	Semantic search over personal memories (second_brain).	🔒
POST	/api/docs/query	Semantic search over the doc_knowledge collection.	🔒
GET	/api/search/unified	Merged search across both collections, ranked by score.	🔒

Knowledge

Base: localhost:8000

Method	Endpoint	Description	Auth
POST	/api/docs/ingest	Store crawled documentation pages (used by DocSpider).	🔒
GET	/api/models	List models available on the local Ollama instance.	🔒

Agents

Base: localhost:8000

Method	Endpoint	Description	Auth
POST	/run-agents/calendar	Trigger the calendar agent immediately (also runs every 15 min via APScheduler).	🔒
POST	/run-agents/email	Trigger the email agent immediately (also runs hourly via APScheduler).	🔒
GET	/api/audit/logs	Recent agent activity from the tamper-evident audit log (admin only).	🔒
GET	/api/audit/verify	Verify the HMAC hash chain over the audit log.	🔒

Users & Matters

Base: localhost:8000

Method	Endpoint	Description	Auth
GET	/api/me	Returns the profile of the currently authenticated user.	🔒
GET	/api/matters	List matters (projects) the current user can access.	🔒
POST	/api/matters	Create a matter. Query param: name.	🔒
POST	/api/matters/:id/close	Close a matter and purge its memory points.	🔒

Example: Unified Search

bash

curl "localhost:8000/api/search/unified?query=vendor%20contract%20renewal&n_results=5" \
  -H "X-API-Key: <your-key>"

json

{
  "results": [
    {
      "source": "second_brain",
      "score": 0.92,
      "text": "Renewal notice: the hosting contract auto-renews on 1 Sep...",
      "type": "file_ingest"
    },
    {
      "source": "doc_knowledge",
      "score": 0.71,
      "text": "Contracts API — renewal webhooks fire 30 days before...",
      "type": "documentation"
    }
  ]
}