3. HTTP API

Base: http://127.0.0.1:<port>. All JSON responses carry Cache-Control: no-store. Pages carry Content-Security-Policy: frame-ancestors 'none' and X-Frame-Options: DENY.

3.1 Guards

The server also binds to 127.0.0.1 only. The Host check defeats DNS rebinding; the Origin check defeats a web page POSTing to your local port.

Errors are {"error": "<message>"}. Validation errors are 400 {"error":"Invalid request body.","details":[{path,message}]}. An unknown route is 404 with an HTML Cannot <METHOD> <path> body, like Express.

3.2 Routes

Static

GET /api/work-view — the snapshot

Returns the whole page state. Top-level fields, in order:

Request fields: id, conversationKey, conversationKeys, original{text,source,sourceId,url,promptNumber,atEpoch}, explicitRequestText, scopeUpdates[], projects[], agentIds[], items[], workstreams[], updatedAtEpoch, explicitRequestId, groupId, workProduct[], activity[], lifecycle, startedAtEpoch, progress (Review|null), completedAtEpoch, requestedBy(+Source), shipEstimate(+Source), stageSourceText, stageSource, afterShip, title, titleSource, sourceContentHashes[], contentFingerprint, review{checked,checkedAtEpoch,actor,available}, humanCopy{state,...}, goals?[]. titleSource is one of title-cache, request-group, explicit-work-state-request, original-human-request. humanCopy.state is current, outdated, pending or unavailable.

Agent fields: id, kind (session|recorded-owner|unassigned), label, platformSource, agentId, agentType, sessionId, contentSessionId, sessionTitle, recordedSessionStatus, project, projects, inCurrentScope, identityEvidence, presence{status: recent|quiet|unknown|finished, isLive, evidence, lastActivityAt, finishedAt?}, isSubagent, launch, work[], activity[] (<=8), counts{work,open,done}, canMarkFinished. presence.status is recent when the last activity is within 15 minutes, else quiet; finished when a stop was recorded at or after the last activity.

GET /api/work-view/events — server-sent events

Headers Content-Type: text/event-stream, Cache-Control: no-cache, no-transform. Frames:

retry: 1000

event: work-view
data: <full snapshot JSON>

event: heartbeat
data: {"at":"<ISO>","source":{...}}

work-view is sent on connect and whenever [revision, source.connected, source.error, setup] changes (polled every ALETHEIA_POLL_MS). heartbeat every 15 s. The original also sends setup-scan, setup-state and setup-import while its onboarding runs; the clone never does.

GET /api/work-view/evidence/:kind/:id

kind is work-state, observation, prompt, summary, session or tool-use; id a positive integer. Returns {kind, ...row} (columns in 02), 404 {"error":"Recorded evidence not found."}, or 400 {"error":"Invalid id"}. Tool input and response are cut to 4000 characters.

GET /api/work-view/file/:kind/:id/:index

Serves a deliverable file recorded in an observation (files_modified[index]) or a work-state entry (work_product list item index). Only when the path is absolute, has no .., has an allowed extension (images, video, pdf, docx, pptx, key, xlsx, csv, html) and exists as a regular file. Headers: X-Content-Type-Options: nosniff, Content-Security-Policy: sandbox allow-scripts.

POST /api/work-view/review

Body {requestId: string(1..2000), expectedFingerprint: 64 hex, checked: boolean} (no other keys). 200 returns the new snapshot. 404 unknown request. 409 {error, snapshot} when the fingerprint is stale ("This work changed...") or when checking a request not reported complete. 503 when the source is disconnected or review storage is down.

A request is reported complete when its review shows percent == 100 (and, if an explicit lifecycle exists, the review was checked at or after it), or its explicit lifecycle says complete: true or a status in done, completed, complete, shipped, delivered, needs-review, review, in-review, awaiting-review, ready-for-review.

POST /api/work-view/rules

Body {action, ruleId?, rule?}; rule is {scopeTier: everywhere|project|situation, scopeName (<=80), when (<=300), then (1..600, trimmed)}.

A project or situation rule needs a non-blank scopeName (400). An unknown rule is 404. 200 returns the snapshot, after rewriting MY-RULES.md and notifying event clients.

POST /api/work-view/agents/mark-finished

Body {agentGroupId}. Only for a subagent (isSubagent, with agentId and contentSessionId) that canMarkFinished; else 409. Appends an agent-lifecycle entry with stop_source: "owner-marked-finished".

POST /api/work-view/rules/load-in-claude-code

Rewrites MY-RULES.md and, unless a line equal to @<rules path> already exists, appends that line to the instructions file (adding a newline first when the file does not end in one). Idempotent. Returns the snapshot.

POST /api/work-state/entries

Used by save_goals.py. Body {cwd: string, list: string(1..200), fields: object}. fields has at least one key; values are string, boolean, finite number or null; keys non-empty; at most 2000 characters as JSON. list = "my-rules" is refused (403). Plain-text reply Saved to "<list>" in <project>. where <project> is the project key of cwd. The clone writes to the overlay store.

Setup

GET /api/setup/state always returns {status:"complete", ...}. GET /api/setup/scan returns the idle scan state. Every POST /api/setup/* returns 404 {"error":"Account setup is not part of aletheia-mem."}. The original's onboarding (choice of local or hosted memory, checkout, history import) is account and billing flow with no meaning here.

3.3 Behaviour not guaranteed identical

The exact wording of validation errors (the original uses zod) and the 404 HTML body are reproduced from observation, not from source.

3.4 Team mode (T-112)

Team routes serve the same store as 31-team.md. /v1/team/* needs Authorization: Bearer <sync token>; a read needs any valid token and a write needs sync or admin. /api/hub/team/* is the guarded local Hub route and acts as the local operator. Bodies are JSON; team_id accepts a numeric id or the team name.

Failures: 401 for a missing, revoked or expired token (member_revoked, token_revoked); 403 for the wrong role or a project the member does not share (viewer_read_only, project_forbidden, not_member); 404 for an unknown team, member or project; 400 for a duplicate team name, the last owner, or a malformed body.

The store check is the gate: TeamStore.authorize() runs for the HTTP route, the CLI and a direct store call. A route cannot bypass it, and a test calls the store directly to prove that.

3.5 Erasure (T-113)

These routes are the guarded local UI/admin path. The CLI is aletheia erase ...; both call the same modules.

before is an epoch or an ISO date and means created_at_epoch < before. ids accepts 12 (memory #12) or memory:12, fact:12, observation:12, episode:12. A plan follows provenance: a memory's episode, its observation, the facts on that observation/episode, and the summaries, keys, links, dismissals and review rows that point at them. apply removes the hub rows and their FTS entries, the vectors, the device replica/outbox when one is local, and asks the sync store for a T-103 purge, which drops every op body and leaves a tombstone with a null payload. The receipt records counts and ids, never text; it is signed with HMAC-SHA256 over the key-sorted body with the local key at ~/.aletheia/erasure.key (mode 0600).

An erasure of an offline device's copy is not possible from here: revoke its token and wipe the device. An E2EE account cannot be matched by project or content id, so pass the entity ids explicitly or purge on the device that holds the key.

3.6 Alerts (T-114)

The guarded local UI/admin path. The CLI is aletheia alerts .... Events: device.paired, token.revoked, quota.hit, sync.error, extraction.failed, queue.depth. A rule either appends one JSON line to a local file or POSTs to a webhook. A webhook body is signed with X-Aletheia-Signature: sha256=<hex> (HMAC-SHA256 over the exact body) when the rule has a secret.

Delivery rules: countThreshold N waits for N events in windowS; minValue gates a numeric event such as queue.depth; rateLimitS allows one delivery per rule per window. A 2xx is final; 5xx/429, a timeout or a network error retries with exponential backoff (1 s, 2 s, 4 s, ..., capped at 60 s) up to five attempts; other 4xx and a refused target fail immediately. A webhook target that resolves to a private, loopback or link-local address is refused unless the rule sets allowPrivate. A name that does not resolve is refused (fail closed). sync.error fires from the sync server's 500 path; device.paired from a successful join; token.revoked from /v1/sync/revoke; quota.hit when a push hits a quota; extraction.failed and queue.depth from the extraction worker. An alert store or delivery failure never takes the server or the queue down.

3.7 Requests, goals, story and economics (T-152, T-165 to T-173)

The universal /v1 API also answers the Work views. These routes are read-only except for dismiss/restore and the rule decide actions. Every number comes from a stored row; an empty store returns empty arrays and empty: true. Full field descriptions and real samples are in 32-requests.md.

The CLI equivalents: aletheia context economics [--project p] [--limit n] and aletheia rules suggest.