Reference
API reference
Every OpenMemory REST endpoint with its method, path, and operationId. The full interactive reference and OpenAPI 3.0 document live at api.openmemory.sh.
Base URL: https://api.openmemory.sh. Authenticate with Authorization: Bearer om_... or X-API-Key: om_... on every endpoint except space creation.
- Interactive reference: https://api.openmemory.sh/docs
- OpenAPI 3.0.3 document: https://api.openmemory.sh/openapi.json
The operationId values are stable. Tool generators that import the OpenAPI document (for example Guild) use them as tool names.
Space
| Method | Path | operationId | Summary |
|---|---|---|---|
| POST | /v1/spaces | space_create | Create a memory space and get its key. No auth. Rate limited per IP. |
| GET | /v1/space | space_get | Settings, usage, limits, and delete_after. |
| PATCH | /v1/space | space_update | Change timezone or dream_mode. |
| DELETE | /v1/space | space_delete | Delete the space and everything in it. |
| GET | /v1/export | space_export | Export everything as JSON. |
Context and batch
| Method | Path | operationId | Summary |
|---|---|---|---|
| GET | /v1/context | context_get | Everything an agent needs at the start of a run, in one call. |
| POST | /v1/batch | batch_apply | Apply up to 50 writes atomically. |
Memories
| Method | Path | operationId | Summary |
|---|---|---|---|
| POST | /v1/memories | memory_remember | Remember a fact. Identical facts are returned, not duplicated. |
| GET | /v1/memories | memory_recall | Recall by words (q), subject, tier, or tag. |
| GET | /v1/memories/{id} | memory_get | Get one fact. |
| PATCH | /v1/memories/{id} | memory_update | Change a fact. |
| DELETE | /v1/memories/{id} | memory_delete | Delete one fact. |
| POST | /v1/forget | memory_forget | Hard-delete matching facts, records, and journal text. Supports dry_run. |
Journal
| Method | Path | operationId | Summary |
|---|---|---|---|
| PUT | /v1/journal/{date} | journal_put | Write the entry for a date (YYYY-MM-DD). merge: true appends. |
| GET | /v1/journal | journal_list | List entries newest first (from, to, kind, limit). |
Records
| Method | Path | operationId | Summary |
|---|---|---|---|
| POST | /v1/collections/{collection}/records | record_put | Create a record, or update the one with the same key. |
| GET | /v1/collections/{collection}/records | record_query | Query by status, key, due_before. Page with cursor. |
| GET | /v1/collections/{collection}/records/{id} | record_get | Get one record. |
| PATCH | /v1/collections/{collection}/records/{id} | record_update | Update with shallow merge and optional expected_version. |
| DELETE | /v1/collections/{collection}/records/{id} | record_delete | Delete a record. |
Actions
| Method | Path | operationId | Summary |
|---|---|---|---|
| POST | /v1/actions | action_propose | Propose an action that needs approval. Returns a short id (A1). |
| GET | /v1/actions | action_list | List actions, newest first. Default: open ones. |
| GET | /v1/actions/{id} | action_get | Get one action. |
| POST | /v1/actions/{id}/transition | action_transition | Compare-and-set status change (from, to, optional receipt). |
KV and events
| Method | Path | operationId | Summary |
|---|---|---|---|
| GET | /v1/kv/{ns} | kv_list | List keys in a namespace. |
| GET | /v1/kv/{ns}/{key} | kv_get | Get one value. |
| PUT | /v1/kv/{ns}/{key} | kv_set | Set a value. Optional compare-and-set with expected_version. |
| DELETE | /v1/kv/{ns}/{key} | kv_delete | Delete a value. |
| POST | /v1/events | event_append | Append to the capped event log. |
| GET | /v1/events | event_list | List events newest first (kind, since, before_id). |
Dreaming
| Method | Path | operationId | Summary |
|---|---|---|---|
| POST | /v1/dream | dream_start | Start a dream now (optional mode). |
| GET | /v1/dream/runs | dream_runs | List recent runs and their reports. |
| POST | /v1/dream/runs/{id}/undo | dream_undo | Undo every change a run made (within 7 days). |
| GET | /v1/dream/jobs/next | dream_job_next | Client mode: get the waiting job (start_if_due=true to start one). |
| POST | /v1/dream/jobs/{id}/result | dream_job_submit | Client mode: submit your model's JSON result. |
Service endpoints
These are not part of the OpenAPI document:
| Method | Path | Purpose |
|---|---|---|
| GET | / | Service name, version, and links. |
| GET | /health | {"ok": true} |
| GET | /openapi.json | The OpenAPI 3.0.3 document. |
| GET | /docs | Interactive API reference. |
| POST | /mcp | The MCP endpoint (Streamable HTTP). On https://mcp.openmemory.sh it is served at the root. See MCP tools. |
Conventions
- Request and response bodies are JSON. Times are ISO 8601 with an offset (
2026-11-05T09:00:00Z). Dates areYYYY-MM-DD. - Creates return
201. Idempotent repeats (same fact, same record key, same action key) return200with"created": false. - Errors are
{"error": {"code", "message", "details"?}}. Status codes are listed in Concepts. - Ids are prefixed:
sp_(space),mem_(memory),rec_(record),dr_(dream run). Actions use short ids per space (A1).