HTTP API

HTTP API

REST API for the engram knowledge graph. All endpoints accept and return JSON.

Starting the Server

engram serve my.brain
# Default: 0.0.0.0:3030

engram serve my.brain 127.0.0.1:8080
# Custom address

Authentication

All endpoints (except /health and /auth/setup) require authentication.

First Run

curl -X POST http://localhost:3030/auth/setup \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "your-password"}'

Login

TOKEN=$(curl -s -X POST http://localhost:3030/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "your-password"}' | jq -r '.token')

# Use in all requests
curl -H "Authorization: Bearer $TOKEN" http://localhost:3030/stats

API Keys

# Create persistent API key
curl -X POST http://localhost:3030/auth/api-keys \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-script"}'

---

Endpoint Reference

Core Graph Operations

Method	Path	Description
POST	/store	Store a node
POST	/relate	Create a directed edge
POST	/batch	Bulk store entities and relationships
POST	/batch/stream	Streaming batch operations
POST	/query	BFS traversal from a start node
POST	/search	BM25 full-text search
POST	/similar	Semantic similarity search (vector)
POST	/autocomplete	Search autocomplete
POST	/paths	Find paths between entities
POST	/ask	Natural language query
POST	/tell	Natural language fact assertion
GET	/node/{label}	Get node with edges and properties
PATCH	/node	Update node properties
DELETE	/node/{label}	Soft-delete a node
PATCH	/edge	Rename an edge
POST	/edge/delete	Delete an edge

Chat System (47 tools)

Method	Path	Description
POST	/chat/compare	Side-by-side entity comparison
POST	/chat/shortest_path	BFS shortest path
POST	/chat/most_connected	Top-N entities by edge count
POST	/chat/isolated	Nodes with few connections
POST	/chat/what_if	Simulate confidence cascade
POST	/chat/influence_path	Find indirect influence paths
POST	/chat/temporal_query	Query edges within a time range
POST	/chat/timeline	Chronological events for an entity
POST	/chat/current_state	Only current (non-expired) edges
POST	/chat/changes	Entities created/updated since date
POST	/chat/network_analysis	Community detection, centrality
POST	/chat/entity_360	Full 360-degree entity view
POST	/chat/entity_gaps	Missing information for an entity
POST	/chat/briefing	Structured briefing on a topic
POST	/chat/dossier	Comprehensive entity dossier
POST	/chat/topic_map	Topic clustering across graph
POST	/chat/graph_stats	Overall graph statistics
POST	/chat/export_subgraph	Export entity neighborhood as JSON
POST	/chat/entity_timeline	Chronological narrative
POST	/chat/contradictions	Find contradictions for an entity
POST	/chat/situation_at	Knowledge state at a point in time
POST	/chat/fact_provenance	Full provenance chain
POST	/chat/watch	Mark entity as watched
POST	/chat/schedule	Create monitoring tasks

Multi-Agent Debate

Method	Path	Description
POST	/debate/start	Start a debate session
GET	/debate/{id}	Get debate status and results
DELETE	/debate/{id}	Delete a debate session
POST	/debate/{id}/run	Run the next round
POST	/debate/{id}/stop	Stop a running debate
POST	/debate/{id}/synthesize	Generate final synthesis
GET	/debate/{id}/stream	SSE live debate progress
PATCH	/debate/{id}/agents	Edit agent configuration
POST	/debate/{id}/inject	Inject evidence

Modes: analyze, red_team, devils_advocate, scenario_planning, delphi, sat, war_game

Assessments

Method	Path	Description
POST	/assessments	Create assessment
GET	/assessments	List assessments
GET	/assessments/{label}	Get assessment detail
PATCH	/assessments/{label}	Update assessment
DELETE	/assessments/{label}	Delete assessment
POST	/assessments/{label}/evaluate	Re-evaluate
POST	/assessments/{label}/evidence	Add evidence
DELETE	/assessments/{label}/evidence/{id}	Remove evidence
GET	/assessments/{label}/history	Score history
POST	/assessments/{label}/watch	Add watch entity
DELETE	/assessments/{label}/watch/{entity}	Remove watch
GET	/assessments/compare/{a}/{b}	Compare two assessments
POST	/assessments/suggest-watches	LLM-suggested watches

Documents & Facts

Method	Path	Description
POST	/documents	List documents
POST	/documents/content	Get document content
POST	/documents/passage	Get specific passage
DELETE	/documents/{label}	Delete document
POST	/provenance	Full provenance chain
POST	/facts	List extracted facts
POST	/facts/{label}/confirm	Confirm a pending fact
POST	/facts/{label}/debunk	Mark fact as debunked

Conflicts & Contradictions

Method	Path	Description
GET	/conflicts	List detected contradictions
POST	/conflicts/resolve	Resolve a conflict

Learning Operations

Method	Path	Description
POST	/learn/reinforce	Boost confidence
POST	/learn/correct	Mark fact wrong, propagate distrust
POST	/learn/decay	Apply time-based decay
POST	/learn/derive	Run inference rules

Ingest Pipeline

Method	Path	Description
POST	/ingest	Ingest text through NER pipeline
POST	/ingest/file	Ingest file (auto-detect format)
POST	/ingest/analyze	Analyze without storing
POST	/ingest/configure	Configure pipeline settings
POST	/ingest/reprocess-docs	Reprocess all documents
POST	/ingest/reprocess-doc/{label}	Reprocess single document
POST	/ingest/webhook/{pipeline_id}	Receive webhook data
GET	/ingest/ws/{pipeline_id}	WebSocket ingest
GET	/ingest/review	Review mode
POST	/ingest/review/confirm	Confirm reviewed items

Seed Enrichment

Method	Path	Description
POST	/ingest/seed/start	Start seed session
POST	/ingest/seed/confirm-aoi	Confirm area of interest
POST	/ingest/seed/confirm-entities	Confirm entities
GET	/ingest/seed/connections	Get predicted connections
POST	/ingest/seed/confirm-relations	Confirm relations
POST	/ingest/seed/commit	Commit to graph
GET	/ingest/seed/stream	SSE progress

Sources

Method	Path	Description
GET	/sources	List sources
POST	/sources	Create source
GET	/sources/{name}	Get source
PUT	/sources/{name}	Update source
DELETE	/sources/{name}	Delete source
POST	/sources/{name}/run	Run source
POST	/sources/{name}/test	Test source
POST	/sources/{name}/pause	Toggle pause
GET	/sources/{name}/usage	Usage stats
GET	/sources/{name}/ledger	Search ledger

Action Engine

Method	Path	Description
POST	/actions/rules	Load rules
GET	/actions/rules	List rules
GET	/actions/rules/{id}	Get rule
DELETE	/actions/rules/{id}	Delete rule
POST	/actions/dry-run	Test event against rules

Reasoning / Gap Detection

Method	Path	Description
GET	/reason/gaps	Detect knowledge gaps
POST	/reason/scan	Full graph scan
GET	/reason/frontier	Frontier nodes
POST	/reason/suggest	LLM investigation suggestions
POST	/reason/enrich/plan	Plan enrichment
POST	/reason/enrich/run	Run enrichment
GET	/enrich/stream	Enrichment SSE stream

Configuration

Method	Path	Description
GET	/config	Get configuration
POST	/config	Update configuration
GET	/config/status	Readiness and wizard state
POST	/config/wizard-complete	Mark wizard complete
POST	/config/onnx-download	Download ONNX model
POST	/config/gliner2-download	Download GLiNER2 model
POST	/config/ollama-pull	Pull Ollama model
GET	/config/relation-types	List relation types
GET	/config/domains	List domains
POST	/config/domains	Set domains
GET	/config/domains/suggest	LLM-suggested domains
GET	/config/kb	List KB endpoints
POST	/config/kb	Add KB endpoint

Mesh Networking

Method	Path	Description
GET	/mesh/peers	List peers
POST	/mesh/peers	Register peer
DELETE	/mesh/peers/{key}	Remove peer
POST	/mesh/sync	Sync with peers
GET	/mesh/profiles	Knowledge profiles
GET	/mesh/discover	Discover by topic
POST	/mesh/query	Federated query
GET	/mesh/identity	Local identity
GET	/mesh/audit	Audit trail

Authentication

Method	Path	Description
GET	/auth/status	Check auth status
POST	/auth/setup	Initial admin setup
POST	/auth/login	Login
POST	/auth/logout	Logout
POST	/auth/change-password	Change password
GET	/auth/users	List users
POST	/auth/users	Create user
PUT	/auth/users/{username}	Update user
DELETE	/auth/users/{username}	Delete user
GET	/auth/api-keys	List API keys
POST	/auth/api-keys	Create API key
DELETE	/auth/api-keys/{id}	Revoke API key

Secrets

Method	Path	Description
GET	/secrets	List secret keys
POST	/secrets/{key}	Set a secret
DELETE	/secrets/{key}	Delete a secret
GET	/secrets/{key}/check	Check if secret exists

Streaming

Method	Path	Description
GET	/events/stream	Real-time graph event stream (SSE)
GET	/batch/jobs/{id}/stream	Batch job progress (SSE)

System

Method	Path	Description
GET	/health	Health check
GET	/stats	Node and edge counts
GET	/compute	Hardware and embedder info
GET	/explain/{label}	Full provenance and co-occurrences
GET	/tools	LLM tool definitions (OpenAI format)
GET	/export/jsonld	Export graph as JSON-LD
POST	/quantize	Set vector quantization
POST	/reindex	Rebuild embedding index
POST	/rules	Load inference rules
GET	/rules	List rules
DELETE	/rules	Clear rules

Admin

Method	Path	Description
POST	/admin/reset	Reset database
POST	/admin/dedup-edges	Deduplicate edges

---

Concurrency Model

• Readers (/search, /query, /similar, etc.) acquire a read lock and run concurrently.
• Writers (/store, /relate, /batch, etc.) acquire an exclusive write lock.
• Deferred checkpoint: writes go to WAL immediately (crash-safe), flush every 5 seconds.
• Use /batch for bulk operations -- one lock acquisition instead of N.

Performance

Operation	Latency
Health check	~1.2 ms
Store entity	~1.3 ms
Query / Search	~1.1 ms

Windows note: Use 127.0.0.1 instead of localhost to avoid IPv6 fallback delay (~210ms).

Error Handling

All errors return JSON: {"error": "message"}. Status codes: 200 (success), 400 (bad request), 404 (not found), 500 (internal error).