REST API Reference

All endpoints require Authorization: Bearer <key> when authentication is enabled.

Base URL — Replace localhost:3300 with your server's address (e.g. http://<YOUR_SERVER_IP>:3300). All routes versioned under /v1/.

Health

Method	Path	Auth	Description
`GET`	`/health`	No	Returns server status and version
`GET`	`/metrics`	No	Prometheus metrics

Memory

Method	Path	Description
`POST`	`/v1/memory/store`	Store a memory
`POST`	`/v1/memory/recall`	Semantic recall
`POST`	`/v1/memories/recall/batch`	Filter-based batch recall
`GET`	`/v1/memory/get/{id}`	Get memory by ID
`PUT`	`/v1/memory/update/{id}`	Update memory content, importance, or tags
`POST`	`/v1/memory/forget`	Delete (forget) a memory

Store memory — request body

{
  "agent_id": "my-agent",                  // required
  "content": "User prefers dark mode",       // required
  "importance": 0.8,                         // optional, 0.0–1.0, default 0.5
  "tags": ["preference", "ui"],             // optional
  "session_id": "sess-abc123",              // optional
  "memory_type": "episodic"                  // episodic | semantic | procedural | working
}

Recall — request body

{
  "agent_id": "my-agent",                  // required
  "query": "UI preferences",                // required
  "top_k": 10,                               // optional, default 10
  "min_importance": 0.5,                    // optional filter
  "tags": ["preference"],                    // optional filter
  "session_id": "sess-abc123"               // optional: scope to session
}

Sessions

Method	Path	Description
`POST`	`/v1/sessions/start`	Start a session
`GET`	`/v1/sessions/:id`	Get session by ID
`POST`	`/v1/sessions/{id}/end`	End a session
`GET`	`/v1/sessions/:id/memories`	Get all memories from a session
`GET`	`/v1/agents/:id/sessions`	List all sessions for an agent

Batch & advanced memory

Method	Path	Description
`POST`	`/v1/memories/recall/batch`	Filter-based batch recall (no semantic query)
`DELETE`	`/v1/memories/forget/batch`	Bulk forget by filter predicates
`POST`	`/v1/memory/search`	Search with tag and type filters
`POST`	`/v1/memory/importance`	Batch-update importance scores
`POST`	`/v1/memory/consolidate`	Merge related memories into summary
`POST`	`/v1/memories/{id}/feedback`	Submit feedback signal (upvote/downvote/flag)
`GET`	`/v1/memories/{id}/feedback`	Get feedback history for a memory
`PATCH`	`/v1/memories/{id}/importance`	Patch importance for a single memory

Agents

Method	Path	Description
`GET`	`/v1/agents`	List all agents
`GET`	`/v1/agents/{id}/memories`	List agent memories
`GET`	`/v1/agents/{id}/stats`	Agent statistics (memory count, storage, top tags)
`GET`	`/v1/agents/{id}/sessions`	List agent sessions
`GET`	`/v1/agents/{id}/wake-up`	Get wake-up context (unread memories since last session)
`POST`	`/v1/agents/{id}/consolidate`	Consolidate agent memories
`POST`	`/v1/agents/{id}/compress`	Compress agent memory
`GET`	`/v1/agents/{id}/consolidation/log`	Consolidation history log
`PATCH`	`/v1/agents/{id}/consolidation/config`	Update consolidation config

Feedback

Method	Path	Description
`GET`	`/v1/agents/{id}/feedback/summary`	Aggregated feedback stats for an agent
`GET`	`/v1/feedback/health`	System-wide feedback quality metrics

Vectors

Method	Path	Description
`POST`	`/v1/namespaces/{ns}/vectors`	Upsert vectors
`POST`	`/v1/namespaces/{ns}/query`	ANN vector similarity search
`POST`	`/v1/namespaces/{ns}/vectors/delete`	Delete vectors by ID
`POST`	`/v1/namespaces/{ns}/vectors/bulk-update`	Bulk-update metadata by filter
`POST`	`/v1/namespaces/{ns}/vectors/bulk-delete`	Bulk-delete vectors by filter
`POST`	`/v1/namespaces/{ns}/vectors/count`	Count vectors (with optional filter)
`POST`	`/v1/namespaces/{ns}/batch-query`	Batch vector queries in parallel
`POST`	`/v1/namespaces/{ns}/multi-vector`	Multi-vector search with MMR diversity
`POST`	`/v1/namespaces/{ns}/unified-query`	Flexible ranking (vector, text, or attribute)
`POST`	`/v1/namespaces/{ns}/aggregate`	Aggregation queries (count, sum, avg, min, max)
`POST`	`/v1/namespaces/{ns}/upsert-columns`	Column-format upsert (efficient batch)
`POST`	`/v1/namespaces/{ns}/explain`	Query execution plan and cost estimate
`POST`	`/v1/namespaces/{ns}/warm`	Pre-load vectors into memory cache
`POST`	`/v1/namespaces/{ns}/cache/warm`	Warm namespace cache
`POST`	`/v1/namespaces/{ns}/export`	Export vectors with pagination

Full-text & hybrid search

Method	Path	Description
`POST`	`/v1/namespaces/{ns}/fulltext/index`	Index documents for BM25 search
`POST`	`/v1/namespaces/{ns}/fulltext/search`	BM25 full-text search
`POST`	`/v1/namespaces/{ns}/fulltext/delete`	Delete from full-text index
`GET`	`/v1/namespaces/{ns}/fulltext/stats`	Full-text index statistics
`POST`	`/v1/namespaces/{ns}/hybrid`	Vector + BM25 hybrid search

Text inference (auto-embedding)

Method	Path	Description
`POST`	`/v1/namespaces/{ns}/upsert-text`	Upsert text with server-side embedding
`POST`	`/v1/namespaces/{ns}/query-text`	Query by natural language text
`POST`	`/v1/namespaces/{ns}/batch-query-text`	Batch text queries
`POST`	`/v1/extract`	Extract structured info from text
`POST`	`/v1/route`	Semantic query routing

Namespaces

Method	Path	Description
`GET`	`/v1/namespaces`	List all namespaces
`POST`	`/v1/namespaces`	Create a namespace
`GET`	`/v1/namespaces/{ns}`	Get namespace details
`PUT`	`/v1/namespaces/{ns}`	Configure a namespace
`DELETE`	`/v1/namespaces/{ns}`	Delete a namespace
`GET`	`/v1/namespaces/{ns}/config`	Get entity extraction config
`PATCH`	`/v1/namespaces/{ns}/config`	Update entity extraction config
`GET`	`/v1/namespaces/{ns}/extractor`	Get extraction provider config
`PATCH`	`/v1/namespaces/{ns}/extractor`	Set extraction provider
`GET`	`/v1/namespaces/{ns}/memory_policy`	Get lifecycle policy
`PUT`	`/v1/namespaces/{ns}/memory_policy`	Update lifecycle policy

Namespace API keys

Method	Path	Description
`POST`	`/v1/namespaces/{ns}/keys`	Create a namespace-scoped API key
`GET`	`/v1/namespaces/{ns}/keys`	List keys for a namespace
`DELETE`	`/v1/namespaces/{ns}/keys/{key_id}`	Revoke a namespace key
`GET`	`/v1/namespaces/{ns}/keys/{key_id}/usage`	Key usage statistics

Knowledge graph

Method	Path	Description
`GET`	`/v1/memories/{id}/graph`	BFS traversal from a memory
`GET`	`/v1/memories/{id}/path`	Shortest path between two memories
`POST`	`/v1/memories/{id}/links`	Create explicit link between memories
`GET`	`/v1/agents/{id}/graph/export`	Export agent knowledge graph
`GET`	`/v1/knowledge/query`	Query KG with filter DSL
`GET`	`/v1/knowledge/path`	Find paths in KG
`GET`	`/v1/knowledge/export`	Export KG as JSON/GraphML

Knowledge operations

Method	Path	Description
`POST`	`/v1/knowledge/graph`	Build knowledge graph from seed memory
`POST`	`/v1/knowledge/summarize`	Summarize a set of memories
`POST`	`/v1/knowledge/deduplicate`	Find and merge duplicates
`POST`	`/v1/knowledge/graph/full`	Full knowledge graph with related memories
`POST`	`/v1/knowledge/network/cross-agent`	Cross-agent memory network

Entity extraction

Method	Path	Description
`POST`	`/v1/memories/extract`	Extract entities from text
`GET`	`/v1/memory/entities/{id}`	Get entities for a memory

Import & export

Method	Path	Description
`GET`	`/v1/export`	Export all memories (JSONL, CSV, Mem0, Zep)
`POST`	`/v1/import`	Import memories from external format
`GET`	`/v1/import/{job_id}/status`	Check import job status

Audit & events

Method	Path	Description
`GET`	`/v1/audit`	Query audit log
`GET`	`/v1/audit/stream`	Stream audit events (SSE)
`GET`	`/v1/audit/export`	Export audit log
`GET`	`/v1/events/stream`	Stream memory lifecycle events (SSE)
`GET`	`/v1/namespaces/{ns}/events`	Stream namespace events (SSE)

Analytics & operations

Method	Path	Description
`GET`	`/v1/analytics/overview`	High-level metrics (QPS, latency, storage)
`GET`	`/v1/analytics/latency`	Latency percentiles and trends
`GET`	`/v1/analytics/throughput`	Request throughput by operation
`GET`	`/v1/analytics/storage`	Storage breakdown by namespace
`GET`	`/v1/ops/stats`	Operational stats
`GET`	`/v1/ops/metrics`	Ops metrics
`GET`	`/v1/kpis`	Product KPI snapshot

Admin — cluster

Method	Path	Description
`GET`	`/admin/cluster/status`	Cluster health, leader, shard distribution
`GET`	`/admin/cluster/nodes`	All nodes with state and roles
`GET`	`/admin/cluster/replication`	Replication status
`GET`	`/admin/cluster/shards`	Shard listing
`POST`	`/admin/cluster/shards/rebalance`	Trigger shard rebalancing
`GET`	`/admin/cluster/maintenance`	Maintenance mode status
`POST`	`/admin/cluster/maintenance/enable`	Enter maintenance mode
`POST`	`/admin/cluster/maintenance/disable`	Exit maintenance mode

Admin — API keys

Method	Path	Description
`POST`	`/admin/keys`	Create a global API key
`GET`	`/admin/keys`	List all API keys
`GET`	`/admin/keys/{id}`	Get key details
`DELETE`	`/admin/keys/{id}`	Delete a key
`POST`	`/admin/keys/{id}/deactivate`	Deactivate a key
`POST`	`/admin/keys/{id}/rotate`	Rotate a key
`GET`	`/admin/keys/{id}/usage`	Key usage statistics

Admin — storage & indexes

Method	Path	Description
`GET`	`/admin/indexes/stats`	Index statistics
`POST`	`/admin/indexes/rebuild`	Rebuild indexes
`GET`	`/admin/cache/stats`	Cache performance stats
`POST`	`/admin/cache/clear`	Clear cache
`POST`	`/admin/cache/warm`	Warm cache
`POST`	`/admin/fulltext/reindex`	Reindex full-text
`GET`	`/admin/storage/tiers`	Storage tier overview
`POST`	`/admin/ttl/cleanup`	Manual TTL cleanup
`GET`	`/admin/ttl/stats`	TTL statistics

Admin — AutoPilot, decay & config

Method	Path	Description
`GET`	`/admin/autopilot/status`	AutoPilot status and last-run stats
`PUT`	`/admin/autopilot/config`	Update AutoPilot config
`POST`	`/admin/autopilot/trigger`	Trigger AutoPilot cycle
`GET`	`/admin/decay/config`	Get decay config
`PUT`	`/admin/decay/config`	Update decay config
`GET`	`/admin/decay/stats`	Decay statistics
`GET`	`/admin/config`	Get server config
`PUT`	`/admin/config`	Update server config

Admin — quotas

Method	Path	Description
`GET`	`/admin/quotas`	List all quotas
`GET`	`/admin/quotas/default`	Get default quota
`PUT`	`/admin/quotas/default`	Set default quota
`GET`	`/admin/quotas/{ns}`	Get namespace quota
`PUT`	`/admin/quotas/{ns}`	Set namespace quota
`DELETE`	`/admin/quotas/{ns}`	Delete namespace quota

Admin — backup & recovery

Method	Path	Description
`GET`	`/admin/backups`	List backups
`POST`	`/admin/backups`	Create a backup
`GET`	`/admin/backups/{id}`	Get backup details
`DELETE`	`/admin/backups/{id}`	Delete a backup
`GET`	`/admin/backups/{id}/download`	Download backup file
`POST`	`/admin/backups/upload`	Upload backup for restore
`POST`	`/admin/backups/restore`	Restore from backup
`GET`	`/admin/backups/restore/{id}`	Get restore status
`GET`	`/admin/backups/schedule`	Get backup schedule
`POST`	`/admin/backups/schedule`	Update backup schedule

Admin — monitoring

Method	Path	Description
`GET`	`/admin/slow-queries`	List slow queries
`GET`	`/admin/slow-queries/summary`	Slow query summary
`DELETE`	`/admin/slow-queries`	Clear slow query log
`POST`	`/admin/encryption/rotate-key`	Rotate encryption key
`GET`	`/admin/background-activity`	Background task status
`GET`	`/admin/memory-type-stats`	Memory type distribution