Docs
Ebb Memory Engine API
Production cognitive memory engine and multi-transport gateway for autonomous AI agents. Features continuous mass-dilated logarithmic decay, Hebbian co-activation networks, off-heap mmap storage, and unified enterprise security. Canonical public HTTP contract for Ebb client SDKs. Generated from the hosted FastAPI application. Excludes internal and admin routes. Protected operations require `Authorization: Bearer <token>` (security scheme `HTTPBearer`). The same routes accept an optional `X-API-Key` header and `X-Ebb-Namespace` to select a namespace. Error responses use the `ErrorResponse` envelope (`code`, `message`, `details`) plus FastAPI's `HTTPValidationError` for 422. SDK subset of the Ebb HTTP contract. Includes Memory, Tasks, Events, and Health. Omits admin, runtime config, provider probes, registration, password reset, and SSO.
Version 0.2.0. Same document as Redoc and Swagger UI.
Health
Liveness at GET /healthz and readiness at GET /readyz.
/healthzHealthz
health
Liveness probe endpoint.
Responses: 200 Successful Response · 400
/readyzReadyz
ready
Readiness probe endpoint.
Responses: 200 Successful Response · 400
Memory
Cognitive memory storage, fused 6-phase scoring retrieval, and synaptic reinforcement.
/api/v1/memory/rememberRemember
remember
Ingest observation into cognitive memory tier.
Parameters
- X-Ebb-Namespace header
Body RememberRequestModel, required. Required fields: content.
Responses: 201 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded
/api/v1/memory/remember/batchRemember Batch
rememberBatch
Batch ingest memories.
Parameters
- X-Ebb-Namespace header
Body BatchRememberRequestModel, required. Required fields: items.
Responses: 201 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded
/api/v1/memory/recallRecall Get
recallQuery
Retrieve memories using cognitive scoring scan (GET).
Parameters
- query query required
- limit query
- profile query
- min_score query
- domain query
- namespace query
- X-Ebb-Namespace header
Responses: 200 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded
/api/v1/memory/recallRecall Post
recall
Retrieve memories using cognitive scoring scan (POST).
Parameters
- X-Ebb-Namespace header
Body RecallRequestModel, required. Required fields: query.
Responses: 200 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded
/api/v1/memory/recall/federatedRecall Federated Get
recallFederatedQuery
Retrieve memories across multiple namespaces using federated rank fusion (GET).
Parameters
- query query required
- namespaces query
- limit query
- profile query
- min_score query
- domain query
- salience_weights query
- X-Ebb-Namespace header
Responses: 200 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded
/api/v1/memory/recall/federatedRecall Federated Post
recallFederated
Retrieve memories across multiple namespaces using federated rank fusion (POST).
Parameters
- X-Ebb-Namespace header
Body FederatedRecallRequest, required. Required fields: query.
Responses: 200 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded
/api/v1/memory/reinforceReinforce
reinforce
Reinforce Hebbian associations or memory trace.
Parameters
- X-Ebb-Namespace header
Body ReinforceRequestModel, required. Required fields: memory_id.
Responses: 200 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded
/api/v1/memory/dreamDream
dream
Trigger sleep consolidation generative replay rest cycle.
Parameters
- X-Ebb-Namespace header
Body DreamRequestModel, required.
Responses: 200 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded
/api/v1/memory/reflectReflect
reflect
Trigger self-model reflection and crystallization.
Parameters
- X-Ebb-Namespace header
Body ReflectRequestModel, required.
Responses: 200 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded
/api/v1/memory/wanderWander
wander
Trigger Default Mode Network stochastic associative walk.
Parameters
- X-Ebb-Namespace header
Body WanderRequestModel, required.
Responses: 200 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded
/api/v1/memory/introspectIntrospect
introspect
Retrieve cognitive state and topological graph summary.
Parameters
- namespace query
- X-Ebb-Namespace header
Responses: 200 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded
/api/v1/memory/statusStatus Endpoint
status
Retrieve health check and storage slab capacity stats.
Parameters
- namespace query
- X-Ebb-Namespace header
Responses: 200 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded
/api/v1/memory/why-notWhy Not
whyNot
Explain why candidate engram was dropped during retrieval.
Parameters
- X-Ebb-Namespace header
Body WhyNotRequestModel, required. Required fields: memory_id, query.
Responses: 200 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded
/api/v1/memory/tableList Memories
listMemoriesTable
Retrieve paginated and filtered table rows of memory traces via cursor or page seeking.
Parameters
- cursor query
- limit query
- tier query
- tags query
- tombstoned query
- search query
- namespace query
- page query
- page_size query
- min_importance query
- min_valence query
- max_valence query
- X-Ebb-Namespace header
Responses: 200 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded
/api/v1/memoryList Memories
listMemories
Retrieve paginated and filtered table rows of memory traces via cursor or page seeking.
Parameters
- cursor query
- limit query
- tier query
- tags query
- tombstoned query
- search query
- namespace query
- page query
- page_size query
- min_importance query
- min_valence query
- max_valence query
- X-Ebb-Namespace header
Responses: 200 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded
/api/v1/memory/vacuumVacuum Endpoint
vacuum
Reclaim slab space from tombstones and trigger deep consolidation.
Parameters
- X-Ebb-Namespace header
Body VacuumRequest, required.
Responses: 200 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded
/api/v1/memory/{memory_id}Get Memory Detail Endpoint
getMemory
Retrieve full details of a specific memory engram.
Parameters
- memory_id path required
- namespace query
- X-Ebb-Namespace header
Responses: 200 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded
/api/v1/memory/{memory_id}Update Memory Endpoint
updateMemory
Update cognitive attributes on an existing memory engram.
Parameters
- memory_id path required
- namespace query
- X-Ebb-Namespace header
Body UpdateMemoryRequest, required.
Responses: 200 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded
/api/v1/memory/{memory_id}Delete Memory Endpoint
forgetMemory
Tombstone (soft-delete) or physically purge a memory trace.
Parameters
- memory_id path required
- purge query
- namespace query
- X-Ebb-Namespace header
Responses: 200 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded
/api/v1/memory/{memory_id}/purgePurge Memory Endpoint
purgeMemory
Irreversibly physically destroy an engram across slabs, bundles, and graphs.
Parameters
- memory_id path required
- namespace query
- X-Ebb-Namespace header
Responses: 200 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded
/api/v1/memory/graph/overviewGraph Overview Endpoint
graphOverview
Sample topological nodes and Hebbian co-activation edges for 3D visualizers.
Parameters
- max_nodes query
- offset query
- namespace query
- X-Ebb-Namespace header
Responses: 200 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded
/api/v1/memory/{memory_id}/graphGet Memory Neighborhood Endpoint
getMemoryGraph
Retrieve synaptic neighborhood graph centered on a target memory trace.
Parameters
- memory_id path required
- depth query
- namespace query
- X-Ebb-Namespace header
Responses: 200 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded
/api/v1/memory/{memory_id}/vectorGet Memory Vector Endpoint
getMemoryVector
Retrieve 16-lane SIMD vector embedding for target memory trace.
Parameters
- memory_id path required
- namespace query
- X-Ebb-Namespace header
Responses: 200 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded
/api/v1/memory/melExecute Mel Endpoint
executeMel
Execute one or more MEL-001 (Memory Engine Language) statements.
Parameters
- X-Ebb-Namespace header
Body MelExecuteRequest, required. Required fields: script.
Responses: 200 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded
/api/v1/memory/remember/uploadRemember Upload Endpoint
rememberUpload
Sensory file/folder upload adapter returning 202 Accepted with background task descriptor .
Parameters
- wait query
- Idempotency-Key header
- X-Ebb-Namespace header
Responses: 202 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded
/api/v1/memory/{memory_id}/documentGet Memory Document Endpoint
getMemoryDocument
Reconstruct the full de-overlapped document from any constituent chunk memory ID.
Parameters
- memory_id path required
- namespace query
- X-Ebb-Namespace header
Responses: 200 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded
Tasks
Background document and folder ingestion task lifecycle, progress inspection, and cancellation .
/api/v1/tasksList Ingestion Tasks
listTasks
List background ingestion tasks visible to the authenticated caller.
Parameters
- status query
- namespace query
- limit query
Responses: 200 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded
/api/v1/tasks/{task_id}Get Ingestion Task
getTask
Retrieve status, counters, timestamps, and error summary for a specific ingestion task.
Parameters
- task_id path required
Responses: 200 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded
/api/v1/tasks/{task_id}Cancel Ingestion Task
cancelTask
Request cooperative cancellation of a queued or running ingestion task (idempotent).
Parameters
- task_id path required
Responses: 202 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded
/api/v1/tasks/{task_id}/cancelCancel Ingestion Task
cancelTaskByPost
Request cooperative cancellation of a queued or running ingestion task (idempotent).
Parameters
- task_id path required
Responses: 202 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded
Events
Server-Sent Events (SSE) memory lifecycle streaming with Last-Event-ID cursor replay.
/api/v1/events/streamEvent Stream
streamEvents
Stream live memory and ingestion lifecycle events over SSE with Last-Event-ID replay.
Parameters
- last_event_id query
- event_types query
- namespace query
- namespaces query
- Last-Event-ID header
- token query
Responses: 200 Successful Response · 422 Validation Error