API Reference

API Reference

Apricity is a JSON-over-HTTP server, so anything the UI does, you can script. This page lists the endpoints exactly as they exist in the current code (server.py).

Authentication

Two ways to authenticate:

• Session cookie (mempalace_session) — issued by POST /api/login, used by the browser UI.
• X-Auth-Token header — set MEMPALACE_TOKEN in the environment (see Configuration) and send it as a header for scripted access. Coexists with the cookie flow.

Endpoints marked open need no auth; auth endpoints require one of the two above.

Endpoints

Health, session & system

Method	Path	Auth	Purpose
GET	/health	open	Liveness + whether auth is active.
GET	/api/session	open	Current authentication state.
POST	/api/login	open	{username, password, remember} → issues a session cookie.
POST	/api/logout	open	Clears the session.
GET	/api/version	open	Installed + latest-available version info.
GET	/api/system	auth	System / runtime info for the About pane.

Palace data

Method	Path	Auth	Purpose
GET	/api/palace	auth	Full palace snapshot (wings, drawers, triples, stats).
GET	/api/search?q=…	auth	Filtered subset of drawers + triples.
GET	/api/taxonomy	auth	Current wing/room taxonomy tree.
GET	/api/checkpoint	auth	Recent "memories filed away" checkpoint state.

Memories

Method	Path	Auth	Purpose
POST	/api/memories	auth	File a new memory.
POST	/api/memories/update	auth	Patch content / wing / room of a drawer; supports ETag.
POST	/api/rename	auth	Rename a wing or room.
POST	/api/delete	auth	Delete a drawer, room, or wing ({scope, …, confirm:"DELETE"}).

Drafts

Method	Path	Auth	Purpose
GET	/api/drafts	auth	List drafts; ?id= returns one with body.
POST	/api/drafts	auth	Save a new draft.
POST	/api/drafts/update	auth	Replace a draft in place.
POST	/api/drafts/delete	auth	Remove a draft.
POST	/api/drafts/commit	auth	File a draft into the palace.

Recently deleted (versions log)

Method	Path	Auth	Purpose
GET	/api/versions	auth	List recently-deleted snapshots.
POST	/api/versions/restore	auth	Recreate a deleted drawer or tunnel from its snapshot.
POST	/api/versions/delete	auth	Remove one snapshot from the log.
POST	/api/versions/clear	auth	Wipe the snapshot log.

In the UI these power the Trash → Recently deleted view. The endpoints are named versions in the code.

Knowledge graph

Method	Path	Auth	Purpose
POST	/api/facts	auth	Add a knowledge-graph triple.
POST	/api/facts/invalidate	auth	Mark a triple as ended.
GET	/api/kg/query?entity=…&direction=…&as_of=…	auth	Query facts about an entity.
GET	/api/kg/timeline?entity=…	auth	Chronological view of an entity's facts.
GET	/api/kg/stats	auth	Knowledge-graph aggregate stats.
GET	/api/graph/stats	auth	Palace graph stats.

Tunnels

Method	Path	Auth	Purpose
GET	/api/tunnels?wing=…	auth	List tunnels (optionally by wing).
POST	/api/tunnels	auth	Create a tunnel (source/target wing+room, optional label & drawer bindings).
POST	/api/tunnels/delete	auth	Delete a tunnel (snapshotted first).
GET	/api/tunnels/find?wing_a=…&wing_b=…	auth	Find tunnels between two wings.
GET	/api/tunnels/follow?wing=…&room=…	auth	List tunnels reachable from a room.
GET	/api/traverse?start_room=…&max_hops=…	auth	Graph-traverse from a room (max_hops ≤ 5).

Diary

Method	Path	Auth	Purpose
GET	/api/diary?agent_name=…&last_n=…&wing=…	auth	Read agent diary entries.
POST	/api/diary	auth	Write a diary entry.

Notifications, preferences & maintenance

Method	Path	Auth	Purpose
GET POST	/api/seen	auth	Read / update notification seen-state (syncs LAN-wide).
GET POST	/api/preferences	auth	Read / write server-side UI preferences (default sort, auto-delete, notification settings…).
GET	/api/settings	auth	Whether credentials are configured + username.
POST	/api/settings/credentials	auth	Set or rotate username + password.
GET POST	/api/hooks	auth	Read / update hook settings (silent-save, desktop-toast).
POST	/api/check-duplicate	auth	Check whether content is a near-duplicate.
GET	/api/aaak-spec	auth	AAAK spec reference.
POST	/api/sync	auth	Sync from a project tree (slow; long timeout).
POST	/api/reconnect	auth	Force-reconnect the MemPalace backend.

Backup (export / import)

Method	Path	Auth	Purpose
GET	/api/export	auth	Export palace data as JSON (Settings → Backup).
POST	/api/import	auth	Bulk-import drawers from a JSON backup.

Example — file a memory from the command line

curl -X POST http://127.0.0.1:8765/api/memories \
  -H "Content-Type: application/json" \
  -H "X-Auth-Token: $MEMPALACE_TOKEN" \
  -d '{"wing":"notes","room":"general","title":"hello","content":"first memory from curl"}'

Tip: GET /api/palace returns the whole palace in one JSON document — handy for scripts that want everything at once.

Next: Security & Safety.