---
title: API reference
description: 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](https://api.openmemory.sh/docs)
- OpenAPI 3.0.3 document: [https://api.openmemory.sh/openapi.json](https://api.openmemory.sh/openapi.json)

The `operationId` values are stable. Tool generators that import the OpenAPI document (for example [Guild](/docs/guides/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](/docs/mcp-tools). |

## Conventions

- Request and response bodies are JSON. Times are ISO 8601 with an offset (`2026-11-05T09:00:00Z`). Dates are `YYYY-MM-DD`.
- Creates return `201`. Idempotent repeats (same fact, same record key, same action key) return `200` with `"created": false`.
- Errors are `{"error": {"code", "message", "details"?}}`. Status codes are listed in [Concepts](/docs/concepts#errors).
- Ids are prefixed: `sp_` (space), `mem_` (memory), `rec_` (record), `dr_` (dream run). Actions use short ids per space (`A1`).