HTTP API

The memora binary serves the HTTP API, the MCP endpoint, the OAuth endpoints, the web UI, and the WebSocket on one port. This document lists the HTTP endpoints.

Authentication#

The Auth column in the tables below uses these levels:

• None: reachable without credentials.
• Session: requires the memora_sess cookie set by a successful login.
• Key (scope): an API key sent as Authorization: Bearer <key> or X-API-Key: <key> that carries the named scope.
• Session or key (scope): either of the above.
• Session only: an API key is not enough. API keys get 401 (or 403 where noted).
• +CSRF: the same-origin check described below applies.

API key scopes#

A key carries any of the scopes mcp, read, write, and admin. New keys get mcp, read, and write unless other scopes are requested. The scope a route needs is decided by its path and method:

A key without the needed scope gets 403 {error, required_scope}. A missing key gets 401; for /mcp the 401 carries a WWW-Authenticate header, Bearer resource_metadata="<base>/.well-known/oauth-protected-resource", so OAuth capable clients can start sign-in. An invalid key gets 401 and is logged; an IP that keeps presenting invalid keys is put on a cooldown (429).

/api/auth/* never accepts an API key: without a valid session it answers 401.

API keys see the vault through their privacy rules (see Privacy): notes and folders hidden from a key behave as if they do not exist. A browser session sees everything.

CSRF#

Write endpoints that accept a session check the request origin whenever a session cookie is present: Origin (or, without it, Referer) must match the request Host (or an X-Forwarded-Host sent by a trusted proxy), and Sec-Fetch-Site: cross-site is refused. A failed check is 403 {"error":"origin mismatch"}. Requests without a session cookie (API-key clients) pass, since a browser cannot attach an API key on its own.

The public auth forms (/api/auth/login, /api/auth/verify, /api/auth/bootstrap, /api/auth/reset) also refuse a foreign or null Origin when no cookie exists yet. A request with neither Origin nor Referer (curl, the CLI) passes.

Locked instance#

While the instance is LOCKED, /api/* and /mcp answer 423 {error, locked: true, hint} except for /api/auth/state, /api/auth/verify, /api/auth/login, /api/auth/logout, /api/auth/bootstrap, and /api/auth/reset. Other pages redirect to /login?locked=1; static assets, /login, /logout, /healthz, and /favicon.ico are still served. /api/auth/login itself answers 423 while locked.

Vault not configured#

Until a vault folder is configured, /mcp and every /api/* route except /api/auth/*, /api/settings*, /api/config, /api/keys*, /api/tools, /api/access*, and /api/ui/* answer 409 {"error":"vault not configured", "needs_vault":true}.

Limits and other gates#

• Requests for a host outside the configured domain list get a bare 404.
• Access rules (see /api/access) can block a caller: 403 {"error":"access denied by stack rule", ip}.
• Per-IP rate limits answer 429 with a Retry-After header and {error, limited, cooldown, retry_after}. Login, code check, setup, reset, profile, password, and username changes have a stricter limit and a cooldown after repeated failed attempts. Requests from the machine itself and /healthz are not limited.
• A request that takes longer than 30 seconds is answered with 408.
• A password hashing pool that is busy answers 503 with Retry-After: 2.

Responses are JSON unless stated otherwise. Errors are {"error": "..."}. Vault errors map to 404 for not-found (including paths hidden from the caller) and 400 for bad input.

Health and discovery#

Auth#

Pages#

App routes are the web app's client-side pages: /brain, /nodes, /graph, /canvas, /tags, /activity, /agents, /access, /settings, /overview, /welcome, the older names /home, /vault, /logs, /keys, and /node/ or /node/<percent-encoded vault path>. The path is never used to read a file; a path holding NUL or another control character (raw or percent-encoded) is 400. /tools is an app route for a signed-in browser and the public tool catalog otherwise.

HTML pages are sent with Cache-Control: no-cache, no-store, must-revalidate and a per-response CSP nonce.

Any other GET that asks for HTML (Accept: text/html), is outside /api/, /mcp, /oauth, and /.well-known, and has no file extension in its last segment gets the app shell (which shows its "page not found" view). Every other unmatched request is 404 {"error":"not found"}.

Static assets#

Vault#

The three folder operations also publish a folder_changed realtime event so open browsers reload their tree.

Search and graph#

Privacy#

Privacy rules hide notes or folders from chosen agents (API keys). A rule has a kind (node or folder), a path, a mode (deny: hidden from the listed keys; allow_only: hidden from every key except the listed ones), and a list of keys. Folder rules apply to everything inside the folder.

Changes are written to the activity log and publish a privacy_changed realtime event.

API keys, tools, and access#

Settings#

All settings endpoints need a signed-in browser.

Session id values are the short ids returned by GET /api/settings/sessions (a unique prefix also works). An ambiguous or malformed id is 400.

OAuth#

Memora is an OAuth 2.1 authorization server for remote MCP clients. Only the authorization code flow with PKCE (S256) is supported. The access token is a new API key named after the client, with the default scopes (mcp, read, write) and every tool; it appears on the Agents page like any other key and is revoked by deleting or disabling that key. URLs in the metadata use MEMORA_BASE_URL when it is set, else the scheme and host of the request.

A client_id may also be an HTTPS URL of a client metadata document. The server fetches it (public addresses only, no redirects, at most 64 KiB), checks that its client_id matches the URL, and caches it for 24 hours.

Logs and activity#

Realtime#

On connect the server sends a hello event with the client count, replays the last 40 stored events (each marked replay: true), then streams live events. When a client leaves, the others get a presence event with the new count. Messages from the client are ignored; the server pings every 30 seconds and closes a connection that has been silent for 75 seconds.

ai_activity events#

Every MCP tools/call publishes a start and an end event sharing call_id:

{"type":"ai_activity","phase":"start","call_id":"c1a2b3c4d5e6-0","actor":"research-bot",
 "actor_kind":"agent","actor_id":"k_1a2b3c4d","action":"read_memory","label":"Plan/Index.md",
 "paths":["Plan/Index.md"],"_ts":1760600000.12}
{"type":"ai_activity","phase":"end","call_id":"c1a2b3c4d5e6-0","actor":"research-bot",
 "actor_kind":"agent","actor_id":"k_1a2b3c4d","action":"read_memory","label":"Plan/Index.md",
 "paths":["Plan/Index.md"],"ok":true,"ms":2,"_ts":1760600000.12}

• actor: the API key's name (fallback: key id) with actor_kind: "agent"; for a browser session the username with actor_kind: "user". actor_id is the key id (or the username). Node events (node_created, ...) from the call carry the same actor.
• action: the tool name.
• paths: vault-relative note paths from the arguments (path, paths, from, to, old_path, new_path, into of merge_memory, source/target of find_path) plus note paths found in the result (search hits, the created or moved note), at most 20, each at most 512 bytes (longer paths are dropped). Whole-vault overviews (get_graph, list_memory, logs, ...) add no result paths.
• Read-only tools publish start after running (so it carries the result paths), immediately followed by end; mutating tools publish start before running and end after, with the result paths added.
• end adds ok, ms, and on failure error (at most 200 characters). label is at most 160 characters. _ts is the publish time in unix seconds. end events are realtime only: they are not written to .events.jsonl or the replay buffer.

UI layout#

name is [a-z0-9_-]{1,40} (else 400). API keys get 403. data is stored as serialized JSON of at most 512 KiB (413 above); the request body limit is 600 KiB. Layouts are stored in the ui_layout table of memora.db. The web UI uses them for canvas (card positions and frames) and graph (pinned positions).

Pins#

The owner's pinned notes and folders (the sidebar's Pinned list), shared by every browser and device of the instance.

kind is note or folder. path is vault-relative as the tree shows it (notes end in .md): absolute paths, .., empty or hidden segments, \, control characters and paths over 1024 characters get 400, as do more than 200 pins. API keys get 403 (agents use the MCP tools list_pins, pin and unpin). Bodies are limited to 256 KiB for PUT and 8 KiB for pin/unpin (413). missing is true when the path no longer exists, for example after a rename outside Memora; such a pin is kept until it is removed.

Renames, moves and deletes done by Memora (HTTP or MCP) rewrite or drop pins in the same database transaction, including pins on notes and folders inside a moved folder; moving an item to the trash or deleting it removes its pin, and deleting a folder removes every pin under it. Every change publishes a pins_changed realtime event with no other data; open browsers reload the list. Pins are stored in the pin table of memora.db.

Status codes#