-
-
Notifications
You must be signed in to change notification settings - Fork 0
API Reference
zhiar edited this page May 29, 2026
·
1 revision
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).
Two ways to authenticate:
-
Session cookie (
mempalace_session) — issued byPOST /api/login, used by the browser UI. -
X-Auth-Tokenheader — setMEMPALACE_TOKENin 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.
| 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. |
| 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. |
| 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"}). |
| 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. |
| 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
versionsin the code.
| 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. |
| 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). |
| 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. |
| 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. |
| 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. |
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/palacereturns the whole palace in one JSON document — handy for scripts that want everything at once.
Next: Security & Safety .
Getting started
Using Apricity
- Browsing & Searching
- Writing & Editing
- Deleting & Recovering
- Knowledge Graph & Tunnels
- Notifications
Make it yours
Reference
Repo · MIT