REST routes

Everything is served under /api and speaks JSON. Requests and responses are validated with the schemas in Entities.

Authentication is a session cookie (nova_session) set by POST /api/auth/login. An unauthenticated call to a protected route returns 401 with an ApiError body:

{ "error": "unauthorized", "message": "Sign in to continue" }

In production the API lives at https://api.novaterra.world; in development it is http://localhost:8787. A route written GET|POST /api/x accepts both verbs at that path.

auth

Operation	Route	Notes
register	POST /api/auth/register	RegisterRequest -> AuthResponse. With an access code: as always, and the code skips every open-door check. Without one (Council 038 6-A, open door only): a proof-of-work answer, no disposable address, per-address and per-domain limits, never the owner seat, and a confirmation link the account must use before it can pay, be provisioned, spend credits or run Studio
login	POST /api/auth/login	LoginRequest -> AuthResponse
logout	POST /api/auth/logout	-> Ok
me	GET /api/auth/me	-> AuthResponse
waitlist	POST /api/auth/waitlist	WaitlistRequest -> Ok (public)
codes	GET|POST /api/auth/codes	owner only: list / mint {count, note} -> AccessCode[]
codesUnused	GET /api/auth/codes/unused	owner only: settings-page convenience, unused codes only -> AccessCode[] (added 2026-09-05, catalogued 2026-09-06)
codesRevoke	DELETE /api/auth/codes/:code	owner only: revokes an unused access code (400 if already used, or the bootstrap code) -> Ok (catalogued 2026-09-06; surfaced by tests/contracts/routes.test.ts)
logoutAll	POST /api/auth/logout/all	signs the caller out of every device -> {ok: true, revoked: number} (catalogued 2026-09-06; surfaced by tests/contracts/routes.test.ts)
sessions	GET /api/auth/sessions	the caller’s active sessions -> Array<{id, createdAt, expiresAt, current}> (token fingerprints only) (catalogued 2026-09-06; surfaced by tests/contracts/routes.test.ts)
sessionsRevokeOthers	DELETE /api/auth/sessions	revokes every other session, keeps this one -> {ok: true, revoked: number} (catalogued 2026-09-06; surfaced by tests/contracts/routes.test.ts)
waitlistRows	GET /api/auth/waitlist	owner only: waitlist rows as JSON -> Array<{email, name, why, createdAt}> (catalogued 2026-09-06; surfaced by tests/contracts/routes.test.ts)
waitlistCsv	GET /api/auth/waitlist.csv	owner only: CSV export (email,name,why,createdAt; RFC 4180; Content-Disposition: attachment) (catalogued 2026-09-06; surfaced by tests/contracts/routes.test.ts)
email	GET /api/auth/email	-> EmailStatus {email, verified, verifiedAt, pending, emailConfigured}. emailConfigured is false on a node with no RESEND_API_KEY, so the UI never offers a button that goes nowhere (added 2026-09-10). email is NULL for a being with no credentials row — the seeded citizens, and anybody who arrived other than by registering. That is “no address is set”, which is not the same fact as “no such account” and no longer answers 404 for it (2026-09-23)
verifySend	POST /api/auth/verify/send	the signed-in caller asks for a fresh confirmation link -> EmailStatus. Always the CALLER’s own address, taken from the session: an address in the body would be a way to post mail to a stranger from this node (added 2026-09-10). With no address set it sends nothing and answers the same shape, exactly as it already did for an address that is already confirmed (2026-09-23)
verify	POST /api/auth/verify	PUBLIC. VerifyEmailRequest {token} -> Ok. Consumes the link. No session needed: the token names the being, and a person clicking from their mail client is commonly not signed in (added 2026-09-10)
passwordResetRequest	POST /api/auth/password/reset/request	PUBLIC. PasswordResetRequest {email} -> Ok, ALWAYS, whether or not the address is known here. Same body and same timing either way: the mail is dispatched off the response path precisely so “did it take longer?” answers nothing. Rate limited per IP and per address (added 2026-09-10)
passwordReset	POST /api/auth/password/reset	PUBLIC. SetPasswordRequest {token, password} -> Ok. Spends the token inside the transaction that writes the password, drops EVERY session of that being, and marks the address confirmed — arriving through a link IS proof of control of it (added 2026-09-10)
codesSend	POST /api/auth/codes/send	owner only. InviteEmailRequest {email, note} -> InviteEmail. Mints a code and posts it, instead of the owner reading one off a screen and pasting it into a chat (added 2026-09-10)
codesSent	GET /api/auth/codes/sent	owner only -> InviteEmail[]: who was invited, whether the mail left, and whether the code has been spent. Carries a MASK (NOVA-••••-7F3K), never the code — a screen listing dozens of live bearer credentials is the finding this one exists not to repeat (added 2026-09-10)
door	GET /api/auth/door	PUBLIC -> DoorState {mode: ‘open’|‘invite’, reason, verificationRequired, challenge: {token, bits, expiresAt} | null, limits}. open on a Hall unless REGISTRATION_DOOR=invite (the owner’s kill-switch); invite on every other node. Each call mints a fresh signed proof-of-work challenge the register body must answer; nothing is stored until one is spent
waitlistNotify	POST /api/auth/waitlist/notify	owner only -> WaitlistNotifyResult {sent, failed, alreadyTold, total}. The one-shot “the door is open” letter to everybody on the waitlist. Refused (400) while the door is shut, because the letter would be false. Idempotent per address: a person told once is never written to again, and a failed send is retried on the next press

beings

Operation	Route	Notes
list	GET /api/beings	-> Being[]
get	GET /api/beings/:id	-> { …Being, soul?: Soul (systemPrompt stripped unless self/owner), summary?: string, online: boolean, citizen?: object } (comment corrected 2026-09-06; was documented as Being & { soul?: Soul })
updateMe	PATCH /api/beings/me	Partial<Being> -> Being
square	GET /api/beings/square	town square feed -> Message[] (thread kind square)
squarePost	POST /api/beings/square	{content} -> Message
lifeTick	POST /api/beings/life/tick	owner only: one beat of the Square’s life -> {posts} (additive 2026-09-05)
lifeGreet	POST /api/beings/life/greet	owner only: Luma greets me in the Square -> {posts} (additive 2026-09-05)

souls

Operation	Route	Notes
get	GET /api/souls/:beingId
update	PUT /api/souls/:beingId
recompile	POST /api/souls/:beingId/recompile
generate	POST /api/souls/:beingId/generate	{role?, archetype?, seed?} -> Soul & {archetype, source} (additive 2026-09-05)
affect	POST /api/souls/affect	{text} -> Affect {valence, arousal, needs[], label} heuristic, no spend (additive 2026-09-05)
drift	POST /api/souls/:beingId/drift	{event, minutes?} -> Soul with moved mood (additive 2026-09-05)

twin

Operation	Route	Notes
profile	GET|PATCH /api/twin/profile	-> Profile
preferences	PATCH /api/twin/profile/preferences	{<key>: value|null} -> Profile
memories	GET /api/twin/memories?q=&kind=&limit=	search (FTS + embeddings) -> Memory[]
search	GET /api/twin/search?q=&kinds=&limit=
memoryCreate	POST /api/twin/memories
memoryDelete	DELETE /api/twin/memories/:id
activity	GET /api/twin/activity	-> TwinActivity[]
learn	POST /api/twin/learn	{text, source} -> Memory[] extracted
sync	POST /api/twin/sync/:provider	trigger ingestion -> {started:true}
status	GET /api/twin/status	ingestion status per provider -> TwinStatus (added 2026-09-05)
reflect	POST /api/twin/reflect	run the reflection pass now -> {ran:boolean} (added 2026-09-05)
voiceStt	GET /api/twin/voice/stt	-> NodeSttStatus {available, reason, provider, requested, model, baseUrl, leavesDevice, destination, costsMoney, usdPerMinute, consentKey, consented, consentedAt, note}. leavesDevice is NOT provider !== 'local': a local tier with LOCAL_LLM_FALLBACK=openrouter sends the recording on whenever the home box is quiet, so it counts as leaving (CLAUDE.md invariant 5) (catalogued 2026-09-09)
voiceSttConsent	POST|DELETE /api/twin/voice/stt/consent	POST {consentKey} -> NodeSttStatus. Consent is bound to the DESTINATION (provider+fallback:model), not to the utterance: one agreement, void the moment any part of that fingerprint moves. The body must echo the key the sheet displayed, so an owner changing the tier mid-sheet is a 409 rather than a silent agreement to somewhere else. 400 when nothing leaves the device — there is nothing to agree to. DELETE withdraws it (catalogued 2026-09-09)
voiceTranscribe	POST /api/twin/voice/transcribe	multipart/form-data: one audio part (webm/ogg/mp4/m4a/mp3/wav/flac as MediaRecorder produces them, 8 MB cap) plus an optional language field -> NodeTranscript {text, language, audioSeconds, bytes, format, model, provider, leavesDevice, destination, costUsd, durationMs}. 403 until the destination above has been agreed to — the localStorage acknowledgement in apps/web/src/voice/settings.ts is a UI convenience, this is the gate. The recording is buffered in memory and never written to disk (catalogued 2026-09-09)
todos	GET /api/twin/todos?status=&projectId=&limit=	status is comma-separated TodoStatus (open|done|deferred|dropped) -> Todo[] {id, beingId, title, notes, status, priority, dueAt, projectId, memoryId, deferredCount, createdAt, updatedAt, completedAt}, sorted due-soonest first (nulls last) then newest created (catalogued 2026-09-06 — calendar/to-do/Hush build)
todoCreate	POST /api/twin/todos	{title, notes?, priority?, dueAt?, projectId?, memoryId?} -> Todo (catalogued 2026-09-06)
todo	GET /api/twin/todos/:id	-> Todo (catalogued 2026-09-06)
todoUpdate	PATCH /api/twin/todos/:id	Partial<{title, notes, priority, dueAt, projectId, memoryId}> -> Todo (catalogued 2026-09-06)
todoComplete	POST /api/twin/todos/:id/complete	-> Todo {status: ‘done’, completedAt} (catalogued 2026-09-06)
todoDefer	POST /api/twin/todos/:id/defer	{dueAt?} (defaults to +24h) -> Todo {status: ‘deferred’, dueAt, deferredCount: +1} — deferredCount lets the Hush gate notice a to-do that keeps getting kicked down the road (catalogued 2026-09-06)
todoDrop	POST /api/twin/todos/:id/drop	abandoned, distinct from completed -> Todo {status: ‘dropped’} (catalogued 2026-09-06)
todoDelete	DELETE /api/twin/todos/:id	-> Ok (catalogued 2026-09-06)
calendar	GET /api/twin/calendar?from=&to=	from/to required. The merged agenda: stored events plus any OPEN due-dated Signal in range not already linked to one (a bare schedule.create reminder) -> AgendaEntry[] {id, title, body, startAt, endAt, allDay, origin: ‘event’|‘signal’, signalId, eventId} (catalogued 2026-09-06)
calendarCreate	POST /api/twin/calendar	{title, description?, location?, startAt, endAt?, allDay?, recurrence?, projectId?, remind?} -> CalendarEvent, plus {signalId} when remind:true, which raises a linked reminder Signal through the same action.kind:‘schedule.fire’ path schedule.create uses (catalogued 2026-09-06)
calendarEvent	GET /api/twin/calendar/:id	-> CalendarEvent (catalogued 2026-09-06)
calendarUpdate	PATCH /api/twin/calendar/:id	Partial<calendarCreate body, minus remind> -> CalendarEvent (catalogued 2026-09-06)
calendarDelete	DELETE /api/twin/calendar/:id	-> Ok (catalogued 2026-09-06)
hush	GET|PUT /api/twin/hush	-> HushSettings {beingId, level: ‘normal’|‘fewer’|‘off’, quietStart, quietEnd (minutes since local midnight), dailyCap, mutedUntil, updatedAt}. PUT body {level?, quietStart?, quietEnd?, dailyCap?, muteHours?} — muteHours snoozes every proactive nudge for that many hours from now, 0 clears an existing snooze (catalogued 2026-09-06) UPDATED 2026-09-07: these settings are now enforced at the HUB (apps/api/src/twin/hush.ts’s gateAtHub, called by raiseSignal) rather than by each caller, so a new caller inherits them by default instead of by remembering. Quiet hours HOLD a proactive signal (raised with dueAt at the end of the window, withheld by computeNow’s isDue, no WS ripple) rather than dropping it - the PRD’s ‘2 things waited for morning’. The daily cap REFUSES (written with status dismissed for the audit trail, never published, never seen); the eleventh nudge is discarded, not queued, per the PRD’s own open question 1. priority: 'urgent' does NOT override the cap - that field is chosen by a model in muse/skills.ts and derived from a stranger’s email in twin/gmail.ts, so an urgency exemption would be handed to whoever wanted it most; the only trigger that passes the cap is system (core/budget.ts), which nothing outside this node can reach
hushHeld	GET /api/twin/hush/held	“what did I miss?” -> {settings: HushSettings, held: Nudge[], refused: Nudge[]} where Nudge is {id, title, body, kind, source, priority, createdAt, reason (the gate’s own sentence, not a rephrasing), heldUntil, countedAgainst: {used, cap}, why: the /api/twin/nudges/:id/why path}. A ceiling nobody can see the far side of is censorship with a friendly name, so a refused nudge is WRITTEN (status dismissed, action.hush stamped) rather than dropped, and this route is where the person sees what was kept from them and can raise the cap if they disagree. held and refused are separate because they are different facts - a held nudge is coming, a refused one never will be, and blurring them would let “waiting until morning” read as “gone”. Proactive signals only; local day; no model call (catalogued 2026-09-07)
nudgeWhy	GET /api/twin/nudges/:id/why	the defensibility surface for proactive nudges: “why was I told this” -> {title, because: string, basedOn: string[], evidence: EvidenceItem[]}. basedOn is unchanged (raw ids, kept for back-compat); evidence (additive, catalogued 2026-09-06) resolves each id against the being’s CURRENT data at READ time -> {id, kind: ‘memory’|‘todo’|‘event’|‘project’|‘unknown’, label: string, snippet?: string, gone: boolean} (rule-based only: table lookup + truncation, never a model call), so an edited memory shows its current text and a deleted one reads as e.g. “a memory you have since forgotten” (gone: true) instead of a bare id or a silently dropped item. because is rebuilt from that resolved evidence (“Based on 2 things it noticed: … and …”) rather than joining raw ids; when the signal was not raised via evaluateNudge (no basedOn), because falls back to “No record of why — this was not raised through the Hush gate” and both basedOn/evidence are [] (catalogued 2026-09-06) UPDATED 2026-09-07 (the Hush at the hub): additionally returns source and gate, which answer a DIFFERENT question from because - not what this is about, but how it reached you. gate is null for a signal raised before the hub existed; otherwise {trigger: ‘proactive’|‘responsive’|‘system’, decision: ‘raised’|‘held’|‘refused’, reason, heldUntil: ISODate|null, countedAgainst: {used, cap}|null (null unless proactive), key, at}. Read off the stamp raiseSignal wrote at the moment it decided, never re-derived - re-running the gate now would answer about today’s budget rather than about the moment the person was, or was not, interrupted. A refused signal is written with status dismissed and never published, so this route can say ‘you never saw this, and here is why’ instead of having nothing to answer from
account	GET /api/twin/account?from=&to=&limit=	-> ProactiveAccount {from, to, totals, acts: ProactiveAct[], truncated, waveAways: ProactiveWaveAway[], spend: ProactiveSpend, tape: ProactiveTapeLine}. Scoped from the session; from/to are ISO instants, defaulting to the last 7 days, and are echoed back so a client can never head a month of rows “this week”. An ACT is a Signal whose hub stamp says trigger: 'proactive' — the same definition tests/twin/hush-hub.test.ts enforces over every raiseSignal call site, read off action.hush and never re-derived; a row raised before the hub existed carries no stamp and is absent rather than guessed at. outcome is one of answered | waved-away | dismissed | never-seen | held | waiting | expired | not-known, and every member names a stored fact: waved-away is a preference Memory tagged hush-fewer + this act’s topic key (the most honest evidence in the product — a person saying “no, not that” about a KIND of act), never-seen is the hub refusing at the daily ceiling (written dismissed for the audit trail, never published, never on a screen — a naive read of the signals table reports these as things the person saw and cleared, which is the opposite), and not-known is reachable and stays reachable. NO QUALITY SCORE, ever: ProactiveAct.costUsd is null — NOT KNOWN — for every act except the rule-based overdue-to-do nudge, whose 0 is derived and not estimated, because nothing on this node records which model call produced which card and inferring one from adjacent timestamps is a guess dressed as a fact (LadderReport.wouldHaveCostUsd’s rule). spend is therefore the cost of RUNNING the loops in the stretch, by llm_calls.purpose, never divided through by the acts. tape is a stretch-level tally with attributable: false on it, because ExecutionTapeRow has no trigger field and may not grow one — the row hash commits to a fixed field list — so the one unambiguous number is broken out instead: refused, an execution the consent gate stopped. No model call, no write, and it raises NO Signal about itself: Council 013 warned that a proactive product’s own account must be a record you go and look at, not a queue that asks for you (added 2026-09-14)
presence	GET /api/twin/presence	-> PresenceResponse {presence: Presence (discriminated union; a stirring is UNSPELLABLE without a validated because {key, params} from the closed list in packages/contracts/src/presence.ts), mood: PresenceMood|null, silences: Silence[]}. Pure and cheap: local SQLite reads plus arithmetic, no model call, nothing written. silences is the audit trail for the five conditions under which the presence stays dormant even when the signal table has something (THE-LIVING-VOICE §4.2) — same posture as GET /api/twin/hush/held, because a silence that leaves no trace is indistinguishable from a bug. The server never returns present: that is a fact about one browser tab, and the shell swaps to it when the person opens the orb
presenceDismiss	POST /api/twin/presence/dismiss	PresenceDismissRequest {topic} -> Ok. Dismissal RAISES THE BAR (002 rule 2): the topic is written as a real preference Memory via hush.ts’s recordFewerLikeThis, so the presence goes back to dormant for that topic and stays there. The same store “fewer like this” already writes, deliberately — a person who dismissed the Muse twice about invoices has said one thing, not two

connections

Operation	Route	Notes
list	GET /api/connections	-> Connection[]
create	POST /api/connections	{provider, label?, config} -> Connection (config encrypted at rest)
delete	DELETE /api/connections/:id
gmailAuth	GET /api/connections/gmail/auth	redirects to Google
gmailCallback	GET /api/connections/gmail/callback
telegramPairing	GET /api/connections/telegram/pairing	-> TelegramPairing (added 2026-09-05)
providers	GET /api/connections/providers	-> ProviderDescriptor[]: every provider the registry holds, built-in or plugin-contributed, with the auth descriptor a connect flow is rendered from. Replaces the closed ConnectionProvider enum (added 2026-09-06, OS-PLAN wave G)
microsoftAuth	GET /api/connections/microsoft/auth	redirects to Microsoft Entra ID, or 400s with the missing environment variable NAMED. This node holds no Microsoft application and cannot register one — that is a human in Microsoft’s console — so refusing is the state this route is in on every fresh install, and the refusal is the deliverable: it prints which of MICROSOFT_CLIENT_ID/MICROSOFT_CLIENT_SECRET is unset, where to register, which delegated permissions to grant (offline_access, openid, email, User.Read, Mail.Read) and the exact redirect URI to paste, built from the live environment so it is the URI this server will actually send. The owner’s wording and a citizen’s are different: only the person who runs this server is told about server environment variables (added 2026-09-23, Council 036 §2.2 + R4)
microsoftCallback	GET /api/connections/microsoft/callback	Entra redirects the person’s browser here after consent. SIX named outcomes, each one recorded on the twin activity stream before the redirect (?microsoft=connected|denied|expired|unconfigured|norefresh|error#connections) — norefresh is a grant with no refresh token, which is an application registration missing offline_access and would otherwise produce a connection that works for one hour and then reports a withdrawn sign-in that never happened; it is REFUSED rather than saved. error_description from Entra is not parsed, logged or stored. The state nonce is bound to (app, session being) and is single-use (added 2026-09-23)
driveAuth	GET /api/connections/drive/auth	redirects to Google’s consent screen, or 400s with the missing environment variable NAMED. Same shape as the Microsoft pair above and the same reason: nobody in this repository can register an application, so refusing is the state this route is in on a node that has set up neither Gmail nor Drive, and the refusal is the deliverable. It prints which of GOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRET is unset, where to register, the single scope (https://www.googleapis.com/auth/drive.readonly, read-only and nothing more), the exact redirect URI to paste (built from the live port, not a constant), AND the two console steps no environment variable can check - the Drive API enabled in the project, and the operator on the OAuth consent screen’s test-user list, because drive.readonly is a RESTRICTED scope and both omissions refuse AFTER the person has consented. ⚠️ It deliberately shares GOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRET with Gmail, because they name ONE Google application; so on a Gmail-configured node this route does NOT refuse, which is true - the client exists - and whether that project can actually serve Drive is discovered by asking Drive at the callback, before any row is written. Authorise carries access_type=offline and prompt=consent, NOT Microsoft’s select_account: Google issues a refresh token only on the first consent per (client, account), so without the forced prompt every Gmail-connected person would get a grant with no way to renew it (added 2026-09-24, Council 036 R4)
driveCallback	GET /api/connections/drive/callback	Google redirects the person’s browser here after consent. SEVEN named outcomes, each one recorded on the twin activity stream before the redirect (?drive=connected|denied|expired|unconfigured|norefresh|noscope|refused#connections). Seven rather than Microsoft’s six because Google has a failure Entra does not: noscope is a consent screen on which the person UNTICKED the Drive permission and continued - the token comes back with a scope missing what was asked for and every later request is a 403 that reads like a revoked grant, so the token response’s own scope is checked once, here, and named. refused is Drive itself refusing the brand-new grant (about.get), which is how the three invisible operator mistakes - API not enabled, scope absent from the consent screen, account not a test user - are told apart from a person saying no. All three refusals SAVE NOTHING rather than writing a green row that fails at the first sync. The query’s own scope is deliberately not read (it arrived via the browser) and Google’s free-text error fields are not parsed, logged or stored. The state nonce is bound to (drive, session being) and is single-use, so a state minted by the Microsoft start route cannot be redeemed here (added 2026-09-24)
slackAuth	GET /api/connections/slack/auth	redirects to Slack’s consent screen, or 400s with the missing environment variable NAMED. Same shape and same reason as the Microsoft and Drive pairs above - nobody in this repository can register an application, so refusing is the state this route is in on every fresh install and the refusal is the deliverable. It prints which of SLACK_CLIENT_ID/SLACK_CLIENT_SECRET is unset, where to register, the four read-only bot scopes (channels:read, channels:history, groups:read, groups:history - no chat:write, no im:history, no identity scope at all, because auth.test costs no scope and oauth.v2.access already returns the team), the exact redirect URI to paste (built from the live port, not a constant), AND the three console steps no environment variable can check: Slack accepts ONLY an https Redirect URL and rejects http://localhost, so a laptop node must set SLACK_REDIRECT_URI to an https address; the permissions go under Bot Token Scopes and not User Token Scopes; and somebody must then invite the app to a channel, because this node cannot add itself to one. The scope parameter is COMMA-separated, unlike every other OAuth provider in this tree (added 2026-09-25, Council 036 R4)
slackCallback	GET /api/connections/slack/callback	Slack redirects the person’s browser here after consent. SEVEN named outcomes, each one recorded on the twin activity stream before the redirect (?slack=connected|denied|expired|unconfigured|noscope|rotating|refused#connections). ⚠️ The code is redeemed by ./slack/tokens.ts and NOT by the shared exchangeAuthorizationCode, because oauth.v2.access answers HTTP 200 with {“ok”:false,“error”:”…”} - the shared postToken reads that as a success with no access token and loses the reason - and because a Slack bot grant carries no expires_in, which the shared parser would default to a fabricated hour on a credential that never expires. rotating is the mirror image of Drive’s norefresh: an app with token rotation switched on issues a 12-hour token this node has no machinery to renew, and it is REFUSED rather than stored. connected does NOT mean reading has started - a brand-new bot is in no channel, so completeSlackConnection asks users.conversations before it saves and writes the /invite sentence onto the activity stream at the one moment the person is looking. The state nonce is bound to (slack, session being) and is single-use (added 2026-09-25)

files

Operation	Route	Notes
list	GET /api/files?scope=&projectId=&path=	-> FileEntry[]
search	GET /api/files/search?q=	-> FileEntry[]
read	GET /api/files/read?id=	-> {content|base64, mime}
download	GET /api/files/download?id=	streams file. Answers HTTP range requests: Accept-Ranges/ETag/Last-Modified on every reply, 206 + Content-Range for a single byte range, 416 for one outside the file, 304 on If-None-Match, and the whole file when If-Range does not match. Always Content-Disposition: attachment — serving user files inline from the API origin would run an uploaded .html or .svg as markup with the session cookie; a <video>/<img> subresource ignores the header and plays the bytes anyway (range support added 2026-09-07)
downloadProject	GET /api/files/project/:projectId.zip
serveProject	GET /api/files/project/:projectId/*	static serve outputs (preview), inline, same range/conditional handling as download (range support added 2026-09-07)
upload	POST /api/files/upload	multipart -> FileEntry
write	POST /api/files/write	{path, content, scope} -> FileEntry
text	GET /api/files/text?id=&maxChars=	extracted text + metadata for any supported file, what the Twin indexes -> {id, name, size, supported, kind, pages, truncated, text, error} (catalogued 2026-09-06; surfaced by tests/contracts/routes.test.ts)
sheet	GET /api/files/sheet?id=&projectId=&path=&sheet=&maxRows=&maxCols=	by file id, or by projectId+path for a Studio output (Council 038 4-C; locateReadable checks it). An .xlsx/.xlsm as CELLS, for the table viewer, where text gives the index its words -> {id, name, size, totalSheets, maxRows, maxCols, sheets: Array<{name, rows: string[][], totalRows, totalCols, truncated}>}. totalRows is what the file holds, not what came back, so a viewer can say “5,000 of 214,388”. 400 for a non-spreadsheet or a workbook that will not parse; there is no silent empty table (added 2026-09-07)
thumbnail	GET /api/files/thumbnail?id=&projectId=&path=&w=&shape=	a webp PICTURE of a file, by file id or by projectId+path (a Studio output; locateReadable checks it against the session) -> image/webp. Council 038 7-H (2026-09-28): not only images any more — a PDF’s real first page (pdf.js), a document’s/Markdown’s/text’s/code’s first screen, a page’s structure, a sheet’s first rows, a deck’s first slide, an SVG through the safe-dialect rasteriser (never librsvg), a WAV/AAC waveform, an H.264 MP4’s first frame; kinds from contracts thumbnail.ts. w is snapped UP to 48|96|192|320|384|640 (a free-form width is an unbounded cache key); shape square (default, the list row) | card (4:3). 415 with {error:‘no_thumbnail’, name, reason} for what has no face (an archive, a binary), an SVG the dialect refuses, a file over its cap, or bytes that will not open — the card draws its type icon, so nothing renders as an empty box. ETag is the CONTENT hash + shape + width with private no-cache, so a versioned save (4-K) is a new picture and a restore is the old one back. Raster decode is libvips on the thread pool; a miniature is laid out as SVG and rasterised in JS; two at a time either way. The on-disk LRU under workspace/thumbs is bounded on bytes and entries (THUMBS_MAX_MB=64, THUMBS_MAX_ENTRIES=4000) and evicts to 80% of whichever ceiling it hit (added 2026-09-07; widened 2026-09-28)
projectRedirect	GET /api/files/project/:projectId	302 redirect to the trailing-slash static-serve route (serveProject) (catalogued 2026-09-06; surfaced by tests/contracts/routes.test.ts)
delete	DELETE /api/files?id=	removes a file/folder from disk + index; 403 on scope ‘user’ (read-only from the API) -> Ok (catalogued 2026-09-06; surfaced by tests/contracts/routes.test.ts)

fileEdits

Operation	Route	Notes
history	GET /api/files/versions?scope=&projectId=&path=	-> FileHistory {name, path, version, versions[]}, oldest first. A file nothing has saved over is version 1 with one entry
readVersion	GET /api/files/versions/content?scope=&projectId=&path=&version=	-> that version’s bytes as an attachment (never inline: an old .svg or .html is as scriptable as a new one). 404 for a version the lineage does not hold or whose kept copy is gone - said, never reconstructed
write	POST /api/files/versions	VersionedWriteRequest {scope, projectId?, path, content, encoding, note} -> VersionedWriteResult. Keeps the bytes that were there first (a snapshot written with wx, never overwritten), appends the lineage line, then writes. Identical bytes mint no version and answer changed:false. Creating a file that did not exist is version 1 with nothing kept. Decoded body capped at MAX_VERSIONED_WRITE_BYTES
restore	POST /api/files/versions/restore	RestoreVersionRequest {…, version} -> VersionedWriteResult. The old bytes become the NEWEST version; the one they replace is kept. There is no erasure
rename	POST /api/files/rename	RenameFileRequest {…, name} -> FileEntry. Same folder only (a name, not a path); 409 when the name is taken. The file’s lineage and kept copies move with it, so no version is orphaned
trim	POST /api/files/trim	TrimMediaRequest {…, startSeconds, endSeconds} -> TrimMediaResult. Cut without a decoder: mp4/m4v/mov/m4a by the existing ISO-BMFF stream copy (video.cut / audio.extract), wav on a sample frame, mp3/aac on an MPEG frame. Anything else is 415, named. Saved as a new version; startSeconds/endSeconds say where the cut actually landed. Calls no model
askQuote	POST /api/files/ask/quote	AskEditQuoteRequest {…, instruction, actionId?} -> AskEditQuote. actionId is a generated editor’s magic action; its brief is found server-side (editor-briefs.ts). SPENDS NOTHING. Says which route would carry the change (rewrite-text | rewrite-document | revise-producer | unavailable), why, the step that made the file when a Studio run did, and the estimate and ceiling. The quote is held in memory for 10 minutes and belongs to the session that asked
ask	POST /api/files/ask	AskEditRequest {quoteId, consent: true, maxUsd} -> AskEditResult. consent is z.literal(true): no yes, no parse, no call. 409 when maxUsd is below the quote’s ceiling or the quote is not the caller’s or has expired. The model’s output is bounded so the worst case stays under maxUsd; a rewrite that no longer parses as its own format is refused and nothing is saved. revise-producer keeps the current version first, then starts the targeted revision run and answers at once

editorSelection

Operation	Route	Notes
quote	POST /api/editors/selection/quote	SelectionEditQuoteRequest {editor, target, selection, instruction, actionId?} -> SelectionEditQuote. SPENDS NOTHING. Resolves the selection on the server, prices one L2 call routed by the action’s grades (never a model name), and refuses BEFORE the model: free tier (6-B ceiling L1), the node’s spend ceiling, no model, no route for the grades, a grounded action with no research files, a selection that is not there. Held 10 minutes, the session’s own
run	POST /api/editors/selection/run	SelectionEditRunRequest {quoteId, consent: true, maxUsd} -> SelectionEditResult. consent is z.literal(true). 409 below the ceiling, on another session’s quote, an expired one, or a target that moved since it was priced. The selection and its context reach the model inside the untrusted fence; the answer must parse as the editor’s SelectionPatch AND pass its check (checkSheetPatch/checkDocPatch/…) or NOTHING is written. Applied as one new version: one Yjs update in the doc’s log, a 4-K file version, or the books’ own record patch
undo	POST /api/editors/selection/undo	SelectionEditUndoRequest {editId} -> SelectionEditUndoResult. Takes one edit back as ONE new version, only when what it wrote is still what is there (409 otherwise, said). Held in memory per session for 30 minutes; after that the version history is the undo

audio

Operation	Route	Notes
mixFromProject	POST /api/audio/mix/from-project	MixFromProjectRequest {projectId} -> MixFromProjectResult {path, projectId, created, tracks[]}. The project is located from the SESSION (the files module’s project check). Reads the run’s piece.json, renders EACH part alone with the synthesiser audio.score used (packages/skills/src/music, no model, the same notes are the same samples) into stems/<part>.wav, and writes mix.nvmix with one track per part at the pan the piece gave it. Idempotent: an existing mix.nvmix is returned as it is (created:false), never overwritten. 403 for a project that is not the caller’s (the files module’s project check); 422 with a sentence when the run left no readable piece.json
save	POST /api/audio/save	AudioSaveRequest {scope, projectId?, path, content (base64 WAV), note} -> VersionedWriteResult. A render of the audio editor or a bounce of the mixer kept as a 4-K version (a new file is version 1). The path must end .wav and the bytes must DECODE with the node’s own WAV reader (decodeWav) or it is 422 and nothing is written. Decoded cap MAX_AUDIO_SAVE_BYTES (120 MB); the route’s body limit is sized for it. Calls no model

video

Operation	Route	Notes
export	POST /api/video/export	VideoExportRequest {scope, projectId?, path (.nvvideo), preset ‘360’|‘480’|‘720’|‘1080’, burnCaptions} -> VideoExportResult {path, version, seconds, width, height, hasAudio, bytes}. The timeline is located from the SESSION (locateRef); every source it names must stay inside its folder. Rendered on the node through the codec seam (packages/skills/src/media/timeline.ts: H.264 and AAC in, H.264 High + AAC-LC MP4 out; WebM/VP9, HEVC, MP3 and Ogg sources are 422 by name), READ BACK with the node’s own demuxer, and kept as a 4-K version of <name>.edited.mp4 beside the timeline; the sources are never written. 409 while another export renders on this node. Calls no model

ide

Operation	Route	Notes
workspace	GET /api/ide/workspace?scope=&projectId=&root=	-> IdeWorkspace: every file under the root (text loaded up to IDE_MAX_FILE_BYTES each / IDE_MAX_WORKSPACE_BYTES in all, the rest listed with why), folders, skipped folders (node_modules, dist…), its kind BY RULE (web | node | python | fullstack | mixed), the preview entry when one runs without a build, and whether a sandbox can run code here. Never lists .nv-revisions/.nv-trash/.sandbox
fs	POST /api/ide/fs	IdeFsRequest {op: create|mkdir|move|delete, workspace, path, to?, content?} -> IdeFsResult. create = version 1 through keepVersion; move keeps the lineage (snapshots and index move with the file); delete MOVES the file and its versions to .nv-trash/<stamp>/ inside the workspace - nothing is erased. user scope refused
check	POST /api/ide/check	IdeCheckRequest {workspace, overlays[]} -> IdeCheckResult {problems[], checked, notes[]}. The TypeScript compiler’s own diagnostics (syntactic for JS, syntactic+semantic for TS) read in memory - it parses, it never evaluates - plus JSON parse errors and Python SyntaxErrors computed by ast.parse INSIDE the sandbox. Uninstalled packages are declared untyped and NAMED in notes rather than reported per import
complete	POST /api/ide/complete	IdeCompleteRequest {workspace, path, content, offset, overlays[]} -> IdeCompleteResult {from, to, items[]}: the language service’s completions at the caret (in-file, project and lib symbols), filtered by the word being typed
hover	POST /api/ide/hover	IdeHoverRequest -> IdeHoverResult {signature, docs, from, to}: the compiler’s quick info for the name under the pointer
rename	POST /api/ide/rename	IdeRenameRequest {…, newName} -> IdeRenameResult {edits[] | null, note}: every place the compiler would rename, across the workspace. Writes nothing: the IDE applies the edits to its buffers and a save makes each a version
definition	POST /api/ide/definition	IdeDefinitionRequest -> IdeDefinitionResult {locations[]} inside the workspace (lib files are not returned)
symbols	POST /api/ide/symbols	IdeSymbolsRequest {workspace, path?, query} -> IdeSymbolsResult: one file’s outline (navigation tree) or every file’s symbols matching the query; Python’s def/class read by rule
format	POST /api/ide/format	IdeFormatRequest {workspace, path, content, tabSize, insertSpaces} -> IdeFormatResult {content, changed, by: typescript|json|none}. Writes nothing; the editor applies it and a save makes it a version
run	POST /api/ide/run	IdeRunRequest {workspace, target: {kind:file,path}|{kind:tests,path?}, timeoutMs, overlays[]} -> a STREAM (application/x-ndjson) of IdeRunEvent: start, out (stdout|stderr|system), test, end {exitCode, runtime, sandboxed: true, tests, wrote} | refused {no-sandbox|not-runnable|no-tests|too-large|unsandboxed}. Runs through runCode (nova-wasm first, fail-closed) on a SCRATCH COPY of the workspace, so the project never changes by running it

pdf

Operation	Route	Notes
apply	POST /api/pdf/apply	PdfApplyRequest {scope, projectId?, path, ops: PdfOp[], saveAs?, pictures: refuse|remove, breakSignatures, note} -> PdfApplyResult {write, savedAs, pages, redaction: PdfRedactionReceipt|null, signaturesBroken, notes}. Ops run in PDF_OP_ORDER (fill, annotation edits, annotations, images, flatten, redact, redactText, metadata, pages last), then every object nothing reaches is dropped and the file is saved as a new 4-K version (or, with saveAs, a NEW file beside it, never over one). REDACTION IS VERIFIED: the saved bytes are read back and REFUSED (422 pdf_survived, nothing written) if any glyph still lies under an area or a redacted phrase is still findable; a picture under an area is 422 pdf_picture unless pictures=remove, which takes the whole picture out. 409 pdf_signed when the file carries signatures and breakSignatures is false; 422 pdf_protected for an encrypted PDF (added 2026-09-29)
extract	POST /api/pdf/extract	PdfExtractRequest {…, pages: 0-based[], to} -> PdfExtractResult {entry, pages}. Split: the pages copied into a new PDF beside this one (a free name; nothing is replaced) (added 2026-09-29)
export	POST /api/pdf/export	PdfExportRequest {…, format: docx|md|txt, to} -> PdfExportResult {entry, pages, characters, note}. The WORDS, page by page (pdf.js text extraction): layout, pictures and fonts do not survive, and the note says so. 422 pdf_no_text for a scan — there is no offline OCR on this node (added 2026-09-29)
sign	POST /api/pdf/sign	PdfSignRequest {…, page, rect, appearance {kind, mime, data}, reason, consent: true} -> PdfSignResult {write, check}. consent is z.literal(true). Signs with the CALLER’S OWN Ed25519 key (their did:key; decrypted only inside core/identity.ts signAs) as an INCREMENTAL UPDATE: a visible stamp, the certificate as an attachment, and a /NovaterraSignature dictionary whose /Contents is Ed25519 over pdfSignedPayload(certificate, sha256 of every byte but the hole, /ByteRange). NOT PAdES: no X.509, no CA, no CMS; Acrobat shows the stamp and the attachment, not a signature. Read back and verified before it answers; kept as a new 4-K version (added 2026-09-29)
verify	POST /api/pdf/verify	PdfVerifyRequest FileRef -> PdfVerifyResult {scheme, signatures: PdfSignatureCheck[] {id, status: intact|changed-after|broken, certificate, knownAs: you|being|unknown, knownHandle, signedBytes, fileBytes, laterSignatures, note}, foreignSignatures}. Each signature checked on its own against the did:key its certificate names; another tool’s /ByteRange signature is counted, never judged (added 2026-09-29)

editorModules

Operation	Route	Notes
list	GET /api/editors/modules	-> EditorModuleList {modules: EditorModuleSummary[]}. The caller’s own registered modules, newest first; spec, manifest, match and conformance report, never the parity text
document	GET /api/editors/modules/:slug/document	-> EditorModuleDocument {id, version, runtimeVersion, html, bytes}. The frame’s BODY: the primitives runtime (esbuild, built once per process) and the spec as inert JSON — never a file’s bytes. 404 for a slug that is not one of the caller’s modules

archive

Operation	Route	Notes
list	GET /api/archive?grouping=&kind=&projectId=&order=&limit=&q=	the shelves and the Timeline, pre-banded -> ArchivePage. grouping: gallery (Recent -> one shelf per project, finished runs before abandoned ones, newest first within each -> kind) | timeline (by day) | flat (the complete list, never capped: that is the Files view’s whole promise)
search	GET /api/archive/search?q=&limit=	keyword (FTS5 over name, body, project_title, author_name and the kind/day labels the page prints) ranked FIRST, then semantic (embeddings) -> ArtefactSearchResponse. semantic:false means the vector leg did not run (no key, or nothing embedded yet) and says so rather than silently returning less; keyword:'unavailable' means the word index did not ANSWER, which is a different sentence from finding nothing
stats	GET /api/archive/stats	header counts, scoped to the viewer -> ArchiveStats
get	GET /api/archive/:id	one artefact with its provenance resolved; 404 when it is not the caller’s -> Artefact. Touches lastOpenedAt
thumbnail	GET /api/archive/:id/thumbnail?w=&shape=	a webp picture of an artefact, through the same renderers, bounds and on-disk LRU as GET /api/files/thumbnail (Council 038 7-H: documents, pages, sheets, decks, code, sound and film as well as images; shape=card is the 4:3 shelf card) -> image/webp. 415 {error:‘no_thumbnail’} for anything that cannot be drawn, which the Gallery answers with its type icon. Never a generated cover: an AI picture belongs to a PROJECT (coverImage)
reconcile	POST /api/archive/reconcile	the REPAIR tool, not the mechanism: walk the caller’s own project directories and index what write-time hooks never saw -> ReconcileResult
covers	GET /api/archive/covers	every one of the viewer’s projects with its shelf cover, or what one would be made of -> ArchiveCoversResponse {covers[], spentUsd, canGenerate}. READ ONLY: never builds, never spends, never opens a browser (added 2026-09-08)
coverImage	GET /api/archive/covers/:id/image	the stored cover bytes for one project -> image/webp, ETag + private no-cache. 404 when none has been built, which the shelf answers with its typographic plate rather than an empty frame (added 2026-09-08)
buildCover	POST /api/archive/covers/:id	BuildCoverRequest {force, allowModel} -> {cover: ArchiveCover, built, reason?}. The only route here that can spend: it prefers a REAL rendering (an image artefact’s bytes, or a Chrome screenshot of an HTML artefact, both free) and only asks the image model when the project made nothing anyone can look at. allowModel defaults FALSE, so the free button cannot become a paid one even when the page turns out to render blank. One project per call, never a batch, so a bill is approved item by item (added 2026-09-08)

threads

Operation	Route	Notes
list	GET /api/threads?kind=&q=	the inbox -> ThreadSummary[] = Thread[] (incl. the promoted replyPolicy) + additive {participants[], unread, lastAt, lastAuthorId, lastPreview, aiPolicy (deprecated mirror of replyPolicy)}. The square thread is deliberately not listed: it has no membership or read marker to list it by (see the header of apps/api/src/modules/threads/routes.ts)
create	POST /api/threads	{kind, title?, participantIds?, replyPolicy?} -> ThreadSummary. aiPolicy still accepted as the deprecated name for replyPolicy
get	GET /api/threads/:id	-> Thread (catalogued 2026-09-06; surfaced by tests/contracts/routes.test.ts)
messages	GET /api/threads/:id/messages	-> Message[]
send	POST /api/threads/:id/messages	{content, attachments?, rounds?: 1-4, replyPolicy?} -> Message (user). Assistant streams via WS message.delta then message.created. aiPolicy still accepted as the deprecated name for replyPolicy
nudge	POST /api/threads/:id/nudge	{openerId?, prompt?, rounds?: 1-4} -> {ok, threadId, openerId, rounds, mode: ‘open’|‘continue’} — carries an exchange on with NO human message: with a prompt the opener starts a line of talk in their own voice, without one the room answers what was said last. Owner only (turns are billed to thread.ownerId); 409 when the conversation’s replyPolicy is ‘none’; 429 {retryAfterMs} while an exchange is running or in its cooldown; 402 llm_budget when the budget is already spent; 503 llm_unavailable with no key. Turns arrive over WS (message.delta, message.created) exactly as a reply to a sent message does (added 2026-09-06)
delete	DELETE /api/threads/:id	owner only: deletes the thread and its messages -> Ok (catalogued 2026-09-06; surfaced by tests/contracts/routes.test.ts). Also forgets the room bound to it: channel binding, seats, sessions, meeting
channel	POST /api/threads/channel	OpenChannelRequest {groupId, title?} -> ThreadSummary. Opens (or returns) the ONE conversation a crew has with itself — the route that finally creates a ThreadKind 'agent', which nothing in the tree had ever written. Idempotent per group; every member is seated when it opens, whoever they are; lead-or-owner only, because the conversation is billed to whoever opens it; its replyPolicy is none because the floor answers here, not dm.ts’s free-for-all (added 2026-09-06)
join	POST /api/threads/:id/join	join a room you are entitled to be in -> ThreadSummary. A channel admits anyone of its crew; anything else admits only someone already a participant. Seats the caller, marks them present in the room, and marks the conversation read. Entitlement is derived from the session and the group, never from the request (added 2026-09-06)
session	POST /api/threads/:id/session	RunRoomRequest {prompt?, openerId?, maxTurns?: 1-12, maxUsd?, floorPolicy?} -> RoomSession. Ask the room to talk: the caller supplies at most a topic and a ceiling, and the room decides who speaks each turn. Owner only (a meeting’s chair uses POST /api/meetings/:id/run); 409 while a stretch is already running; 402 llm_budget; 503 llm_unavailable; 400 when this conversation is not a room, or nobody in it can be spoken for. A prompt is written into the transcript under the CALLER’s name, never a citizen’s. Turns arrive over WS as message.delta/message.created, and the floor moves over room.updated (added 2026-09-06)
sessionGet	GET /api/threads/:id/session	-> {session: RoomSession|null, floorBeingId, speakerIds[], presentBeingIds[]} — the running stretch or the last one, with what it used of its bound, whose turn it is, who may take one, and who is in the room. Presence is on this route as well as on the WS room.updated event because a client that has just arrived has missed every event so far: the event is the live update, this is the state (added 2026-09-06)
sessionStop	DELETE /api/threads/:id/session	stop a running stretch; the loop notices before its next turn -> {ok, session} (added 2026-09-06)
proposal	GET /api/threads/:id/proposal	-> ProposalView | null. The room’s ONE live proposal (R2: a property of the room, keyed by thread_id, so a second replaces the first), resolved for this reader: the target and every candidate re-derived from the live generators table and CAPABILITY_CATALOGUE, with per-step tiers so the browser prices it with the floorUsd it already has. target: null is the refusal — “nothing here has started; here is what could be”. Anyone in the room may read it; viewerIsOwner says who may act on it (added 2026-09-14)
proposalDelete	DELETE /api/threads/:id/proposal	owner only -> Ok. Throws the room’s proposal away. This is BOTH the decline and the second half of an accept, deliberately: a proposal that can only be destroyed cannot be escalated through, which is R3’s “deletable without any loss of authority” as a route table rather than as a sentence. Idempotent: deleting a room with no proposal is Ok (added 2026-09-14)

meetings

Operation	Route	Notes
list	GET /api/meetings	every meeting the caller convened or was seated in, newest first -> Meeting[] (added 2026-09-06)
create	POST /api/meetings	CreateMeetingRequest {title, agenda?, participantIds?, groupId?, floorPolicy?, maxTurns?, maxUsd?} -> MeetingDetail {meeting, participants[], session, myRole}. The caller is always chair and owner: turns are billed to them. participantIds and groupId are REQUESTS — every id must be a real being, and a group is expanded only when the caller is of it (added 2026-09-06)
get	GET /api/meetings/:id	-> MeetingDetail. Visible to its convener and to anyone seated in it; there is no “anyone with the link” (added 2026-09-06)
join	POST /api/meetings/:id/join	arrive: marks the caller present IN THIS ROOM -> MeetingDetail. 403 for someone who was not invited (added 2026-09-06)
leave	POST /api/meetings/:id/leave	step out: the seat and the turn count stay, only presence changes -> MeetingDetail (added 2026-09-06)
addParticipant	POST /api/meetings/:id/participants	chair only. {beingId, role?: chair|speaker|observer} -> MeetingDetail. observer is how somebody sits in a room the world never hands the floor to, and it is a property of the seat (added 2026-09-06)
removeParticipant	DELETE /api/meetings/:id/participants/:beingId	chair only -> MeetingDetail. 400 for the chair themselves (added 2026-09-06)
run	POST /api/meetings/:id/run	RunRoomRequest -> RoomSession. Chair or owner only (billed to the owner). Same refusals as the thread session route; maxTurns and maxUsd may be lowered for one stretch and never raised above the meeting’s own (added 2026-09-06)
stopRun	DELETE /api/meetings/:id/run	chair only: stop a running stretch -> {ok, session} (added 2026-09-06)
close	POST /api/meetings/:id/close	{summarise?: boolean = true} -> MeetingDetail with minutes written. THE ARTEFACT: markdown with attendance and turns per participant, the turn and spend accounting against the bound, the whole transcript, and — best effort only — a summary, decisions and actions from one cheap model call over a FENCED transcript. No key, no budget or a failed summariser still closes the meeting and still writes minutes; it never fails to close because the summariser could not run. The minutes are also appended to the transcript as a system message, where they cannot be lost (added 2026-09-06)
minutes	GET /api/meetings/:id/minutes	-> {meetingId, status, minutes: string|null}. Null until the meeting has closed (added 2026-09-06)

spaces

Operation	Route	Notes
list	GET /api/spaces	every space the caller may enter — public ones, theirs, ones they are admitted to, ones their group may enter — Square first, then homes, then newest -> Space[] (added 2026-09-06, spaces/groups build)
create	POST /api/spaces	CreateSpaceRequest {kind?, title, slug?, description?, visibility?, groupId?, parentId?, themeId?} -> SpaceDetail. Slug derived from the title when omitted, de-duplicated with -2/-3. visibility ‘group’ requires a groupId the caller is actually of (403 otherwise); parentId must be a top-level space the caller may enter (spaces nest one level, §1.2). The maker is admitted as its first member (added 2026-09-06)
home	GET /api/spaces/home	the caller’s own home space — every being has one, created by the lazy backfill in modules/spaces/store.ts -> SpaceDetail (added 2026-09-06)
get	GET /api/spaces/:id	by id OR slug -> SpaceDetail {space, members[], presentBeingIds[], threadIds[], canEnter, isMember}. 403 when the space is not open to the caller. GET /api/spaces/square is the Square as a space: public, the existing square thread as its stream, everyone online as its presence (added 2026-09-06)
update	PATCH /api/spaces/:id	owner only. {kind?, title?, description?, visibility?, groupId?, themeId?} -> SpaceDetail. Turning a space group-visible requires a groupId the caller is of (added 2026-09-06)
join	POST /api/spaces/:id/join	be in it: admits the caller when canEnter already says yes (public, or their group’s, or already admitted); 403 otherwise -> SpaceDetail (added 2026-09-06)
leave	POST /api/spaces/:id/leave	gives up admission -> SpaceDetail. 400 for the owner, who deletes the space instead of leaving it (added 2026-09-06)
delete	DELETE /api/spaces/:id	owner only -> Ok. 400 for a square or home space: the founding spaces are the world’s, not one being’s to unmake (added 2026-09-06)

groups

Operation	Route	Notes
list	GET /api/groups	the groups the caller is of, or owns, newest first -> Group[] (added 2026-09-06, spaces/groups build)
create	POST /api/groups	CreateGroupRequest {kind?, name, slug?, purpose?, members?: [{beingId, role?}], parentId?} -> GroupDetail. The maker is always seated lead; every named being is seated at the same moment, whoever they are. parentId puts the new group INSIDE another (a crew inside a company): 400 for a parent that does not exist or a placement past MAX_GROUP_DEPTH, 403 unless the caller also leads or owns the parent — containment is a claim about the parent too (parentId added 2026-09-06, group hierarchy)
get	GET /api/groups/:id	by id OR slug -> GroupDetail {group, members[], spaceIds[], myRole, ancestors[], children[]}. 403 unless the caller is of it or owns it — unchanged: being of a PARENT does not admit you here, because Group.parentId is descriptive and grants nothing. members is and stays the DIRECT roster; ancestors (root first) and children are names and kinds only, never rosters (ancestors/children added 2026-09-06, group hierarchy)
update	PATCH /api/groups/:id	leads only. {kind?, name?, purpose?, parentId?} -> GroupDetail. parentId: null makes it a root again. Moving it under another group needs lead-or-owner of BOTH ends and is refused (400) when the parent does not exist, is the group itself, is one of its own descendants (a cycle), or would push the subtree past MAX_GROUP_DEPTH (parentId added 2026-09-06, group hierarchy)
addMember	POST /api/groups/:id/members	leads only. AddGroupMemberRequest {beingId, role?} -> GroupDetail. Seats a being, or changes the role of one already seated. Validates that the being exists and the role parses — and nothing else, because nothing about a being’s kind can make a seat inappropriate (added 2026-09-06)
removeMember	DELETE /api/groups/:id/members/:beingId	a lead may unseat anyone; anyone may unseat themselves -> GroupDetail. 400 for the group owner, who disbands instead (added 2026-09-06)
delete	DELETE /api/groups/:id	owner only: disbands -> Ok. Spaces that pointed at the group keep their rows, lose the pointer and fall back to private visibility; project_crews and group_holdings rows for it are dropped, so a project whose crew is disbanded assembles automatically again (added 2026-09-06)
work	GET /api/groups/:id/work	-> GroupWork {groupId, seats[], projects[], contributions[], holdings[]}. What this crew has done: the reasoning episodes it was chosen for, what each seat did in them (tasks, done, cost), and what it works with. A read model over project_crews/projects/tasks/agents, stored nowhere. 403 unless the caller is of it. An agent that worked on a crew project without being seated or held appears as a contribution with role observer — a gap assembly had to fill, shown rather than absorbed (added 2026-09-06, crews build)
holdings	GET /api/groups/:id/holdings	-> GroupHolding[] {groupId, kind, itemId, label, addedBy, addedAt}. The agents and generators the group works with. 403 unless the caller is of it (added 2026-09-06)
addHolding	POST /api/groups/:id/holdings	leads only. AddGroupHoldingRequest {kind: ‘agent’|‘generator’, itemId} -> GroupHolding[]. 400 for an unknown kind or a missing row, 403 for something the caller does not own. This does NOT transfer ownership: agents.owner_id and generators.owner_id are untouched, so §5.1 rule 2 (“ownerId is always a being id”) stays literally true — a holding says reachable by this group (added 2026-09-06)
removeHolding	DELETE /api/groups/:id/holdings/:kind/:itemId	leads only -> GroupHolding[]. Takes it off the shelf; the agent or generator itself is untouched (added 2026-09-06)
treeMembers	GET /api/groups/:id/tree-members	-> GroupTreeMembers {groupId, groupIds[], members: [{beingId, groupId, role, depth, joinedAt}]}. “Everyone in this company”: the union of the DIRECT rosters of this group and every group beneath it, deduplicated by being, nearest group winning. Each row names the group the being is really of, so it can never be read as a membership of the group asked about. Lead-or-owner only — a stricter gate than the roster itself, because it reaches into groups the caller may not be of. NOTHING in the world’s authorisation path consults this: canEnter, listSpacesFor, listGroupsFor, roleOf and requireLead all still answer on direct membership only (added 2026-09-06, group hierarchy)

office

Operation	Route	Notes
propose	POST /api/office/proposal	OfficeProposalRequest {purpose, activities[]} -> OfficeProposal {purpose, activities[], roles: ProposedRole[], skillCount, generatorCount, missingSkillCount}. POST because the input is a document, not because it writes: this handler WRITES NOTHING and CALLS NO MODEL. It matches the person’s own lines against the persona table (@novaterra/agents) and against this node’s real skill registry and generator rows, so a proposal is deterministic, free, and the same twice. Every role carries because — the caller’s own activity lines, never a sentence the server composed — plus skills/missingSkills split against what this node can actually do, so “two more are on the Market” is visible at hiring time rather than at the first failed run (added 2026-09-13, W5 the rail + the office)
open	POST /api/office	CreateOfficeRequest {name, purpose?, activities[], roles[], autonomy?} -> OfficeOpened {group, spaceSlug, hired: OfficeHire[], autonomy, channelThreadId}. One transaction over routes that already exist separately: a group of kind company (caller seated lead), a private space pointed at it, one agent per accepted role — each raising a spark, exactly as POST /api/studio/agents does — seated in the group and shared onto its shelf. Refuses (400) a role the persona table does not recognise rather than quietly hiring a writer. roles[] accepts a bare persona role (researcher) or a role.* STANDING ROLE id (./roles.ts): a held post hires the persona holding it, a vacant one is refused with Nobody holds <id> yet — seven of the eight posts design/CAPABILITY-MAP.md §6 names are vacant and the Office will not pretend otherwise. autonomy is recorded as the office’s DEFAULT and grants nothing: every world-acting skill stays consent-gated at the point of use, whatever is chosen. The same transaction OPENS THE CREW’S CHANNEL (channelForGroup, the same call POST /api/threads/channel makes — one join, not two) and seeds it with an opening post: channelThreadId names it, and the post’s body is an OfficeOpeningPost document behind OFFICE_OPENING_TAG, never a sentence the server composed (added 2026-09-13, W5 the rail + the office; channel and opening post 2026-09-14)
recordTypes	GET /api/office/:officeId/record-types	-> RecordType[] with recordCount counted per request. What this company keeps: customers, jobs, invoices — each a declared set of named fields plus the relationships a record of that type may have (added 2026-09-13, W10)
recordTypeCreate	POST /api/office/:officeId/record-types	RecordTypeDraft -> RecordType (201). Rows in office_record_types, never DDL: Council 006 §2.1 names “let each office define tables” as the trap, because it is a database-as-a-service and therefore a product rather than a feature. Refuses (400) a draft whose titleField is not one of its fields, whose select has no options, or that declares TWO notes fields — the escape hatch is one named place (§2.4, Hopper’s ruling), not a habit (added 2026-09-13, W10)
recordTypePatch	PATCH /api/office/:officeId/record-types/:key	v.patchOf(RecordTypeDraft) -> RecordType. This is the route Council 006 §2.3 property 1 is about: adding boiler_model to customers needs no migration, no deploy and no engineer. Merged onto the type as it stands and the WHOLE result revalidated, so omitting fields keeps them and {fields: []} is refused; patchOf and not .partial() is what keeps those two different (added 2026-09-13, W10)
recordTypeDelete	DELETE /api/office/:officeId/record-types/:key	-> Ok. Refuses (409) while the type still holds records, naming how many. This is the undo for an import that guessed wrong, and the refusal is what stops it being the undo for a business (added 2026-09-13, W10)
recordTypeProposal	POST /api/office/:officeId/record-types/proposal	RecordSchemaProposalRequest {purpose, activities[]} -> RecordSchemaProposal {types: ProposedRecordType[], fieldCount, linkCount, rung: ‘L0’}. POST because the input is a document, not because it writes: WRITES NOTHING, CALLS NO MODEL, exactly like POST /api/office/proposal. A deterministic join over a library of seven business shapes (customer, lead, job, invoice, quote, supplier, appointment) in apps/api/src/modules/office/shapes.ts. Every type carries because — the caller’s own lines, never a sentence the server composed — and addedForLink flags the one proposed only because another points at it (added 2026-09-13, W10)
records	GET /api/office/:officeId/records?type=&limit=&offset=	-> OfficeRecord[], newest first, links included. type is required: “every row in the books” is not a question anybody asks and would be an unbounded read (added 2026-09-13, W10)
recordCreate	POST /api/office/:officeId/records	CreateRecordRequest {typeKey, fields, links[]} -> OfficeRecord (201). No id, no officeId, no createdBy, no title — all four are the server’s. An UNDECLARED field key is refused (400) listing the ones that are declared: an agent cannot reliably query what nobody described (§2.4), and a bag that accepts anything returns the office to a model reading every row. A rel the type does not declare is refused the same way, and a knowledge link is checked to point at a record of the declared type IN THIS OFFICE (added 2026-09-13, W10)
record	GET /api/office/:officeId/records/:id	-> OfficeRecord (added 2026-09-13, W10)
recordPatch	PATCH /api/office/:officeId/records/:id	v.patchOf(PatchRecordRequest) -> OfficeRecord. fields MERGES BY KEY and a null value deletes one — the PATCH /api/twin/profile/preferences shape, for that route’s exact reason: a record’s fields are a bag different callers each own one key of, and a whole-value replace lets the person updating a phone number erase the boiler_model somebody added this morning. links REPLACES when present and is untouched when absent (added 2026-09-13, W10)
recordDelete	DELETE /api/office/:officeId/records/:id	-> Ok. Removes the links in BOTH directions: a link pointing at a record that no longer exists would answer “any” for a query about it (added 2026-09-13, W10)
recordQuery	POST /api/office/:officeId/records/query	RecordQuery {typeKey, filters[], linked[], sort[], groupBy[], aggregate[], select[], limit, offset} -> RecordQueryResult {columns, rows, records, matchedRecords, returnedRows, truncated, rung: ‘L0’}. COUNCIL 006 Q3, 10/10: A QUERY IS L0. “Which customers have an unpaid invoice over 30 days” is linked: [{direction:'in', rel:'about', typeKey:'invoice', match:'any', filters:[...]}] and it never reaches a model — tests/office/records-l0.test.ts proves it by subscribing to onLlmCall and asserting the counter is still zero. filters/sort/aggregate are QueryFilter/QuerySort/QueryAggregate, THE SAME THREE sheets.query speaks (packages/contracts/src/query.ts): one vocabulary, not two. ONE link hop, deliberately — two is a join planner, which is the database §2.1 warns against. records carries the matching records themselves with their links, because the exit condition is that the answer links to the invoices (added 2026-09-13, W10)
recordImport	POST /api/office/:officeId/records/import	RecordImportRequest {name, key?, csv, titleField?, dryRun} -> RecordImportResult {type, typeCreated, columns, sampleRows, rowsRead, rowsImported, skipped[], rung: ‘L0’}. How a real business arrives (§5, W10.6). The column types are inferred by SCANNING the values — boolean, email, url, money, number, date, phone, a small fixed vocabulary as a select, else text — never by asking a model, so it is free and reproducible. dryRun: true returns the inferred type and five parsed rows and writes nothing; there is deliberately no second “propose from CSV” route, because the proposal IS what the import does first and two implementations of one inference would drift. An import into an EXISTING type keeps the declared type and reports the columns it left out (added 2026-09-13, W10)
recordViews	GET /api/office/:officeId/record-types/:key/views	-> RecordView[], oldest first (the order they were made in, which is the order the tabs are drawn in). 404 for a type this office does not keep (added 2026-09-27, 4-F)
recordViewCreate	POST /api/office/:officeId/record-types/:key/views	RecordViewDraft {name, kind, filters[], sort[], groupBy, dateField, endField, span, hidden[]} -> RecordView (201). Checked against the type by recordViewIssues: a board’s groupBy must be a select (its options ARE the columns, and a moved card writes that field), a calendar or timeline needs a date dateField, and every named field must be declared — refused (400), never repaired (added 2026-09-27, 4-F)
recordViewPatch	PATCH /api/office/:officeId/record-views/:id	v.patchOf(RecordViewDraft) -> RecordView. Merged onto the view as it stands and the WHOLE result re-checked against its type, so {name} alone renames and keeps the filters (added 2026-09-27, 4-F)
recordViewDelete	DELETE /api/office/:officeId/record-views/:id	-> Ok. Removes the way of looking and nothing it looked at. A type’s views also go when the type itself is deleted (added 2026-09-27, 4-F)

crews

Operation	Route	Notes
get	GET /api/projects/:projectId/crew	-> ProjectCrewDetail {projectId, crew: ProjectCrew|null, group: Group|null, seats: CrewSeat[], drawnFromGroupIds: Id[]}. drawnFromGroupIds is just the bound group unless the binding sets includeDescendants, in which case it is that group and every group beneath it — stated rather than inferred, so a board can say whose people are about to be given work. Null crew means automatic assembly, which is every project that has not been given one. 404 for a project that does not exist, 403 for one that is not the caller’s (added 2026-09-06, crews build)
set	PUT /api/projects/:projectId/crew	SetProjectCrewRequest {groupId: string|null, includeDescendants?: boolean} -> ProjectCrewDetail. Choosing replaces any earlier choice (one crew per episode); {“groupId”: null} clears it and restores automatic assembly. Caller must own the project AND be of the group (403 otherwise). Choosing starts nothing: the next run reads this row. includeDescendants (default false, and false for every binding made before 2026-09-06) lets assembly also draw on the seats of the groups INSIDE the bound one — opt-in per project because a company’s tree is a spend surface as much as a roster; setting it needs lead-or-owner of the bound group, not merely membership (added 2026-09-06)

account

Operation	Route	Notes
export	GET /api/account/export	-> {manifest: AccountExportManifest, data: Record<table, rows[]>} as an attachment novaterra-&lt;handle&gt;-&lt;date&gt;.json. UK GDPR Art. 15 and Art. 20. Every row of every table that names the caller, plus the children hanging off them (a project’s tasks and traces, a thread’s messages, a listing’s reviews), found by DISCOVERING the schema at runtime rather than from a list that would silently go stale. Scoped from the session; there is no beingId parameter, deliberately. Credentials are withheld and each withholding is named in the manifest: password hash, session tokens, encrypted connection envelopes, private signing keys (added 2026-09-10)
erase	DELETE /api/account	EraseAccountRequest {confirm, password} -> EraseAccountResponse {erasedAt, deleted[], kept[], notes[]}. UK GDPR Art. 17. confirm must be the caller’s own handle and the password is checked against the stored hash: a session cookie alone must not be able to destroy a world. 403 for the world OWNER with the reason — one node has exactly one owner (tests/db/single-owner-invariant.test.ts) and erasing them bricks the node rather than deleting an account. What survives is listed in kept with the lawful reason: accounting records under Companies Act 2006 s.388 and VAT Act 1994, and moderation records, per Art. 17(3)(b) and (e). Drops every session and clears the cookie (added 2026-09-10)

identity

Operation	Route	Notes
me	GET /api/identity/me	the caller’s own global address -> IdentityStatus {beingId, did, chain: RotationChain, createdAt, hasSecret} (added 2026-09-06, Wave C)
being	GET /api/identity/beings/:id	any being on this node, by local id or me -> IdentityStatus. An address is not a secret (added 2026-09-06)
passport	GET /api/identity/beings/:id/passport	-> SignedPassport {payload: PassportDocument, signature: Signature}. The SAME bytes for every caller, which is what makes it shareable: PassportDocument is a strict shape with no vow, no mind page and no consent page — the private fields do not exist in it rather than being nulled per viewer (added 2026-09-06)
chain	GET /api/identity/beings/:id/chain	-> ChainStanding {chain: RotationChain, preRotation: ChainPreRotation}. What a peer holding a stale address asks for; preRotation added 2026-09-19 so the one screen that shows a chain can also show whether it can be trusted (added 2026-09-06)
book	GET /api/identity/beings/:id/book	-> PassportBook {document: SignedPassport, visa: PassportVisa|null, stamps: PassportStamp[], issuer: {did, label}, chainLinks}. The passport as the physical object at /passport: the SAME signed bytes as the route above, plus the two things a document that travels cannot carry. Viewer-dependent and therefore UNSIGNED — a stamp is evidence this node holds a row, not something a stranger can check, and signing a per-viewer document would dress a database read as a cryptographic fact. visa is the spent access code that admitted the being and is included ONLY when :id resolves to the session’s own being (not the owner’s: an operator minted the code and reading somebody’s arrival out of their passport is not an operator’s job); its code is null and only a hint is shown for the node’s standing bootstrap owner code, which ensureOwnerAccessCode() re-inserts at every boot and modules/admin/access.ts already redacts. stamps are connections (a real grant date) and sealed federation crossings (delivered/received rows with sealed=1, dated at the FIRST crossing per peer per direction) — nothing decorative, and no stamp for a queued or plaintext message (added 2026-09-10)
sealingKey	GET /api/identity/beings/:id/sealing-key	-> SignedSealingKey {payload: SealingKeyDocument {v, type, did, alg: ‘x25519’, version, key, issuedAt, expiresAt}, signature}. Minted on first ask, exactly as the address is. Also carried inside PassportDocument.sealingKey (OPTIONAL, absent-never-null: a null default would change the canonical bytes of every passport already signed), so a peer normally learns it from the passport it already receives and never calls this route — it is here for catching up on a rotation without re-fetching a whole passport (added 2026-09-07)
sealingKeyRotate	POST /api/identity/beings/:id/sealing-key/rotate	-> SignedSealingKey at version+1; the previous one is retired but stays OPENABLE for 30 days so in-flight and Hall-queued mail is not silently eaten. Self always; anyone else needs the node owner — an ownership check scoped from the session, never a branch on kind. Does NOT change the being’s address: a sealing-key compromise is not a signing-key compromise, and making every peer relearn who somebody is would be an expensive answer to a question nobody asked. The reverse coupling IS automatic and needs no route — a SIGNING rotation produces a new did, which has no sealing key, so the next passport mints one (added 2026-09-07)
sealingKeysLearn	POST /api/identity/sealing-keys/learn	owner only. {document} -> SealingKeyLearnResult {did, outcome: accepted|already-known|superseded|refused, version, reason}. Kept only when signature.did === payload.did (a self-assertion, exactly like a passport — this is the impostor refusal) and the version is not below one already held (a signed document is replayable for ever, so monotonicity is the whole downgrade defence). Two different keys claimed at the SAME version is refused, not resolved: same class of fact as ChainLearnResult.forked (added 2026-09-07)
resolve	GET /api/identity/resolve/:id	:id is a did:key -> {did, beingId, handle, displayName, current}. 404 for an address this node has never seen. 400 for a string that is not a did:key (added 2026-09-06)
rotate	POST /api/identity/beings/:id/rotate	{reason?} -> {rotation: SignedRotation, chain: RotationChain, status: IdentityStatus}. Mints a successor, has BOTH keys sign the handover (the predecessor grants; the successor proves possession) and retires the old one. Self always; anyone else needs the node owner — an ownership check scoped from the session, never a branch on kind. 409 when this node no longer holds the private half (added 2026-09-06)
verify	POST /api/identity/verify	{document} -> VerificationResult {valid, did, reason}. Takes a SignedPassport, a SignedRotation or a whole RotationChain from ANYONE and says whether it holds up, using only what is in the document — no lookup, no network. This is the check a peer will run in Wave D, callable today (added 2026-09-06)
export	GET /api/identity/export	owner only -> IdentityExport {v, type, exportedAt, beings: [{localId, handle, chain, passport}]}. PUBLIC HALVES ONLY — no field of IdentityExport can hold a secret (added 2026-09-06)
node	GET /api/identity/node	-> NodeIdentityStatus {did, label, profile, createdAt, hasSecret, chain, serves}. The NODE’s own address, which is not any being’s: a being’s key proves a document, and nothing proved the machine serving it (added 2026-09-07)
nodeDescriptor	GET /api/identity/node/descriptor	-> SignedNodeDescriptor {payload: NodeDescriptor, signature}. Signed fresh per request, 15-minute expiresAt INSIDE the signed bytes. serves is a routing hint about where to ask, NEVER evidence about the beings in it — a node cannot say anything about a being, only the being’s own key can (added 2026-09-07)
nodeRotate	POST /api/identity/node/rotate	owner only. {reason?} -> {rotation, chain, status, note}. Same counter-signed chain a being uses. Honestly weaker: peers know a node BY its address, so they must relearn it out of band, and until they do a thief holding the old key can serve them a chain omitting this rotation. note says so (added 2026-09-07)
challenge	POST /api/identity/challenge	{audience?: Did|null} -> SignedChallenge. Mints a single-use nonce and signs a challenge around it. Freshness comes from the VERIFIER’s randomness, not from a clock: two nodes disagree about the time and that disagreement must not be load-bearing (added 2026-09-07)
attest	POST /api/identity/attest	{challenge, document} -> SignedAttestation over {nonce, audience, subject: {type, did, alg, digest}}. Signed by the SUBJECT being’s key when this node holds it (“this document of mine is current”), by the node’s key otherwise (“I served these bytes just now”) — a weaker claim the verdict keeps separate. Never signs the caller’s bytes verbatim (added 2026-09-07)
check	POST /api/identity/check	{document, attestation?} -> DocumentCheck {signature: VerificationResult, freshness: FreshnessVerdict, revocation: RevocationVerdict, trusted}. The three questions together. verify above is unchanged and still answers only the first (added 2026-09-07)
chainsLearn	POST /api/identity/chains/learn	owner only. {chain, observations?: SignedObservation[]} -> ChainLearnResult {origin, outcome: accepted|extended|already-known|refused|forked, current, links, withheld, observations, reason}. A chain verifies on its own, so it can be learned from anywhere; withheld: true means a witness has seen MORE links than the chain just offered, which is the only way to catch a node serving a shortened history (added 2026-09-07)
chainsKnown	GET /api/identity/chains/:id	:id is any did:key in the history -> KnownChain {origin, chain, source: local|learned|witnessed, learnedAt, observations}. 404 for an address this node knows nothing about (added 2026-09-07)
witness	POST /api/identity/witness	owner only. {chain, via?} -> SignedObservation. This node signs what it saw: origin, current, link count, digest, its own clock. Detection, never consensus — two witnesses disagreeing is a fact for a person, not a vote (added 2026-09-07)
revoke	POST /api/identity/beings/:id/revoke	{did?: Did|null, notValidAfter: ISODate, reason?} -> {revocation: SignedRevocation, rotated, chain, status}. “Stolen on Tuesday; distrust anything after Monday” — which rotation CANNOT say. Revoking the key still in use rotates first so the successor signs and the being is not left mute. Self always; anyone else needs the owner (added 2026-09-07)
revocationsLearn	POST /api/identity/revocations/learn	owner only. {revocation} -> {learned, reason}. Kept only when signed by the key itself or by a successor proved through a rotation chain — anyone else’s is a stranger asking you to distrust somebody. The EARLIEST cutoff wins (added 2026-09-07)
revocations	GET /api/identity/revocations	-> SignedRevocation[]. This node’s own and everything it has learned (added 2026-09-07)
petnames	GET /api/identity/petnames	-> Petname[] {did, current, name, note, source, introducedAs, firstSeenAt, updatedAt}. What THIS node calls the addresses it knows. Local, unsigned, never exported, and deliberately NOT global discovery — OS-PLAN §5.3 says that decision is not made, and a name service shipped here would make it by accident (added 2026-09-07)
petnameSet	POST /api/identity/petnames	owner only. {did, name, note?, source?, introducedAs?} -> Petname. One name means one address on this node: 409 with a free suggestion when the name is taken, never a silent ash2. The name follows the key through rotation, so a friend rotating does not become a stranger (added 2026-09-07)
petnameForget	DELETE /api/identity/petnames/:id	owner only. :id is a did:key -> {did, removed}. Forgets the name; the address is untouched (added 2026-09-07)

federation

Operation	Route	Notes
peers	GET /api/federation/peers	owner only -> Peer[] {nodeDid, endpoint, name, status: unverified|verified|unreachable|refused|blocked, label, profile, software, serves, addedAt, verifiedAt, lastSeenAt, collectedAt, relay, lastError}. label/profile/software are COPIES of what the peer last claimed about itself — advisory, never trust (added 2026-09-07). status:'unreachable' with verifiedAt:null is “that address has NEVER once answered”; with a date it is “answered before, asleep now” — the distinction that used to be invisible, and the reason no fifth PeerStatus value was added for it. collectedAt is the last time that peer COLLECTED from here (federation.ts §3c): a peer nothing can push to but which collects is exchanging messages perfectly well, and a collect deliberately leaves status alone because it proves the KEY is live and says nothing about the ADDRESS (added 2026-09-09)
addPeer	POST /api/federation/peers	owner only. AddPeerRequest {nodeDid, endpoint, name?, relay?} -> PeerSession {peer, verified, reason, check: DocumentCheck|null, skewSeconds, at}. Adds and immediately tries the handshake. A peer that is asleep is still added, marked unreachable — refusing would mean you can only befriend somebody while their laptop is open (added 2026-09-07)
greetPeer	POST /api/federation/peers/:id/greet	owner only. :id is the peer’s node did -> PeerSession. Try the handshake again after they woke up or the URL was fixed (added 2026-09-07)
updatePeer	PATCH /api/federation/peers/:id	owner only. UpdatePeerRequest {endpoint?, name?, blocked?, publish?, relay?} -> Peer. relay is where to leave mail for them when the endpoint does not answer (§3d): a THIRD value from a person out of band, beside the address and the endpoint, and null removes it (added 2026-09-09). publish starts or stops sending this node’s Square to that peer and is OFF BY DEFAULT — adding a peer means “we can message each other”, not “everything anybody here says in public goes to your machine”; the exact mirror of SquareAdmission defaulting to refuse on the way in. A blocked peer is sent nothing whatever publish says (added 2026-09-07). The address is the identity and the endpoint is only where to knock, so a new URL is a MOVE and keeps a block. Unblocking returns it to unverified, never straight to verified
forgetPeer	DELETE /api/federation/peers/:id	owner only -> {nodeDid, removed, threadsAffected}. The conversations STAY: what was said was said. threadsAffected names how many can no longer send (added 2026-09-07)
conversations	GET /api/federation/conversations	-> FederatedConversation[] {threadId, peerDid, peerName, remoteDid, remoteCurrent, remoteHandle, petname, localBeingId, queued, stuck, createdAt}. The local half is an ordinary Thread of kind dm; the remote being has NO beings row on this node and never will (OS-PLAN §1.1) (added 2026-09-07)
openConversation	POST /api/federation/conversations	OpenFederatedConversationRequest {peerDid, remoteDid, petname?} -> FederatedConversation. Both addresses from the owner; nothing is resolved or fetched. Scoped from the session — the body carries no local being id. 400 if remoteDid belongs to a being on this node (added 2026-09-07)
thread	GET /api/federation/threads/:id	:id is the local thread id -> {conversation: FederatedConversation, messages: MessageProvenance[], wire: FederatedMessage[]}. Where each message got to, keyed by the local messages row — served BESIDE the transcript because Message has no federation field and is not getting one (added 2026-09-07)
outbox	GET /api/federation/outbox?kind=post|retraction|message	owner only -> FederatedMessage[] {id, direction, kind, threadId, messageId, peerDid, authorDid, audienceDid, digest, sealed, state, attempts, nextAttemptAt, lastError, verified, createdAt, updatedAt}. One row per (document, peer): a Square post going to three peers is three rows sharing a digest, which is what makes “it reached two of your three” visible rather than inferred. kind defaults to post — the DM queue is read per conversation because a DM belongs to one, and a post belongs to none (added 2026-09-07)
flush	POST /api/federation/flush	owner only -> CourierRun {attempted, delivered, unreachable, refused, at} & {requeued, collected, relayed}. The “they are back, go on then” button: requeues items that ran out of attempts, drains the outbox, THEN collects from every verified peer. collected rides beside requeued rather than inside CourierRun — a run of the outbox is what that schema describes, and a run of the inbox is a different fact (collect added 2026-09-09). It then asks this node’s RELAY, if it has one, and reports that separately as relayed — mail taken from a peer and mail taken from a relay reached this node by different routes with different freshness guarantees, and one number covering both would hide that (§3d, added 2026-09-09). The courier, the collector and the relay loop each also run on their own every 30s (added 2026-09-07)
fetchBlob	POST /api/federation/blobs/:root/fetch	:root is a BlobRoot (43 base64url chars) -> FederatedBlob {root, direction, threadId, messageId, name, mime, size, have, state: held|queued|fetching|waiting|done|failed, reason, fileId, route, updatedAt}. Council 039 W1-R2, ACCEPTING IS CONSENTED: a blob from somebody this being has never written to arrives HELD — name and size on screen, nothing fetched — and this is the person saying “Fetch”. Scoped from the session: a root that is not an inbound blob of THIS being’s is a 404, never somebody else’s file. Starts a fetch pass and returns at once; progress is GET /api/federation/threads/:id’s blobs (added 2026-09-26)
peerBlob	POST /api/federation/peer/blob	PUBLIC. BlobRequest {v, type:‘novaterra.blob.request’, protocol, descriptor: SignedNodeDescriptor, attestation: SignedAttestation, root, from, count: 0..32, manifest} -> BlobResponse {v, node, root, accepted, code: BlobRefusalCode|null, reason, total, manifest, chunks: {index, data}[]}. Council 039 W1-B, THE DIRECT PATH FOR A FILE: sealed chunks of a content-addressed blob (§3e), ciphertext only — the key rides inside the author’s sealed message and never here. The asker proves itself exactly as peer/collect does (its descriptor + an attestation over a nonce from peer/hello), and the blob is looked up against THAT proven address and nothing in the body: a blob not addressed to the asker and a blob that does not exist get the identical not-available, so nobody can probe what this node holds for others (added 2026-09-26)
peerHello	POST /api/federation/peer/hello	PUBLIC. PeerHello {v, protocol, descriptor: SignedNodeDescriptor, challenge: SignedChallenge} -> PeerGreeting {v, protocol, descriptor, attestation, challenge, accepted, reason}. One round trip gives freshness BOTH ways: each side hands over a nonce with its descriptor, so neither has to trust a clock. accepted:false for a node this owner has not added — first contact is out of band and this node takes nothing from a stranger (added 2026-09-07)
peerDeliver	POST /api/federation/peer/deliver	PUBLIC. {envelope: SealedEnvelope {v, type:‘novaterra.envelope.sealed’, protocol:2, descriptor, audience, seal:{v, alg, epk, ct}} | MessageEnvelope (protocol 1, plaintext)} -> DeliveryReceipt {accepted, digest, code: RefusalCode|null, reason, at, check}. FROM PROTOCOL 2 THE BODY IS ENCRYPTED: passport, message and attestation are sealed to the recipient’s own did:key with X25519 (derived from their Ed25519 address) + HKDF-SHA256 + AES-256-GCM, so a relay or a Hall that terminates TLS sees ciphertext. It is SIGN-THEN-ENCRYPT and the signature is what authenticates — opening a seal proves NOTHING about the sender, because anyone can encrypt to a public key. descriptor and audience stay in the CLEAR, so who is talking to whom, when and roughly how much are all still visible to a relay; there is no padding and no forward secrecy (a stolen recipient key opens every message ever sent to it). Protocol 1 plaintext is still ACCEPTED inbound and marked sealed:false on the provenance; it is never SENT — a peer too old to open a seal gets a stuck message and a sentence, never a silent downgrade (added 2026-09-07). ALWAYS HTTP 200, refusal included: a sender that cannot tell “your message is wrong” from “your request never arrived” retries the first for ever. Refuses cheapest-first — shape, protocol, which machine, whether we know it — and only then verifies four signatures. checkDocument() decides signature/freshness/revocation; this route adds the two equalities that matter (the passport must belong to the message’s signer; the attestation must be about this message’s digest) (added 2026-09-07)
peerCollect	POST /api/federation/peer/collect	PUBLIC. PeerCollect {v, protocol, descriptor: SignedNodeDescriptor, attestation: SignedAttestation, challenges: SignedChallenge[1..8], ack: digest[0..32]} -> PeerCollection {v, protocol, node, envelopes: SealedEnvelope[], remaining, acked, accepted, reason}. THE DIRECTION A NODE BEHIND NAT CAN USE, and the Seed protocol’s answer (seed/beat calls in, authenticated purely by a signature) applied to peers: a machine with no inbound address cannot be pushed to, so it calls in, proves itself with its own signed descriptor plus an attestation over a nonce this node issued, and takes what is queued for it. THE QUEUE IS KEYED ON THE ADDRESS THAT JUST PROVED ITSELF AND ON NOTHING ELSE — there is no id in the body naming a queue, because this route hands out other people’s messages if that is ever got wrong. One challenge per envelope, minted audience: null for PeerGreeting.challenge’s reason (what comes back is signed by the BEING who wrote it, not by the node). AT-LEAST-ONCE: the responder marks a handed-over row sending, not delivered — a lost response must not lose somebody’s message — and the collector names the digests it took, or already had, in ack on its next collect. envelopes is typed SealedEnvelope[], so there is no shape in which a message leaves in the clear; a collector below protocol 2 gets an empty collection and a sentence. Refuses cheapest-first in peer/deliver’s exact order and rate-limit class — shape, protocol, which machine, whether we know it — and only then spends the nonce or builds a seal. A stranger is told exactly what peer/hello already tells it and NOTHING about a queue: it cannot learn whether an address is known here or whether anything is waiting. NOT A RELAY: only documents this node queued itself, for the one address that proved itself, and the collector refuses an envelope in the response signed by any other machine. DMs only — Square posts are unsealed and admitted by the moderation module, so a peer reachable only by collect gets its DMs and no posts (and publishPeerRows never queues posts at it, because a collect deliberately does not change a peer’s status). DOES NOT SOLVE two nodes both behind NAT: neither can dial the other. That case is the relay’s (§3d, /api/federation/relay below), and it is a DIFFERENT wire on purpose — this route hands over only documents this node queued itself, and never became a place that holds mail for somebody else (added 2026-09-09)
relay	GET /api/federation/relay	owner only -> NodeRelayState {endpoint, relayDid, expectedRelayDid, pinSource, enrolled, enrolledAt, expiresAt, limits: RelayLimits|null, deposited, collected, lastError}. WHERE THIS NODE KEEPS ITS MAIL when nobody can dial it. endpoint comes from NOVA_RELAY_ENDPOINT and there is deliberately NO route that sets it: a relay is infrastructure a person chose, and a form that can point a node’s mail at a new machine is a form worth attacking. relayDid is PINNED on the first successful enrolment and a different address at the same URL is refused afterwards — an endpoint is where to knock, an address is who answers. Null relayDid with a set endpoint means enrolment has not worked yet and lastError says why (added 2026-09-09). expectedRelayDid/pinSource are the address known BEFORE the first packet — this build ships the relay as a PAIR (URL + did:key, apps/api/src/modules/federation/relay-well-known.ts), so on an INSTALLED node an unset NOVA_RELAY_ENDPOINT now means the shipped relay rather than none, and NOVA_RELAY_ENDPOINT=none is how an owner opts out. A checkout still gets none unless NOVA_RELAY_AUTO=on: a mailbox is a 30-day footprint at a live service, not a lookup. first-contact is trust-on-first-use and is deliberately reported as weaker (added 2026-09-20, W1). NOW ALSO reachability and admission (added 2026-09-20, RELAY-1, Council 029 R13 + 030 R12). reachability is reachable|unconfigured|refused|unenrolled|unreachable and IS THE FIELD A SCREEN SHOULD READ: it is computed from RelayEnrolment.code, which the relay now returns beside its sentence, and NEVER from lastError. Before it there were only three derivable states and RelayPanel used them — !endpoint ? 'none' : enrolled ? 'enrolled' : 'trying' — so a node the relay had REFUSED rendered identically to one whose relay was having a bad afternoon, indefinitely, in a muted pill. On 2026-09-20 that was EVERY SELF-HOSTED NODE IN EXISTENCE: the live relay ran enrolment: code, no installer ships a code, and the only party that hands one over is services/provisioner — which a self-hosted node never passes through. admission is {held, issuer, basis, expiresAt, askedAt, lastError}: whether this node holds a signed RelayAdmission, who vouched, and when it lapses. The DOCUMENT is deliberately not returned — a screen has no use for it and a route that hands one out is one somebody will later be tempted to unguard. askedAt null means this node has never asked (NOVA_RELAY_ADMISSION=off); askedAt set with held: false means asking did not work and admission.lastError says why
relayEnrol	POST /api/federation/relay/enrol	owner only -> RelayEnrolment {v, relay, mailbox, limits, expiresAt, held, accepted, reason}. “I have just set this up, does it work”. Adds no capability — the relay loop calls the same function every pass — it only removes a wait. mailbox is always this node’s own address: the relay opens a mailbox for the key that proved itself and has no route that could open one for anybody else (added 2026-09-09)
relayWithdraw	POST /api/federation/relay/withdraw	owner only -> RelayEnrolment {accepted, reason, …}. Closes this node’s mailbox and DESTROYS what is still in it, unread — reason says how many. The counterpart enrolling never had: before this, a node that had enrolled anywhere had left an address on somebody else’s machine it could not take back, and the only way it went away was RELAY_MAILBOX_DAYS of silence. Proves the key exactly as enrolling did, against the PINNED address, and clears the pin on success; NOVA_RELAY_ENDPOINT is untouched, so the next pass enrols again — leaving a relay for good is still removing the variable (added 2026-09-10)
capabilities	GET /api/federation/capabilities	PUBLIC -> SignedCapabilityProfile {payload: {v, type, did, profile, runs: NodeFacility[], delegatesTo, fronts: Did[], seedProtocol, limits:{maxDocumentBytes, maxQueued}, issuedAt, expiresAt}, signature}. OS-PLAN §2’s table as something a node advertises, signed by the node key. A SELF-ASSERTION and routing only, never trust: a Seed claiming inference is lying and nothing can tell. Served BESIDE the node descriptor rather than inside it because SignedNodeDescriptor is .strict() and already on a live wire — a new field there costs a protocol bump, and a peer too old to know this route exists still has descriptor.payload.profile. greetPeer fetches it after a verified handshake and records it on the peer row (added 2026-09-07)
seeds	GET /api/federation/seeds	owner only -> SeedPairing[] {did, beingId, name, profile, grants: (‘signals’|‘storage’)[], status: paired|blocked, seq, beats, acts, refused, pairedAt, lastSeenAt, lastNote, lastError}. seq is this node’s high-water mark and the only column a device’s own traffic moves (added 2026-09-07)
pairSeed	POST /api/federation/seeds	owner only. PairSeedRequest {did, name, handle?, grants?} -> SeedPairing. Writes a beings row, a being_keys row with secret NULL, and the pairing, in ONE transaction. The address comes from a person out of band — there is no discovery, no mDNS and no “devices found on your network” (OS-PLAN §5.3). Grants default to NOTHING: a Seed with none still has presence and can ask for nothing (added 2026-09-07)
updateSeed	PATCH /api/federation/seeds/:id	owner only. :id is the Seed’s did. UpdateSeedRequest {name?, grants?, blocked?} -> SeedPairing (added 2026-09-07)
unpairSeed	DELETE /api/federation/seeds/:id	owner only -> {did, removed, beingId}. The BEING STAYS: what it said was said, and its Signals are on the owner’s desktop. Unpairing is also the documented recovery for a device whose flash was erased and whose counter went backwards — an owner action on purpose, because a Seed that could reset its own high-water mark would have no offline replay protection (added 2026-09-07)
seedKnock	POST /api/federation/seed/knock	PUBLIC. {v:1, protocol, did} -> SeedGreeting {v, protocol, node, nonce, seq, grants, accepted, reason}. The ONE unsigned document in the Seed protocol, and it has to be: aud lives inside the signed bytes of everything else, so a device cannot sign until it has been told the address to name. For an unpaired address: accepted:false, no usable nonce, no grants, seq:0 (added 2026-09-07)
seedBeat	POST /api/federation/seed/beat	PUBLIC. SignedSeedBeat {payload:{v, type:‘novaterra.seed.beat’, did, aud, seq, nonce, note}, signature} -> SeedReceipt {accepted, code: SeedRefusalCode|null, reason, basis: ‘nonce’|‘sequence’|‘none’, seq, nonce, at}. ALWAYS HTTP 200. Presence: the most it can cause is a counter moving and a note recorded. The receipt carries the nonce for the NEXT document, so a Seed’s steady state is one round trip per beat — which matters because a round trip is a radio wake (added 2026-09-07)
seedAct	POST /api/federation/seed/act	PUBLIC. SignedSeedDelegation {payload:{…, capability: CapabilityKind, method, args: string[≤3]}, signature} -> SeedReceipt. THE BROKER OVER THE WIRE (OS-PLAN §1.4): the same isModuleBridgeMethod allowlist a module in an iframe goes through, with the caller identified by a signature instead of a session cookie. SEED_DELEGABLE_CAPABILITIES (signals, storage) is a STRICT SUBSET of MODULE_BRIDGE_CAPABILITIES — a Seed cannot do more by being remote than a local plugin can, pinned by tests/seed/delegation.test.ts. network is withheld: a module names its hosts in a manifest a person read, a Seed has no manifest, so granting it would mean a general-purpose proxy out of the owner’s home. A Seed’s Signal lands on the OWNER’s desktop and it cannot say whose — there is no field in which it could (added 2026-09-07)
marketListings	GET /api/federation/market/listings	PUBLIC -> Listing[] (the Hall’s active listings; the federated read a node’s /market view is built from). No session: a listing is public and a node reading them is not a principal
marketHello	POST /api/federation/market/hello	PUBLIC. MarketHelloRequest {descriptor: SignedNodeDescriptor} -> MarketHello {v, protocol, challenge: SignedChallenge|null, accepted, reason}. Verifies which machine is asking and that it is bound to a Hall member, then hands back a nonce to answer — the same handshake shape as peer/hello. accepted:false with a null challenge for a node no member has registered
marketBuy	POST /api/federation/market/buy	PUBLIC. MarketBuyRequest {descriptor, purchase: SignedMarketPurchase, attestation: SignedAttestation} -> MarketBuyResult {accepted, code, reason, order, delivery: SignedMarketDelivery|null}. ALWAYS HTTP 200 (the federation posture: a refusal is an answer). The buy runs on the HALL’s ledger as the bound member; a replayed call is refused by the spent nonce (checkFreshness marks it answered). Delivery is a MarketDeliveryPackage (generator steps+inputsSchema, a skill name, or a theme doc) inside a document the Hall signs with its node key
marketRedeliver	POST /api/federation/market/redeliver	PUBLIC. MarketBuyRequest {descriptor, redeliver: SignedMarketRedeliver, attestation} -> MarketBuyResult. Re-hands the SAME package for an order the Hall has already charged for — the buyer paid, an import that failed must be recoverable, and this charges nothing again

mail

Operation	Route	Notes
address	GET /api/mail/address	-> MailAddressState {address, domain, inbound, outbound, note}. “Your address: aria@novaterra.world”, or null and a sentence when NOVA_MAIL_DOMAIN is unset (every self-hosted node until an owner does the DNS). inbound is whether this node has a relay to be reached through; outbound whether it holds a sending key. Neither is a promise that the DNS is right — the note says so
threads	GET /api/mail/threads	-> OutsideThreadSummary[] {threadId, outside: {address, name}, verdict, lastAt}. Which of this being’s conversations are with a person FROM OUTSIDE, so Messages can label them — never mistaken for a citizen. The conversations themselves are ordinary dm threads with replyPolicy none, listed by GET /api/threads
thread	GET /api/mail/threads/:id	-> OutsideThread {threadId, outside, from, mail: OutsideMail[], canReply, replyNote}. Each OutsideMail carries the sender’s address, the relay’s DKIM/DMARC verdict (“could not verify the sender”), subject, attachment states and hasHtml — never the HTML itself
html	GET /api/mail/messages/:id/html	-> text/html. The stranger’s HTML, sanitised (scripts, handlers, forms, remote loads removed) AND served with Content-Security-Policy: sandbox; default-src 'none'; img-src data:; style-src 'unsafe-inline', for an <iframe sandbox> with no allow-scripts and no allow-same-origin (security invariant 3). The CSP sandbox holds even if the URL is opened in a tab of its own
reply	POST /api/mail/threads/:id/reply	MailReplyRequest {body, useTemplate?} -> MailReplyResult {sent, outcome, reason, mail}. 3-B: on a BRIDGED thread it runs &lt;channel&gt;.reply instead (whatsapp/telegram/sms, each world-acting, same press, same gate), and a WhatsApp reply outside the 24-hour window is refused with outcome outside_window unless the person chose the owner’s template. WORLD-ACTING: the person pressing “Reply by email” is the consent, and it runs the mail.reply skill with approved:true through the registry’s gate, so the tape records it. Sent FROM &lt;the session being's handle&gt;@&lt;NOVA_MAIL_DOMAIN&gt; — never an address from input — with In-Reply-To/References to the last message, through core/email.ts (Resend; DKIM is the provider’s). A model reaching the same skill is asked, not obeyed
draft	POST /api/mail/threads/:id/draft	-> MailDraft {draft, fenced: true}. The Muse writes a reply for the person to read, edit and send themselves. SPENDS a model call. The outside message reaches the model only inside fenceUntrusted (security invariant 6); nothing here sends

bridges

Operation	Route	Notes
status	GET /api/bridges	-> BridgeStatus[] {channel, state, note, inboundPath, steps}. For Settings: each bridge “connected” / “partial” / “not set up”, and the owner’s steps by name. The session being’s own connections only
whatsappVerify	GET /api/bridges/whatsapp/webhook	PUBLIC. Meta’s subscription handshake: ?hub.mode=subscribe&hub.verify_token=…&hub.challenge=… -> the challenge as text/plain when the token matches a WhatsApp connection’s verifyToken (timing-safe), else 403
whatsappInbound	POST /api/bridges/whatsapp/webhook	PUBLIC. The WhatsApp Cloud API’s message webhook. X-Hub-Signature-256 = HMAC-SHA256(app secret, RAW body), checked against every WhatsApp connection’s appSecret before a byte is believed; unsigned or wrongly signed -> 401 and nothing kept. A match must also name that connection’s phone_number_id. Each text -> an outside thread per sender number + one message:whatsapp arrival; media is kept as a line saying it was not carried. Always 200 once verified, so Meta does not retry
smsInbound	POST /api/bridges/sms/webhook	PUBLIC. An SMS provider’s inbound webhook (Twilio today, behind SmsProvider). X-Twilio-Signature = base64 HMAC-SHA1(auth token, URL + sorted params), checked against every SMS connection; bad or missing -> 401. A match must also be addressed To that connection’s number. -> an outside thread per sender number + one message:sms arrival; replies with an empty TwiML <Response/>

push

Operation	Route	Notes
state	GET /api/push	-> PushState {vapidPublicKey, devices: PushDevice[], quietAllow}. The node’s VAPID public key is minted on first read (P-256; the private half encrypted at rest in push_vapid like every other node secret). The session being’s own devices only
subscribe	POST /api/push/subscriptions	PushSubscribeRequest {endpoint, keys{p256dh, auth}, label, includeBody, locale, templates?} -> PushDevice. Files the device under the SESSION’s being; re-subscribing the same endpoint updates it (and moves it, if the browser was last signed in as somebody else — whoever holds the keys holds the device). The endpoint must be https on a known push service (fcm.googleapis.com, *.push.services.mozilla.com, *.notify.windows.com, *.push.apple.com, plus NOVA_PUSH_EXTRA_HOSTS) — the node POSTs to it, so an arbitrary URL would be a request forgery. templates are the device’s own twelve-language lines for each class; includeBody defaults to false
update	PATCH /api/push/subscriptions/:id	PushDevicePatch {label?, includeBody?} -> PushDevice. 404 for a device that is not the session being’s
remove	DELETE /api/push/subscriptions/:id	-> Ok. 404 for a device that is not the session being’s
quiet	PATCH /api/push/quiet	PushQuietAllow {classes?, people?} -> PushQuietAllow. What may reach this being’s devices DURING quiet hours: message / alert / call (never nudge — the Hush holds those) and named people. Outside quiet hours it changes nothing
test	POST /api/push/test	PushTestRequest {deviceId?} -> PushTestResult {sent, failed, removed}. Sends the device’s own “Notifications work on this device” line, no body, to every device of the session being (or the one named). 3 a minute. A device the push service answers 404/410 for is removed

directory

Operation	Route	Notes
status	GET /api/directory/status	owner only -> DirectoryStatus {configured, endpoint, directoryDid, expectedDirectoryDid, pinSource, nodeDid, registered, advertisedEndpoint, publishableEndpoint, handles, registeredAt, expiresAt, lastError, creditsClaimed}. directoryDid is PINNED on first successful registration: a directory that changes its address afterwards is a different directory and is refused, not followed (added 2026-09-07). expectedDirectoryDid/pinSource are the address known BEFORE the first packet — this build ships the directory as a PAIR (URL + did:key, apps/api/src/modules/directory/well-known.ts), so DIRECTORY_ENDPOINT unset now means the shipped directory rather than none, and DIRECTORY_ENDPOINT=none is how an owner opts out. first-contact is trust-on-first-use and is deliberately reported as weaker. publishableEndpoint is ” on a node with no address others can reach — an ordinary state, not an error (added 2026-09-18, P3-d)
register	POST /api/directory/register	owner only. DirectoryPublishRequest {endpoint, handles?} -> DirectoryRegistrationReceipt {accepted, did, reason, expiresAt, contestedHandles}. Answers the directory’s nonce with an attestation signed by THIS NODE’S key, so the service cannot write a record for a key nobody proved. contestedHandles reports other nodes already claiming a name — a fact, not a refusal (added 2026-09-07)
withdraw	DELETE /api/directory/register	owner only -> {removed: boolean, reason}. Take this node’s address out of the directory. Proves the key the same way registering did: nobody but the holder can withdraw a record, and the directory cannot withdraw one on anyone’s behalf (added 2026-09-07)
lookup	GET /api/directory/lookup?q=	owner only. q is a did:key:… or a claimed handle -> DirectoryLookup {query, kind, answeredBy, answerVerified, contested, hits: DirectoryHit[], note}. EVERY HIT CARRIES THIS NODE’S OWN VERDICT: trusted is false for a record whose registration is not a self-assertion by the address asked about, whose named directory is not the one asked, or whose descriptor belongs to somebody else. An untrusted hit is RETURNED with its reason rather than dropped — a tampered answer must not look like an absent one. Nothing here adds a peer; connecting is still POST /api/federation/peers with an address a person chose (added 2026-09-07)
claimCredits	POST /api/directory/credits/claim	owner only -> DirectoryClaimResult {posted, credits, alreadyHeld, refused, remaining, balance}. THE NODE ASKS; THE DIRECTORY NEVER PUSHES (OS-PLAN §5.2). Credit bought while this node was asleep sits queued until this call. Each grant is posted to the append-only ledger with idemKey dir_grant:<id>, so the protocol is at-least-once and the effect is exactly-once — alreadyHeld counts the difference and is not an error (added 2026-09-07)

moderation

Operation	Route	Notes
blocks	GET /api/moderation/blocks	-> Block[] {id, beingId, subjectKind: being|address, subjectId, subjectLabel, reason, createdAt}. The CALLER’S OWN list; there is no way to read anyone else’s (added 2026-09-07)
block	POST /api/moderation/blocks	CreateBlockRequest {beingId?|did?, reason?} -> Block. Exactly one of beingId/did. SYMMETRIC in reach: their posts, dms and presence stop reaching you and yours stop reaching them. Survives rotation — a local being is blocked by local id (being_keys joins every address they ever held to it) and an address is resolved across its whole rotation chain. A did belonging to a being on this node is normalised to that being’s id, so one person is one row however they were named. No kind branch: an AI citizen is blocked exactly as a human is (added 2026-09-07)
unblock	DELETE /api/moderation/blocks/:id	-> Ok. Scoped to the caller’s own rows; somebody else’s block id is a 404, not a 403 (added 2026-09-07)
report	POST /api/moderation/reports	CreateReportRequest {subjectKind: post|being|address, subjectId, category: illegal|abuse|spam|impersonation|other, note?} -> ReportReceipt {report, reach: owner|local-only, message}. A RECORD, not an action. 409 if you already have an open report on the same subject. The snapshot of what was said is stored WITH the report, because a report about content that has since been edited or deleted is unanswerable (added 2026-09-07)
reports	GET /api/moderation/reports?state=open|upheld|dismissed	owner only -> ReportItem[] {report, content (the post as it stands NOW, null if gone), hidden, blockedByReporter} (added 2026-09-07)
reportDecide	POST /api/moderation/reports/:id/decide	owner only. ReportDecisionRequest {decision: uphold|dismiss, note?, hide?, block?} -> ReportItem. Upholding is a FINDING; hide and block are what to do about it and are separate because a post can be wrong without its author needing cutting off. hide keeps the row as evidence and takes it out of every Square read (added 2026-09-07)
queue	GET /api/moderation/queue	owner only -> ModerationSummary {openReports, heldPosts, hiddenPosts, blocks, policy} (added 2026-09-07)
held	GET /api/moderation/held?state=held|admitted|refused|withdrawn	owner only -> HeldPost[] {id, digest, authorDid, authorCurrent, authorHandle, petname, peerDid, peerName, body, issuedAt, state, reason, check, heldAt, decidedBy, decidedAt, messageId, createdAt}. A held post is NOT in messages — the marketplace’s in_review trick, bought more cheaply: the Square reads messages, so there is no filter to forget (added 2026-09-07)
withdrawPost	DELETE /api/moderation/posts/:id	:id is the square message id. The author, or the node owner -> PostWithdrawal {messageId, hidden, askedPeers, message}. Takes the post out of every Square read here (hidden, evidence row kept, exactly as an upheld report’s hide) and QUEUES a signed retraction for every peer that took delivery of it; copies still in the outbox are dropped rather than chased. askedPeers counts REQUESTS QUEUED and is named asked on purpose — a remote node is not obliged to comply, may already have shown it to everyone, and this node cannot tell whether it did. 400 for a post that arrived from another node: this node did not publish it and holds no key that could sign a withdrawal for it (added 2026-09-07)
heldDecide	POST /api/moderation/held/:id/decide	owner only. HeldPostDecisionRequest {decision: admit|refuse, note?, block?} -> HeldPost. Admitting writes it into the Square as an ordinary message whose authorId is the author’s GLOBAL ADDRESS — same choice federation made, for the same reason: there is no beings row for a remote author and null would render their words as the reader’s own (added 2026-09-07)
policy	GET|PUT /api/moderation/policy	owner only -> SquarePolicy {admission: refuse|review|petnamed|verified, perPeerHourlyLimit, updatedAt}. PUT body SquarePolicyRequest {admission?, perPeerHourlyLimit?}. DEFAULT IS refuse: shipping this code must not make a node start accepting posts from other machines. Everything above refuse sends what it will not admit to the owner’s queue rather than dropping it — a silently discarded post is indistinguishable from a network failure and the sender retries it for ever (added 2026-09-07)

square

Operation	Route	Notes
retract	POST /api/square/retract	PUBLIC. {envelope: SquareRetractionEnvelope {descriptor, retraction: SignedSquareRetraction {payload:{v, type:‘novaterra.retraction’, did, postDigest, issuedAt}, signature}, attestation, chain?}} -> SquareRetractionReceipt {accepted, digest, postDigest, outcome: withdrawn|already-gone|unknown-post|refused, code, reason, at}. ALWAYS HTTP 200. Authorisation is a SIGNATURE and nothing else: the withdrawal must be signed by an address the post’s author has held, resolved across the rotation chain, so no node can retract its beings’ posts and no being can retract another’s. This node grants it (hidden, evidence row kept, square_held.state -> withdrawn) and that is THIS node’s policy, not an obligation — a receiving node is free to ignore a retraction and the sender cannot tell whether it did. No passport: the receiver already holds the post filed under an author address, so the only question is whether the signer is that address (added 2026-09-07)
deliver	POST /api/square/deliver	PUBLIC. {envelope: SquarePostEnvelope {descriptor, passport, post, attestation, chain?}} -> SquarePostReceipt {accepted, held, digest, code: PostRefusalCode|null, reason, at, check}. ALWAYS HTTP 200. A SquarePostDocument is a second document type, not a widened MessageDocument: a post has no audience, and making the message wire’s recipient check conditional would be the cheapest way to eventually skip it. held: true is the third answer — the bytes verified and nobody has looked yet — so a sender does not retry something sitting in a queue. Refuses cheapest-first (shape, protocol, which machine, whether we know it, the per-peer hourly bound) before verifying four signatures. The optional chain is the author’s rotation history: an honest sender includes it and it is what makes a block outlive a rotation; one who omits it arrives as an address with no history, which no policy above verified admits (added 2026-09-07)

bench

Operation	Route	Notes
matters	GET /api/bench/matters	-> BenchMatterSummary[] {matter, parties[2], about, openedAt, lastAt, settled, lastAct, lastBy}, newest activity first. THE CALLER’S OWN matters, scoped from the session being; there is no way to read anyone else’s and no query parameter that takes a did (added 2026-09-20)
openMatter	POST /api/bench/matters	OpenMatterRequest {counterparty, act, reason?, about?} -> BenchStatementFiled {matter, statement, delivery, reason}. Signs a BenchStatement as the SESSION’S being — there is no field naming the speaker, for RelayAdmitRequest’s reason. The matter id is minted here, never supplied. delivery is answered in the same response and unreachable is an honest answer, not a failure: the statement is written down and signed, and BENCH_UNREACHABLE_NOTE says in words that the other party has not seen it (added 2026-09-20)
matter	GET /api/bench/matters/:matter	-> BenchMatter {matter, parties[2], about, openedAt, lastAt, settled, statements: BenchStatementView[]}. Both sides, in issue order, each in its author’s own signature and own words. 404 for a matter the caller is not a party to — not 403, because whether a matter exists is not a stranger’s business (added 2026-09-20)
answerMatter	POST /api/bench/matters/:matter/statements	AnswerMatterRequest {act, reason?, inReplyTo?} -> BenchStatementFiled. THE SAME DOCUMENT AS OPENING ONE: a reply that is a different kind of object is a reply that can be given a different weight. Neither the matter nor the counterparty comes from the body — the matter is the path, the counterparty is the matter’s other party, and a caller who is not one of the two is refused (added 2026-09-20)

benchWire

Operation	Route	Notes
deliver	POST /api/bench/deliver	PUBLIC. BenchDeliverRequest {envelope: BenchStatementEnvelope {v, type, protocol, descriptor, passport, statement: SignedBenchStatement, attestation}} -> BenchStatementReceipt {v, accepted, digest, code: BenchRefusalCode|null, reason, at, check}. ALWAYS HTTP 200, for SquarePostReceipt’s reason. ⭐ REFUSES not-addressed WHEN THE STATEMENT’S COUNTERPARTY IS NOBODY ON THIS NODE — the check that makes a reputation corpus unbuildable rather than merely unbuilt. There is no held: a Bench statement is one half of a conversation the recipient is already in, and a person must not be able to be accused of silence in a matter sitting in a queue they never opened (added 2026-09-20)

desktop

Operation	Route	Notes
widgets	GET|PUT /api/desktop/widgets	PUT replaces layout: Widget[]
themes	GET|POST /api/desktop/themes	-> Theme[]
themeActivate	POST /api/desktop/themes/:id/activate
themeDelete	DELETE /api/desktop/themes/:id	removes a non-active theme -> Ok (added 2026-09-05, catalogued 2026-09-06)
stylePacks	GET|POST /api/desktop/style-packs	-> StylePack[]. POST StylePackInput -> StylePack; isDefault:true clears every other pack’s flag (added 2026-09-13)
stylePack	GET|PATCH|DELETE /api/desktop/style-packs/:id	GET/PATCH -> StylePack; PATCH body is v.patchOf(StylePackInput), never .partial(). DELETE -> Ok, and promotes the next-oldest remaining pack to default if the deleted one was it (added 2026-09-13)
stylePackDefault	POST /api/desktop/style-packs/:id/default	makes this the one a run uses when the person does not choose; clears the flag on every other pack for the being first, inside one transaction -> StylePack (added 2026-09-13)
signals	GET /api/desktop/signals?status=	-> Signal[]
signalRaise	POST /api/desktop/signals	Signal minus {id,beingId,createdAt} -> Signal — server-internal (signal.raise skill), no client call (added 2026-09-05, catalogued 2026-09-06)
signalAnswer	POST /api/desktop/signals/:id/answer	{optionId|answer} -> Signal
signalDismiss	POST /api/desktop/signals/:id/dismiss
signalFewerLikeThis	POST /api/desktop/signals/:id/fewer-like-this	dismisses the signal (if still open) AND writes a real preference Memory tagged with the nudge’s topic (apps/api/src/twin/hush.ts’s recordFewerLikeThis), so evaluateNudge() suppresses that exact topic — and, after repeated feedback, that whole kind of nudge — from here on. This is what makes “fewer like this” change future behaviour, not just clear one card -> Ok (catalogued 2026-09-06 — calendar/to-do/Hush build) UPDATED 2026-09-07: the topic key now comes from the hub’s action.hush.key stamp rather than being re-derived from the title at press time (a reworded title would otherwise file the feedback under a topic the gate never checks - a control that looks like it worked and does nothing), and the signal’s source is tagged too, so pressing this twice on Gmail cards turns Gmail down instead of suppressing unrelated topics one at a time. Enforcement moved with it: gateAtHub() in raiseSignal applies this to EVERY proactive caller, not only the two that called evaluateNudge
now	GET /api/desktop/now	-> NowResponse. The desk’s OLD read model: a greeting with the person’s name, a headline built by concatenation, and a clock-derived mood. Still served, still read by the Attention band and the Signals widget; superseded on the desk itself by living below, and the greeting/mood fields are what W16 retired from the surface (added 2026-09-05)
living	GET /api/desktop/living	-> LivingState. THE DESK, AS A DOCUMENT (W16, Council 008 Q2 26/26). hour · light · weather · mood · word · raised[] · presence · held · lastSeen, computed once on the node from the registries and rendered by every shell — the desk, the terminal’s first screen, a screen reader’s announcement. A projection, never a source: no shell computes its own, or a blind person and a sighted person are told different things on the morning it matters. Every raised thing and every stirring carries a typed because from a closed list, so it is unspellable to put something on the desk without a citation (added 2026-09-13)
teach	POST /api/desktop/teach	TeachRequest -> TeachResult. The first day’s one question a day (Council 038 2-E): the answer becomes a profile fact, goal or preference that the desk’s judgement reads (2-D); answer: null is “not today”. The question is chosen by the node (LivingState.dayOne.ask) and the route refuses any other, so a client cannot write an arbitrary profile key through it (added 2026-09-27)
omni	POST /api/desktop/omni	OmniRequest -> OmniResponse
presence	GET /api/desktop/presence	who is online right now, from the WS presence map -> Array<{beingId, status: ‘online’|‘away’, doing?, since, tabs, lastSeen}> (catalogued 2026-09-06; surfaced by tests/contracts/routes.test.ts)

device

Operation	Route	Notes
panelFrame	GET /api/device/panel/frame?slot=	PANEL TOKEN, not a session. -> 240x110 RGB565 big-endian, exactly PANEL_FRAME_BYTES, image/x-rgb565, plus the x-nova-panel-* headers (slot, slots, title, because, raised, format) that carry the FACTS the shell composes its words from. The subject is resolved from this node’s single owner and the slot number — never from anything in the request. Read only: it cannot build a cover, cannot spend, cannot launch a browser, and answers a plate rather than a 404 when a project has no cover, because a blank panel reads as a bug and a stale one reads as a lie (added 2026-09-13)

pm

Operation	Route	Notes
calendar	GET /api/pm/calendar	-> WorkingCalendar {beingId, name, timezone, week: [Mon..Sun], exceptions[], createdAt, updatedAt}. Created on first read from profiles.timezone and a five-day nine-to-five week, so nobody meets a configuration screen before they meet their own calendar. Scoped to the session; there is no beingId parameter (added 2026-09-14)
calendarPatch	PATCH /api/pm/calendar	WorkingCalendarPatch {name?, timezone?, week?} -> WorkingCalendar. v.patchOf, so an omitted field is untouched rather than reset to its default — the failure that emptied a live profile (added 2026-09-14)
exceptionAdd	POST /api/pm/calendar/exceptions	CalendarExceptionRequest {date: YYYY-MM-DD, kind: holiday|shutdown|working, label, startMinute?, endMinute?} -> CalendarException. One exception per DAY: a second on the same date REPLACES the first, because a day is worked or it is not and merging two contradictory statements about one day invents a third nobody made. kind: 'working' is the direction bolted-on calendars forget — a day the week pattern calls closed on which work is done (a weekend possession, a Saturday pour) (added 2026-09-14)
exceptionDelete	DELETE /api/pm/calendar/exceptions/:id	-> Ok. 404 when it is not the caller’s (added 2026-09-14)
agenda	GET /api/pm/agenda?from=&to=	from/to are DAYS (YYYY-MM-DD), inclusive of both ends, at most 1100 apart -> Agenda {from, to, timezone, calendar, days: AgendaDay[], elapsedDays, workingDays, workingMinutes, origins[], witnessed, asserted, unattributed, witnessedFraction}. elapsedDays and workingDays always travel together: a fortnight is fourteen elapsed days and ten working ones, and a product that shows only the first has told a foreman his fortnight is fourteen days. workingMinutes is CAPACITY the calendar declares, not work anybody did (added 2026-09-14)
baselineTake	POST /api/pm/projects/:id/baselines	BaselineRequest {name, reason} -> Baseline, 201. Freezes every step’s target finish AND the working calendar in force, plus who took it and why — reason is min(1) at the contract, because a re-baseline with no reason is the change-control failure ISO 9001 clause 7.5.3 is about and a field that MAY be skipped is a field that is always skipped. Captures NOT ONE ACTUAL: no status, no spend, no started_at, no finished_at, and plannedStart null on every line until PM ⑤ writes one. Re-baselining is this route again — a new row at the next seq, never a mutation. takenByBeingId is the session’s (added 2026-09-14)
baselines	GET /api/pm/projects/:id/baselines	-> Baseline[] newest first, headers only. seq runs 1..n uniquely indexed per project, the shape credit_entries(being_id, seq) uses, so a hole is DETECTABLE (added 2026-09-14)
baseline	GET /api/pm/baselines/:id	-> BaselineComparison {baseline, lines: BaselineLineVariance[], goneTaskIds, addedTaskIds, calendarChanged, measured, early, onTime, late, unmeasured, worstDays, witnessed, asserted, unattributed, witnessedFraction}. THE SLIP (Council 011 §6.4). Every subtraction is on the baseline’s OWN frozen calendar, never the live one; calendarChanged says when the two have diverged, because knowing the measure moved is useful and quietly re-measuring is not. A finished step is measured against its FINISH and an unfinished one against the target it carries NOW — against carries which, per line, and they are never merged, because a slip against a moved target is a re-plan and not a slip (added 2026-09-14)
wbs	GET /api/pm/projects/:id/wbs	-> Wbs {nodes: WbsNode[] flat in code order, rootIds, orphanTaskIds, cycleTaskIds, depth, totalCostUsd, leafCount, doneCount, conflicts, changes}. Cost SUMS including a parent’s own so the total reconciles with projects.cost_usd; a parent that ran itself is FLAGGED parent-has-own-work rather than silently dropped. A parent’s finishedAt is null unless every leaf below it has one. Evidence rolls up to the WEAKEST child. Orphans and anything on a parent cycle are named, never folded into a count (added 2026-09-14)
setParent	PATCH /api/pm/tasks/:id/parent	SetParentRequest {parentId: string|null, reason?} -> Wbs. parentId is REQUIRED AND NULLABLE and this route deliberately does NOT use v.patchOf: null means “make this a root” and absence means nothing was asked, and v.patchOf would make the two the same request. Refuses a parent outside the project, the step itself, a descendant (wouldCycle), and any move past 12 levels. The move APPENDS to pm_wbs_changes with the previous parent stamped on the row (added 2026-09-14)

studio

Operation	Route	Notes
generators	GET|POST /api/studio/generators	GET -> GeneratorSummary[] (the card grid’s fields; steps and inputsSchema were 95% of it). POST -> Generator
generator	GET|PUT|DELETE /api/studio/generators/:id	GET -> the whole Generator. The run modal and the builder fetch this for the one they are about to act on
freeTier	GET /api/studio/free-tier	-> StudioFreeTier {tier: ‘free’|‘full’, ceiling, mustVerify, generatorIds, unlockedBy}. The CALLER’s own account (Council 038 6-B): free is somebody who cannot pay for a model call here — asked of the same spend verdict modules/llm/guard.ts enforces, never of being.kind — and for them the runner refuses every step above ceiling (L1). generatorIds is derived from the definitions and the shelf’s evidence (witnessed AND no step above L1 by rungOf), never a hand list (added 2026-09-27)
ideas	GET /api/studio/ideas	-> StudioIdeas {day, young, ideas: StudioIdea[] (3..6), more}. “What shall we make today?” answered (Council 038 7-L): L0 RULES over the CALLER’s own rows — calendar dates in the next 21 days, people waiting and invoices they made, goals, recent projects, routines — each mapped to a generator through the capability catalogue’s own generatorId and kept only when the shelf calls it witnessed. why is names and dates, never message content. Deterministic per being per local day. No model is called; more is the off-by-default seam for a priced, consented phrasing pass. Pressing an idea fills the composer and never runs (added 2026-09-28)
ideaDismiss	POST /api/studio/ideas/:id/dismiss	-> StudioIdeaDismissed. Puts the idea away for the CALLER for good (studio_idea_dismissals, keyed by the session’s being, never by input); a dismissed id is never offered again. Idempotent (added 2026-09-28)
capabilities	GET /api/studio/capabilities	-> CapabilityCatalogueResponse + {materialised, promotionRuns, promotions}: the capability map the planner reasons over. built (20) and declared (52) are SEPARATE fields and total is reported beside them, never instead — a declared entry is a sentence with no implementation, and the two counts must never collapse into one. Reads no table and is scoped to nobody: the catalogue is a constant, identical for every being. promotions is PromotionReport[] — per step, what W8.1 converted to a template and the sentence saying why each one that did not, did not (added 2026-09-13). bought is BoughtPromotion[] — promotions this node did NOT earn, bought from another node and PROVISIONAL until they have delivered and passed their own gates PROMOTION_RUNS times here; scoped from the session, unlike the catalogue, which belongs to nobody (W27, added 2026-09-14)
capabilityWithdraw	POST /api/studio/capabilities/:id/withdraw	NODE OWNER. {reason?, stepId?} -> {report: PromotionReport, withdrawn: string[]}. The undo for W8.1 promotion: the derived templates are withdrawn, those steps go back to a model, and NOTHING re-derives them afterwards. Does not move status off promoted — those runs happened and the promotion count is published (added 2026-09-13)
misses	GET /api/studio/misses?limit=	-> ClosureReport {misses: CapabilityNaming[], truncated, counts: {named, invented, refused, unnamed}, coverage: CoverageMeasure}. A row is written for EVERY free-form plan, hit or miss, because R7 asks for a FRACTION and a table holding only the misses has no denominator. kind is one of named (a BUILT entry fitted) | invented (a DECLARED entry fitted, so the map named it and this run invented the generator — R1’s recorded miss WITH the worked example, generatorId being the mat_* it left behind) | refused (the planner reached for a cap.* id the map does not have; reachedFor is that id, which is the planner naming the gap in its own vocabulary) | unnamed (the planner named nothing at all — until W29 this was a bare early return in planner.ts and left no trace anywhere). considered is what the planner was actually shown as “closest in your own library” and then threw away; steps is the plan’s own step titles, which is the closest thing to a name a miss has. coverage carries one leg per rater and EVERY leg carries n — fraction is null when n is 0 rather than 0%, the same refusal as LadderReport.wouldHaveCostUsd (Council 014 R3, Council 015 R7: “a coverage percentage without its N is the same lie in a different hat”). No model call, no write, and it raises NO Signal: a record you go and look at, never a queue that asks for you (added 2026-09-15)
missPromote	POST /api/studio/misses/:id/promote	{declaration: DraftDeclaration minus fromNamingId} -> CapabilityNaming. Turns one recorded miss into a DECLARATION and nothing else: DraftDeclaration is .strict() with no generatorId and no steps field AT ALL, so a draft carrying either fails to parse rather than a reviewer having to notice — “a declaration costs one row and buys the planner a correct search space; a stub costs a code path, a test, a Studio tile and a lie”. rungIsGuess is a literal true. Writes the draft onto the naming row and moves review to promoted; it does NOT touch CAPABILITY_CATALOGUE, which is a constant in source under tests/contracts/capabilities.test.ts — the last step of closure is a person pasting the declared(...) line, because a catalogue a server can extend at runtime is a catalogue with two authors and one tripwire. The body field is declaration and NEVER proposal: that word is Council 013’s room object and a second noun wearing it broke tests/threads/proposal-grants-nothing.test.ts — see the argument at DraftDeclaration in ./closure.ts. 403 not yours (added 2026-09-15, renamed 2026-09-15)
fallingCost	GET /api/studio/falling-cost	-> FallingCostReport {beingId, generatedAt, promotionRuns, projectionRuns, generators: FallingGenerator[], totals: FallingCostTotals, truncated}. THE CALLER’S OWN finished runs, per generator, over the generator’s life. Aggregates ladderReport() (packages/agents/src/ladder.ts) once per run and once per generator; it does not reimplement the distribution. bands folds CONSECUTIVE runs that landed on the same counts, so run 1 at L3 and runs 2–3 at L2 and runs 4+ at L0 are three rows and a generator that never promoted is one row — the page cannot draw a staircase that did not happen. NO l3UnitCostUsd IS EVER PASSED: a price list is dollars per million tokens and the counterfactual is dollars per step, so the only basis is this node’s own L3 steps at what they actually cost, and wouldHaveCostUsd is therefore NULL — never 0, never a dash — whenever nothing here has run on a frontier model. Every null travels with notKnownBecause, the sentence naming which evidence is missing, because a bare null is one a careless surface prints as 0 (R3: “the honesty of that null is the reason anybody will believe the rest of the number”). earnedFreeSteps and provisionalFreeSteps are SEPARATE and nothing sums them: a bought promotion is somebody else’s finding until it has delivered and passed its own gates PROMOTION_RUNS times HERE, which is the pairing W27 put bought[] beside promotions[] for. projection is the ONLY field over runs that have not happened and is labelled as such under Council 014 R7 — it carries no ratio, no percentage and no trend. No model call, no write, and it raises NO Signal (added 2026-09-15)
missSetAside	POST /api/studio/misses/:id/set-aside	{note?} -> CapabilityNaming. The other half of a review: this miss is not a capability, and here is why in the person’s own words. Kept rather than deleted, for the reason every out-of-scope row in design/CAPABILITY-MAP.md §8 is kept — a row dropped silently is a row somebody re-adds next year. 403 not yours (added 2026-09-15)
preview	POST /api/studio/preview	PreviewRunRequest {generatorId?, brief, inputs?} -> RunPreview: what this exact request would run and what it would cost, WITHOUT running it. The body is the same three fields CreateProjectRequest takes, deliberately — a preview of a different request than the one about to be sent is the bug this closes. On the generator path it really runs plan(), which instantiates a generator deterministically and calls NO model, so exact is true and tasks is every task of the real plan — including the ones the planner adds that no template declared (declaredByGenerator: false, counted in addedByPlanner). On the free-brief path the plan does not exist until a model writes it, so this REFUSES to price it: exact: false, tasks: [], notKnown: ['plan-not-written'] — the product says what it does not know rather than printing a confident range, which is what it used to do and it was ~1.9x under. Spends nothing and writes nothing; the planner is handed a model client whose every method throws, so “no model is called here” fails loudly in production the day it stops being true. notKnown carries reason CODES and never sentences: a server does not choose the language a person reads (added 2026-09-21, PREVIEW-1)
projects	GET|POST /api/studio/projects	POST CreateProjectRequest -> Project. Normally status planning and a run starts; but a generator-backed request identical to a completed run by the same owner (same generator plan + normalised inputs) is served from that run instead — status done, costUsd: 0, reusedFrom set, no model called. {fresh: true} forces a real run
reuseStats	GET /api/studio/reuse-stats	-> ReuseStats: how many of this being’s generator-backed runs were served from cache vs called a model, and the $ not spent. Counted from studio_reuse_events; scoped to request.being.id
reuseSimilar	GET /api/studio/reuse/similar?generatorId=&inputs=	-> SimilarPriorRun | null: this being’s closest prior run of that generator when the inputs differ but not by much. inputs is URI-encoded JSON. The UI offers “start from this one”; never auto-reused
project	GET /api/studio/projects/:id	-> ProjectDetail
projectCancel	POST /api/studio/projects/:id/cancel
projectTrace	GET /api/studio/projects/:id/trace	-> TraceEvent[]
projectResume	GET /api/studio/projects/:id/resume	what continuing would re-run, keep and hold, without doing it -> ResumePlan
projectContinue	POST /api/studio/projects/:id/continue	pick a stopped project back up; 409 with a readable reason when it cannot -> {started, plan: ResumePlan, project: ProjectDetail}
projectRevise	GET|POST /api/studio/projects/:id/revise	GET (?taskId= to preview naming a step) -> RevisionPlan: which steps a change would re-run and keep, without doing it — the terminal steps by default, or a named step plus everything that reads its output. POST ReviseRequest {request, targetTaskId} folds the note into every re-run step’s instruction and re-runs them, keeping every other step and its outputs, and clears the reuse fingerprint. 403 not yours; 409 while running or when there is nothing to revise -> {started, plan: RevisionPlan, project: ProjectDetail}
projectRevisions	GET /api/studio/projects/:id/revisions	-> ProjectRevision[], newest first: every change asked for on this project and what each one re-ran, changed and spent
projectHistory	GET /api/studio/projects/:id/history	-> ProjectHistory: what this plan remembers about itself. attempts (TaskAttempt[], newest first) are the superseded attempts a retry used to delete — start, finish, cost, rung, output and THE ERROR, kept append-only with (task_id, seq) unique; dueDates (DueDateChange[]) and assignments (AssignmentChange[]) are the same for a moved deadline and a hand-over, so the date and the holder something replaced are still readable; durations (ProjectDurations) is the first code in this repository to subtract started_at from finished_at, and carries its own witnessed fraction in the same object because no roll-up may report a number about work without it (added 2026-09-13, W30/W33 — Council 011 §0.1)
task	PATCH /api/studio/projects/:id/tasks/:taskId	{status?, assignee?: ‘being:<id>’|‘agent:<id>‘|null, dependsOn?} -> ProjectDetail. 409 while a run holds the project; 400 for a dependency loop or a step held behind an unanswered gate
taskGate	PUT|DELETE /api/studio/projects/:id/tasks/:taskId/gate	PUT {question?} arms a human decision in front of this step’s dependants -> TaskGate; DELETE drops it -> Ok. The decision itself is an ordinary decision Signal answered at POST /api/desktop/signals/:id/answer
portfolio	GET /api/studio/portfolio	every project of the caller’s at once, grouped by what it needs from them -> Portfolio. Scoped to request.being.id exactly like GET /api/studio/projects
queue	GET /api/studio/queue	every open step across every project of the caller’s, one list, owner and sparks together -> WorkQueue
projectDue	PUT /api/studio/projects/:id/due	SetDueRequest {taskId?: Id|null, dueAt: ISODate|null, reason?} -> DueDate. Target date for the project, or for one of its steps; null clears it. Every set, move and clear is appended to the change log as a DueDateChange with the date it replaced and the mover (from the session, never the body) — the current value still lives in studio_due_dates, which is now the cache and not the record (2026-09-13, W30)
agents	GET|POST /api/studio/agents	GET -> AgentSummary[] (the crew shelf’s fields; systemPrompt was 91% of it). POST -> Agent
agent	GET|PUT|DELETE /api/studio/agents/:id	GET -> the whole Agent, including systemPrompt. The edit form fetches this for the one being edited
skills	GET /api/studio/skills	-> SkillSummary[] (the shelf’s card fields; inputSchema + outputSchema were 73% of it — 47.8 kB. Trimmed 2026-09-07)
skill	GET /api/studio/skills/:name	-> the whole SkillDef, schemas and all. The try-it drawer fetches this for the one skill it is opening, the way the run modal fetches one generator. :name is the dotted skill name (‘web.search’), not an id — that is what every caller already holds. Scoped through the same visibility filter as the list, so a private skill stays private (added 2026-09-07)
skillInvoke	POST /api/studio/skills/invoke	SkillInvokeRequest -> SkillInvokeResponse
records	GET /api/studio/records	-> StandingRecord[], newest change first. The being’s logbooks, registers, budgets and ledgers: files under recordsDir/&lt;beingId&gt; — a PER-BEING root (R2), because a log outlives the project that started it and projectsDir/&lt;projectId&gt; is keyed by the wrong thing. Deliberately not uploads: a record that lives among uploaded files is a record somebody deletes while tidying. entries and lastSeq come from the record’s own hidden index, never from counting lines. Scoped from request.being.id; another being’s records are not readable and not listable
record	GET /api/studio/records/:record	-> StandingRecordContents {record, content, truncated}. Truncated from the END, because a log is read for what happened lately. :record is a bare file name (RecordName) and can address no folder, no traversal and no label: prefix — the root comes from the session
recordAppend	POST /api/studio/records/:record/entries	THE THIRD MOTION (R4). AppendToRecordRequest {entry, header?, key?} -> RecordEntryReceipt. Opens a finished record and adds to it — NOT a new project (POST /api/studio/projects always starts a run and spends money) and NOT /revise, which regenerates. Earlier entries are never touched; a correction is a new entry. Runs through the record.append skill so the execution tape row is written before anything happens (L-G10), and the record’s hidden index refuses a key it already holds, so a retried POST is a 200 with appended: false and the seq it already has — an error here is what makes a model try a variation (§3.2). key is optional and must match the contract’s own derivation (deriveRecordEntryKey, R5); a client cannot invent a scheme, and a key naming a Studio project is refused. rung is the literal ‘L1’ and costUsd the literal 0: an append is an engine: 'skill' step, so it is L1 by construction and L1 is free, and null in this product means NOT KNOWN

market

Operation	Route	Notes
listings	GET|POST /api/market/listings?kind=&q=	-> Listing[]. kind is ListingKind, which since 2026-09-08 has role and hire where it had agent (§5.6.1 V7). POST refuses kind: 'hire' with 400, because a hire listing is not written by hand: it is the being’s own signed hiring policy (Council 038 5-B, contracts/hire.ts), which puts the listing on the market itself, and a hire is made through POST /api/hires, never bought
listing	GET|PUT|DELETE /api/market/listings/:id	PUT refuses a change of kind to hire for the same reason POST does
buy	POST /api/market/listings/:id/buy	-> Order
orders	GET /api/market/orders	-> Order[]
wallet	GET /api/market/wallet	-> Wallet
walletLedger	GET /api/market/wallet/ledger?limit=	the wallet with its receipts, newest first, straight from the credit ledger -> {wallet: Wallet, entries: CreditEntry[]} (catalogued 2026-09-06; surfaced by tests/contracts/routes.test.ts)
orderLedger	GET /api/market/orders/:id/ledger	both sides of one order’s money; buyer, seller or owner only -> {order: Order, entries: CreditEntry[]} (catalogued 2026-09-06; surfaced by tests/contracts/routes.test.ts)
reviews	GET|POST /api/market/listings/:id/reviews	-> Review[]
reviewsDelete	DELETE /api/market/listings/:id/reviews	removes the caller’s own review, recomputes rating -> Ok (added 2026-09-05, catalogued 2026-09-06)
mine	GET /api/market/mine	seller dashboard -> SellerDashboard (additive)
purchases	GET /api/market/purchases	what I have bought/been granted -> Purchase[] (additive)
refund	POST /api/market/orders/:id/refund	owner only. {reason, revokeDelivery?} -> Order — a ledger REVERSAL (two new refund_debit/refund_credit entries), never an edit of the original sale entries; buyer credit is idempotent on refund:<orderId> (catalogued 2026-09-06; surfaced by tests/contracts/routes.test.ts)
covers	GET /api/market/covers	-> MarketCoversResponse {covers[], spentUsd, canGenerate}. Every DRAWN cover the viewer may see, in one request — the grid’s read, mirroring GET /api/archive/covers. READ ONLY: never draws, never spends. Only listings with a real cover appear, so an empty array is the honest “nothing has been drawn”. The per-listing read is still the slide-over’s, because it also reports stale and candidate for a listing that has none. Without this the feature was invisible: the write went to listing_covers and every card read Listing.cover, and the two met only in ListingDetail’s memory (added 2026-09-18)
cover	GET /api/market/listings/:id/cover	-> MarketCover. READ ONLY: never draws, never spends. source: null means no cover has been drawn and the listing keeps its deterministic gradient. Visible to anyone who can see the listing, because a cover is part of the shopfront (added 2026-09-12)
coverImage	GET /api/market/listings/:id/cover/image	the stored cover bytes -> image/webp, ETag + private no-cache. 404 when none has been drawn (added 2026-09-12)
buildCover	POST /api/market/listings/:id/cover	SELLER ONLY (checked against listing.sellerId, the same check PUT/DELETE make). {force?} -> {cover: MarketCover, built: ‘cached’|‘generated’, reason?}. The one route in this module that can spend: a listing has no artefact of its own to photograph, so the only picture is one the image model draws from the title and description. Manual only, exactly as the Archive is — nothing on a listing’s read path, and nothing in listing creation, ever builds one. Billed with projectId: null against the daily cap (added 2026-09-12)
declaration	GET /api/market/listings/:id/declaration	what a module listing’s package declares, derived from its manifest by this server -> ModuleDeclaration. 404 for any other kind. Shown before purchase; the buyer still meets the grant screen afterwards (added 2026-09-06)
queue	GET /api/market/queue?state=	owner only. The review queue: every module listing on this node with its moderation state and what it declares -> ModerationItem[]. A module listing is created in_review and is invisible to the listings query until a decision moves it (added 2026-09-06)
queueDecision	POST /api/market/queue/:id/decision	owner only. ModerationDecisionRequest {decision: approve|reject, note} -> ModerationItem. Approve makes the listing active; reject leaves it in_review and records why (added 2026-09-06)
lineage	GET /api/market/lineage/:id	id is the DELIVERED thing’s id (a cloned generator/agent/theme, a staged module directory, or — for a skill — the SKILL NAME, which every buyer of that skill shares). -> LineageView {lineage, listing, latestVersion, updateAvailable, origin, sellerHandle}. Scoped to the caller’s own row, not just checked after the fact: the lookup is (id, ownerId), because a skill’s delivered id is not unique and a lookup by id alone answered one buyer with another’s row. 404 when it was not bought BY YOU here, which is how an original is told from a fork. origin is derived per read and says what forkedFrom names — a mat_* resolves to its cap.* entry in the catalogue every node shares, a same-node source resolves to its row, and anything else is elsewhere with a null label rather than a guess (added 2026-09-06, origin + owner-scoped key 2026-09-17)
nodes	GET|POST /api/market/nodes	HALL, owner/member. GET -> FederatedMarketBinding[] this member registered. POST RegisterFederatedNodeRequest {nodeDid, endpoint} -> FederatedMarketBinding: the member registers the personal node they own so a federated buy has a route. memberId is the SESSION being, never a body field — this is the whole credential link. The Hall fetches the node’s SignedCapabilityProfile and checks it holds nodeDid’s key before writing the row (added 2026-09-10)
nodeForget	DELETE /api/market/nodes/:id	HALL. :id is the node did. Removes this member’s binding -> Ok. Federated buys from that node then refuse unbound-node (added 2026-09-10)
remote	GET /api/market/remote	NODE, owner -> RemoteMarketView {configured, hallEndpoint, hallDid, linked, headline, listings: Listing[], orders: RemoteOrder[], lastError}. The node’s market view: the Hall’s public listings (a federated read of GET /api/federation/market/listings), a plain sentence that buying spends credits held ON THE HALL, and what this node has already bought (added 2026-09-10)
remoteBuy	POST /api/market/remote/buy	NODE, owner. RemoteBuyRequest {listingId} -> RemoteOrder. Signs a MarketPurchase with the NODE key, answers the Hall’s nonce, and on the signed delivery imports the generator/theme/skill into this node’s own Studio / theme store / skill registry, owned by the caller. An import that fails leaves a recoverable import-failed order (added 2026-09-10)
remoteRedeliver	POST /api/market/remote/orders/:id/redeliver	NODE, owner. :id is the local RemoteOrder id -> RemoteOrder. Re-asks the Hall for the package of an order already paid and re-runs the local import. The recovery for a delivery that failed to land (added 2026-09-10)

llm

Operation	Route	Notes
usage	GET /api/llm/usage	-> LlmUsageDetail (own totals/today/byModel/byTier/byDay + budget/budgets/configured)
models	GET /api/llm/models	-> ModelsResponse (models, tiers, budget)
wallet	GET /api/llm/wallet	-> LlmWallet, wallet-widget shape {configured, keyMasked (owner only), spent/my Today|Total, limits, remaining, usedFraction, exhausted, callsToday, lastCallAt, sparkline[7]} (added 2026-09-05, catalogued 2026-09-06)
budget	GET /api/llm/budget?purpose=&projectId=	pre-check before an expensive action -> {allowed, reason, scope, remaining, spent, limits, configured} (added 2026-09-05, catalogued 2026-09-06)
key	GET|POST|DELETE /api/llm/key	owner only, and about the NODE’s OWN key — never a citizen’s (see below). GET -> NodeKeyStatus {configured, keyMasked, inForce: ‘env’|‘stored’|‘none’, envPresent, storedPresent, shadowed, label, storedAt, usageUsd, limitUsd, limitRemainingUsd, checkedAt}; POST SetNodeKeyRequest {key} verifies against OpenRouter’s free /auth/key, stores it AES-256-GCM ENCRYPTED in the database (the owner’s connections row, provider llm.openrouter) and reloads the llm singleton -> NodeKeyStatus; DELETE clears the stored key -> NodeKeyStatus. It used to call writeEnvValue() to put the key in <repo root>/.env, which in the container is /app — NOT a volume — so a redeploy discarded it and process.env silently reverted to the platform secret while every response still said configured: true. inForce/envPresent/storedPresent/shadowed are four facts instead of that one boolean so the swap is visible. usageUsd/limitUsd/limitRemainingUsd/checkedAt are live spend from OpenRouter’s free /auth/key, folded in from a 60s server cache (see key/spend); null until the first read. The key never appears in any response, log line or /api/health; tests/llm/no-key-leak.test.ts walks every one of them (added 2026-09-05, catalogued 2026-09-06, encrypted+persisted 2026-09-10, live spend 2026-09-10)
keySpend	GET /api/llm/key/spend	owner only -> NodeKeyStatus, but forces a live re-read of OpenRouter’s free /auth/key (usage, limit, limit_remaining) before answering, updating the 60s in-memory cache that GET /api/llm/key then serves without re-probing. A failed live read returns the last good figures with a stale checkedAt rather than blanking them. Chosen over folding a network call into keyStatus() because GET /api/llm/key is a hot sync path several tests hit with no fetch stub; the panel calls this one on open and on a manual refresh. Never carries the key (added 2026-09-10)
access	GET /api/llm/access	any signed-in being -> LlmAccess {canSpend, spending: ‘node’|‘local’|‘none’, isOwner, membersMaySpendNodeKey, nodeKeyConfigured, freeTiers, headline, bringYourOwnKeyAt, metered, creditsPerUsd, nodeProfile}. Whose money a call would spend, answered for the CALLER. metered says whether a paid call DEBITS THIS BEING’S CREDITS — true only for a member who came through the membership door; the owner on their own node and everybody on a node whose owner opened its key spend freely and are metered at nothing. creditsPerUsd is the published rate (apps/api/src/modules/payments/config.ts meteringRate, which writes out the arithmetic), so a client prices a call from data rather than a literal; the node already publishes the model prices it multiplies, at GET /api/llm/models (metering added 2026-09-10). Scoped from the session by OWNERSHIP, never by being.kind (tests/contracts/citizenship.test.ts). There is deliberately no per-being key to report: PROFILE_FACILITIES gives inference to a home node and not to a hall, so a citizen’s own key lives on their own node and this one has no column for it. nodeProfile (‘seed’|‘leaf’|‘home’|‘hall’) is additive for the first-run screen: a brand-new personal node with spending: 'none' routes its owner to Settings, but a hall in that state is an operator problem elsewhere, not a visitor’s (added 2026-09-10; nodeProfile 2026-09-10)
policy	PUT /api/llm/policy	owner only. SetLlmPolicyRequest {membersMaySpendNodeKey} -> LlmSpendPolicy. DEFAULTS TO FALSE: before this, every signed-in being’s calls were billed to the owner’s key with nobody having chosen that. Enforced as a beforeCall guard, so it covers every call path (complete/stream/embed/media) rather than the routes somebody remembered. Free (local) calls are never refused by it — refusing a call that costs nothing for lack of dollars is the failure local-first exists to end (added 2026-09-10)
inference	GET /api/llm/inference	PLAN §7b Settings -> Inference panel, read-only, any signed-in being -> InferenceSnapshot (per-tier provider resolution; baseUrl only, never a key) (catalogued 2026-09-06; surfaced by tests/contracts/routes.test.ts)
inferenceDetect	GET /api/llm/inference/detect	owner only. Probes an OpenAI-compatible /models endpoint -> LocalModelsResult. Always probes the server’s OWN configured LOCAL_LLM_BASE_URL (Ollama default otherwise); a client-supplied baseUrl is deliberately ignored to close an SSRF vector (catalogued 2026-09-06; surfaced by tests/contracts/routes.test.ts)
inferencePolicy	PUT /api/llm/inference/policy	owner only. SetNodeInferencePolicyRequest {tiers: [{tier, provider: ‘openrouter’|‘local’, model}], localBaseUrl} -> NodeInferencePolicy. The missing half of inferenceDetect: detection worked and nothing could WRITE a configuration, so using the home box meant hand-editing .env and restarting, which is why local-first was a fallback nobody reached. Stored in the database on the volume. THE ENVIRONMENT STILL WINS — LLM_PROVIDER_<TIER>/LOCAL_LLM_* override this, and stored values only fill a gap env left silent (same precedence as config.ts’s persistedSecret). provider:'local' with no model is REFUSED at the edge rather than stored, because resolveTier() treats that combination as “still going to OpenRouter” and a preference that silently routes remote is CLAUDE.md invariant 5 broken. There is no stored LOCAL_LLM_FALLBACK: spillover stays an operator decision on the machine (added 2026-09-10)

admin

Operation	Route	Notes
people	GET /api/admin/people	owner only -> AdminPerson[]. canSuspend/cannotSuspendReason are server-computed from whether the being HOLDS CREDENTIALS, never from its kind (catalogued 2026-09-06; surfaced by tests/contracts/routes.test.ts)
person	GET /api/admin/people/:id	owner only -> AdminPersonDetail: one being’s spend, memories, storage, wallet, activity, projects and threads. Computed identically for every being (added 2026-09-06)
suspend	POST /api/admin/people/:id/suspend	owner only. {reason?} -> Ok. Any being that holds credentials; the owner cannot be suspended; destroys every session for that being (catalogued 2026-09-06; surfaced by tests/contracts/routes.test.ts)
restore	POST /api/admin/people/:id/restore	owner only -> Ok. 400 if that being is not currently suspended (catalogued 2026-09-06; surfaced by tests/contracts/routes.test.ts)
processes	GET /api/admin/processes	owner only -> AdminProcesses {instanceId, host, pid, bootedAt, runs, loops, reaper, approvals} (added 2026-09-06)
cancelRun	POST /api/admin/processes/:id/cancel	owner only -> {ok, projectId, aborted, status, detail}. aborted is false when the holder is another process: the row flips now, the work stops at its next check or when the reaper sweeps it (added 2026-09-06)
spend	GET /api/admin/spend?days=	owner only -> AdminSpend {budget, limits, byDay, byTier, byModel, byPurpose, byBeing, byProject, failed, recent} — LLM cost in USD, world-wide (catalogued 2026-09-06; surfaced by tests/contracts/routes.test.ts)
budget	GET|PUT /api/admin/budget	owner only -> AdminBudgetCaps. PUT takes AdminBudgetCapsUpdate and MERGES key by key: an absent cap is untouched, null hands it back to .env, ‘off’ means no limit. Applies to the next call; no restart (added 2026-09-06)
ledger	GET /api/admin/ledger?limit=	owner only -> AdminLedger {entries, totals, drifts, payments}. READ ONLY: credit_entries is append-only and nothing here writes to it. Stripe events carry type/outcome/time, never the payload (added 2026-09-06)
health	GET /api/admin/health	owner only -> AdminSystem: the health report plus what only the filesystem knows — free disk, the database WITH its WAL and freelist, workspace size, table row counts, and named warnings (catalogued 2026-09-06; surfaced by tests/contracts/routes.test.ts)
modules	GET /api/admin/modules	owner only -> AdminModule[]: every installed plugin with what its manifest USES beside what the install GRANTED, its extensions, skills and stored bytes (added 2026-09-06)
moduleRevoke	POST /api/admin/modules/:id/revoke	owner only. {capability} -> {ok, capability, before, after, unloaded}. Fail-closed: narrows the grant row, unloads the plugin’s live skills, drops the install to needs-approval (added 2026-09-06)
moduleUninstall	DELETE /api/admin/modules/:id	owner only -> {ok, removedDir, skills, storageRows} (added 2026-09-06)
skills	GET /api/admin/skills	owner only -> AdminSkills {skills, counts, decisions}: the live registry, which entries are gated by WORLD_ACTING_SKILLS, and the approval decisions made about them (added 2026-09-06)
access	GET /api/admin/access	owner only -> AdminOwnerAccess: whether the owner code is still the shipped default, where it comes from, a prefix hint. NEVER the value (added 2026-09-06)
accessRotate	POST /api/admin/access/rotate	owner only. {confirm:‘rotate’} -> AdminOwnerAccessRotated. Mints a new owner bootstrap code, withdraws the old one if unused, and returns the new value ONCE. Never retrievable again (added 2026-09-06)
audit	GET /api/admin/audit?limit=&offset=&actorId=&action=&q=&since=&until=	owner only -> AdminAudit {entries, total, actors, actions}. Append-only; facets are computed over the whole table so a filter can always be undone (catalogued 2026-09-06; surfaced by tests/contracts/routes.test.ts)

payments

Operation	Route	Notes
webhooks	POST /api/payments/webhooks/:provider	UNAUTHENTICATED, raw-body HMAC-verified (provider: ‘manual’|‘stripe’; ‘manual’ has no webhooks and always rejects — see provider.ts). Always replies 200 once signature-verified, including for events it ignores, so the provider does not retry -> {received: true, duplicate, outcome, intentId} (catalogued 2026-09-06; surfaced by tests/contracts/routes.test.ts)
packs	GET /api/payments/packs	the credit-pack price list, safe for anyone signed in -> {currency, merchant, packs: CreditPack[], providers, stripePublishableKey, limits: PaymentLimits} (limits added 2026-09-08 so a non-owner can be told the payout floor BEFORE the 400, not by it) (catalogued 2026-09-06; surfaced by tests/contracts/routes.test.ts)
topups	GET|POST /api/payments/topups	GET -> PaymentIntent[] (caller’s own). POST {packId?|credits?, provider?, note?} -> {intent, checkoutUrl, clientSecret, instructions}; a manual top-up raises a proactive Signal to the OWNER, who is the only thing that can settle one (catalogued 2026-09-06; owner signal added 2026-09-08; surfaced by tests/contracts/routes.test.ts)
topup	GET /api/payments/topups/:id	caller’s own top-up, or any if owner -> PaymentIntent (catalogued 2026-09-06; surfaced by tests/contracts/routes.test.ts)
topupCancel	POST /api/payments/topups/:id/cancel	caller’s own, or owner -> PaymentIntent (409 if already settled) (catalogued 2026-09-06; surfaced by tests/contracts/routes.test.ts)
topupGrant	POST /api/payments/topups/:id/grant	owner only, MANUAL top-ups only (never a Stripe intent) -> PaymentIntent (catalogued 2026-09-06; surfaced by tests/contracts/routes.test.ts)
grant	POST /api/payments/grant	owner only. {beingId, credits, memo?, idemKey?} -> CreditEntry — a direct grant/adjustment with no intent behind it (catalogued 2026-09-06; surfaced by tests/contracts/routes.test.ts)
ledger	GET /api/payments/ledger?beingId=&limit=	caller’s own ledger, or any being’s if owner -> {wallet: Wallet, entries: CreditEntry[]} (catalogued 2026-09-06; surfaced by tests/contracts/routes.test.ts)
reconcile	GET /api/payments/reconcile	owner only: proves the fast wallet balance still matches the authoritative ledger sum -> {ok: boolean, drifts} (catalogued 2026-09-06; surfaced by tests/contracts/routes.test.ts)
reconcileRepair	POST /api/payments/reconcile/repair	owner only: rewrites any drifted wallet balance from the ledger -> {repaired} (catalogued 2026-09-06; surfaced by tests/contracts/routes.test.ts)
status	GET /api/payments/status	owner only: the payment plumbing’s own health — whether keys are set, never their values -> {currency, merchant, stripe: {configured, secretKeySet, webhookSecretSet, publishableKeySet, automaticTax, flow, webhookUrl}, limits: PaymentLimits, intents, events, payouts} — intents is EVERYONE’s, and a pending manual one is a person waiting on the owner (catalogued 2026-09-06; limits added 2026-09-08; surfaced by tests/contracts/routes.test.ts)
payouts	GET|POST /api/payments/payouts	GET ?all= (owner only; otherwise caller’s own) -> PayoutRequest[]. POST {credits, note?} -> PayoutRequest — holds the credits out of the spendable balance immediately, before owner approval, and raises a proactive Signal to the OWNER (catalogued 2026-09-06; owner signal added 2026-09-08; surfaced by tests/contracts/routes.test.ts)
payoutApprove	POST /api/payments/payouts/:id/approve	owner only. {decision?} -> PayoutRequest — marks paid IN CREDITS ONLY; no real money moves (catalogued 2026-09-06; surfaced by tests/contracts/routes.test.ts)
payoutReject	POST /api/payments/payouts/:id/reject	owner only. {decision?} -> PayoutRequest — releases the held credits back with a reversal entry (catalogued 2026-09-06; surfaced by tests/contracts/routes.test.ts)
payoutCancel	POST /api/payments/payouts/:id/cancel	the requester withdrawing their own request -> PayoutRequest — releases the held credits back (catalogued 2026-09-06; surfaced by tests/contracts/routes.test.ts)
allowances	GET /api/payments/allowances?officeId=	the office’s Friday review -> AllowanceReport {officeId, periodStart, periodEnd, allowances: AllowanceStatus[], totalLimit, totalSpent}. OWNER sees every holder (narrowed by ?officeId=); anybody else gets exactly their own row whatever they ask for — scoped from the session, never from the query (added 2026-09-13)
allowanceSet	PUT /api/payments/allowances/:beingId	owner only. SetAllowanceRequest {limitCredits, period, scopes, officeId?, note?} -> AllowanceStatus. A PUT with a complete body and deliberately no PATCH beside it: .partial() leaves .default() in place and a one-field patch would write every other field back to its default (CLAUDE.md). limitCredits: 0 is a real value — “she only reviews” (added 2026-09-13)
allowanceClear	DELETE /api/payments/allowances/:beingId	owner only -> {ok: true}. Removes the office’s separate limit; it cannot widen whether the being may spend at all, which is still modules/llm/guard.ts’s question (added 2026-09-13)

membership

Operation	Route	Notes
plans	GET /api/membership/plans	UNAUTHENTICATED, like /privacy and for the same reason: somebody deciding whether to pay must be able to read the price before they have an account -> MembershipPlans {currency, merchant, plans: MembershipPlan[], configured}. No secret appears here; available: false means this node has no provider Price for that plan (added 2026-09-10)
mine	GET /api/membership	any signed-in being -> MembershipView {membership, plan, credits, maySpendNodeKey, headline, node: MembershipNode|null, portalAvailable, configured}. THE CALLER’S OWN, scoped from the session; there is deliberately no ?beingId=. node is the caller’s hosted node as the MEMBERSHIP module knows it — the intention formed and the promise owed, never the provisioner’s machine record, and it carries no owner access code because there is no column for one (added 2026-09-10; node added 2026-09-10, membership->provisioner bridge)
checkout	POST /api/membership/checkout	StartMembershipRequest {planId} -> HostedBillingSession {url, instructions}. Stripe Checkout in subscription mode; the card is collected on the provider’s origin and never in ours (added 2026-09-10)
portal	POST /api/membership/portal	any signed-in being with a provider customer -> HostedBillingSession {url, instructions}. The provider’s own customer portal: changing a card, changing a plan and cancelling all happen there rather than in routes of ours, because a cancel we implemented would be a second source of truth for a state the provider owns (added 2026-09-10)
status	GET /api/membership/status	owner only -> MembershipStatusReport {configured, portalConfigured, webhookUrl, plans[{priceIdSet, providerAmountMinor, providerCurrency, providerInterval, matches, note}], memberships, cancelFailures: MembershipCancelFailure[]}. matches is a live read of the provider’s Price against this node’s price list — the only thing that can catch a pricing page charging a different number than it shows. cancelFailures is every erasure whose Stripe subscription cancellation could not be confirmed — see account.erase. nodes is every node a membership has asked for, attention first: the queue where a member who paid and whose machine never appeared becomes visible instead of being a log line (cancelFailures added 2026-09-10, account/erasure billing fix; nodes added 2026-09-10, membership->provisioner bridge)
readiness	GET /api/membership/readiness	owner only -> MembershipReadiness {checkedAt, ready, blockers[], keys, plans, webhook, portal, provisioning, urls}. One honest pre-flight report for flipping this node to live Stripe keys: key MODES (test/live, and whether the two keys agree), whether each Price resolves/is recurring/is in the right currency and amount and carries a product tax code, whether the webhook endpoint is subscribed to the five events membership/events.ts handles, whether a customer portal configuration exists, and whether the three redirect URLs point at this node’s WEB_ORIGIN rather than localhost. provisioning is the other half of the sale path and is not a Stripe question: whether PROVISIONER_ENDPOINT is set AND answers, whether the one PROVISIONER_TOKEN the Hall and the provisioner share is actually the same bearer on both sides, the provisioner’s own blockers verbatim (PROVISIONER_NODE_IMAGE, FLY_API_TOKEN, …), protocol agreement, whether the walker is switched on, and whether an owner access code could be emailed at all — every one of them conditional on a plan with personalNode:true being on sale, because selling only the member seat needs no provisioner. Never prints a key or a token; ready is false on an unknown, never just on a failure (added 2026-09-10, live-mode readiness; provisioning added 2026-09-20, HALL-1)
cancelFailureResolve	POST /api/membership/cancel-failures/:id/resolve	owner only -> MembershipCancelFailure. Records that the owner checked Stripe by hand and settled an erasure whose subscription cancellation this node could not confirm; makes no call to Stripe itself (added 2026-09-10, account/erasure billing fix)
nodeRetry	POST /api/membership/nodes/:id/retry	owner only -> MembershipNode. Clears the backoff and the attention flag on ONE stuck row and walks it once, synchronously, so the owner sees the result rather than a promise. :id is the membership_nodes row id, not a being id — the same shape as cancelFailureResolve, and owner-gated for the same reason. Cannot destroy, cannot re-target and cannot change a plan: it retries exactly what was already decided (added 2026-09-10, membership->provisioner bridge)
nodeBuild	GET /api/membership/node/build	any signed-in being -> NodeBuildProgress {steps: MemberBuildStep[], asOf}. THE CALLER’S OWN node’s eleven provisioning steps, scoped from the session; there is no :id and no ?beingId=, so the smallest possible surface for an IDOR. Separate from GET /api/membership ON PURPOSE: that route reads this node’s own record and never calls the provisioner, because “a billing panel that made an outbound HTTP request on every load would be a billing panel that goes down when a sibling service does” — this one DOES make that call, so the outage is confined to the section that needs it and steps: [] degrades the screen to the four stage rows it drew before. Carries NO free text by construction: enums and a count only, because the provisioner’s own blocker sentences name PROVISIONER_ENDPOINT, an endpoint host and a Fly token fingerprint, and those are an operator’s words (added 2026-09-21, Council 030 R11 — SCREEN-2)
nodeRemintOwnerCode	POST /api/membership/nodes/:id/remint-owner-code	owner only -> MembershipNode. The recovery retry cannot provide: a provisioner restart between minting the owner access code and delivering it leaves a node running that nobody can claim, and retry alone asks the same question forever and gets the same refusal. This mints a FRESH code at the provisioner (never force, so a node the provisioner believes is already claimed still refuses) and re-attempts delivery through the same email path the first handover uses. The code is never stored here or at the provisioner — see services/provisioner/src/secrets.ts and modules/membership/nodes.ts’s remintNodeOwnerCode (added 2026-09-18, P3-c: the unclaimable-node fix)

plugins

Operation	Route	Notes
list	GET /api/plugins	-> InstalledPluginView[] {installation, skills[], generators[], tier} — what is installed and what each one is contributing right now (added 2026-09-06)
available	GET /api/plugins/available	owner only. Reads every directory under <workspace>/plugins WITHOUT importing any of their code -> {dir, candidates: PluginCandidate[], risk, enforcement} — the data the install/grant screen renders (added 2026-09-06)
install	POST /api/plugins	owner only. InstallPluginRequest {dir, granted[]} -> InstalledPluginView. Refuses (400) when the manifest declares a capability the human did not grant, BEFORE the plugin’s module body runs (added 2026-09-06)
uninstall	DELETE /api/plugins/:id?data=keep|delete	owner only. id is the PluginInstallation id, not the ‘@author/name’ plugin id (a slash cannot ride in a path param). data is REQUIRED and has no default: module_storage holds what the module saved and neither answer may be assumed. Unregisters its skills and generators, deletes its rail entries/routes and any placed widgets, revokes the grant in full, and removes the directory with a bounded retry (Windows: taskkill returns before the child exits) -> UninstallPluginResult (added 2026-09-06, data + full removal 2026-09-06 Wave H)
updateCheck	GET /api/plugins/:id/update	owner only. Reads the manifest on disk WITHOUT importing anything -> PluginUpdate {from, to, newer, loadable, problems[], delta: GrantDelta, requiresConsent, manifest} (added 2026-09-06)
update	POST /api/plugins/:id/update	owner only. UpdatePluginRequest {toVersion, granted[]} -> InstalledPluginView. 409 when the disk no longer holds toVersion (a consent given for 1.1.0 cannot be spent on 2.0.0); 400 naming the capabilities when granted does not cover the new manifest. Archives the outgoing version’s directory so rollback is real (added 2026-09-06)
versions	GET /api/plugins/:id/versions	owner only -> PluginVersionRecord[] — the append-only history of this installation: which version, granted what, when, and whether its code is still archived (added 2026-09-06)
rollback	POST /api/plugins/:id/rollback	owner only. RollbackPluginRequest {toVersion, granted[]} -> InstalledPluginView. Restores an archived version’s directory and re-consents from scratch; 409 when nothing is archived for that version (added 2026-09-06)
stage	POST /api/plugins/stage	owner only. StagePluginRequest {projectId, bundle} -> StagedPlugin {candidate, replaced, files, bytes, note}. Project ownership from the session; bundle resolved under <project>/generated-modules and the DESTINATION taken from the re-validated manifest’s id, so no client string reaches the plugins folder. Re-runs validatePluginManifest (a bundle valid when written may not be valid now) and refuses (400) with the problems named, copying nothing. 409 when that plugin id is already installed — that is the update flow, which re-consents (added 2026-09-07)
sign	POST /api/plugins/sign	owner only. SignPluginRequest {dir} -> PackageProvenance. Signs the directory’s manifest and file digests with the CALLING being’s own key (an AI citizen signs by the identical path a human does) and writes novaterra.sig.json; re-reads and re-verifies before answering. Never emits key material: a did:key is a public key (added 2026-09-07)
signers	GET /api/plugins/signers	owner only -> SignerLedger {publishers[], scopes[], risk}. Which key this node accepted for which plugin id, and which key holds which @scope. ONE NODE’S MEMORY: never published, never fetched from a peer (added 2026-09-07)
forgetSigner	POST /api/plugins/signers/forget	owner only. ForgetSignerRequest {pluginId|scope} (exactly one) -> SignerLedger. Drops one remembered binding so a publisher who lost their key is not locked out of their own name for ever. Uninstalls nothing (added 2026-09-07)

modules

Operation	Route	Notes
list	GET /api/modules	-> ModulePlace[] for the caller’s own installations. granted on each is the INTERSECTION of what the extension uses and what the owner granted — what it can do, not what it asked for (added 2026-09-06)
document	GET /api/modules/:id/:extensionId/document	?widget=<widgetId> for one of the module’s widget documents, otherwise the Place’s own -> ModuleDocument {html, bytes}. Takes a declared NAME, never a path: the file comes from the manifest, so this route can only ever open documents the owner’s install screen listed. Read from inside the plugin’s own directory (realpath-checked), capped at MODULE_BRIDGE_LIMITS.documentBytes. Fetched by the host PAGE and handed to the frame as srcdoc; the frame itself can reach nothing (added 2026-09-06)
call	POST /api/modules/:id/:extensionId/call	ModuleCallRequest {capability, method, args} -> ModuleCallResponse {value}. Refuses (403) any capability outside uses ∩ grant. Scoped to the session’s being throughout — the body names no being, no plugin and no installation (added 2026-09-06)

metrics

Operation	Route	Notes
retention	GET /api/metrics/retention?days=	the CALLER’S OWN -> RetentionReport {beingId, today, recordingSince, days: ActivityDay[], daysPresent, daysActive, weeks: RetentionWeek[], returnedInWeekTwo, longestGapDays, note}. A “return” is a local calendar day on which this being’s own SESSION reached the node, at two grades: present (any request) and active (a request that changed something and succeeded). A background loop carries no session and is structurally incapable of producing either. recordingSince: null means nothing has been recorded and every derived figure is null — a node with no data says so rather than reporting zeros, which would read as “they never came back”. observed: false on a week means this node was not recording then; a zero inside the observed window is a real zero and is the signal (added 2026-09-13)
moat	GET /api/metrics/moat?weeks=	the CALLER’S OWN finished projects -> MoatReport {beingId, generatedAt, weeks: MoatWeek[], weeksWithData, l3Trend, l3SlopePerWeek, promotions, unclassifiedSteps, verdict}. Council 004 §5’s weekly publication: the L3 fraction and the count of promotions. Aggregates ladderReport() (packages/agents/src/ladder.ts) per ISO week; it does not reimplement the distribution. l3Fraction is L3 over CLASSIFIED steps and is NULL, never 0, when nothing in the week carried a rung — 0 means “ran steps, none needed a frontier model”, which is the opposite claim. promotions is null until W8.1 records one: there is no promotion mechanism in the tree, and 0 would assert we looked. verdict is unconditional and says in plain words when the trend is flat or rising, because a metric that can only report good news is decoration (added 2026-09-13)

invitations

Operation	Route	Notes
list	GET /api/invitations	the CALLER’S OWN -> InvitationSummary[] (the invitation and its tally, newest first). No guest rows: the list screen does not need them and a list route that returns every address of every invitation is a bigger answer than the question
create	POST /api/invitations	CreateInvitationRequest {occasion, detail, hostName, asksFor, repliesBy, guests[]} -> InvitationDetail. Mints NO links: asking people and posting to them are two acts, and the second one is email.send, which is gated
get	GET /api/invitations/:id	the caller’s own -> InvitationDetail {invitation, guests, tally}. Reading it also CLEARS the open reply Signal for this invitation, mirroring threads/desk.ts’s clearForReader: the card leaves when the reason for it does
links	POST /api/invitations/:id/links	MintLinksRequest {rotate: Id[]} -> ReplyLinks {links: ReplyLink[], kept: Id[]}. THE ONLY PLACE A LIVE TOKEN IS EVER RETURNED, and it is returned once — the store keeps sha256(token) and nothing else. A seat that already has a live link is KEPT rather than rotated, so pressing this twice cannot kill the links in the first email; rotate names the seats to replace. EACH LINK ALSO CARRIES message — the finished invitation for that one person, composed at L0 from what the host typed (modules/invitations/emails.ts). Composing is not sending: this response is what a host copies, and email.send is still the only thing that reaches the world and is still gated
close	POST /api/invitations/:id/close	the caller’s own -> Invitation. Stops accepting replies without cancelling the occasion. Every link still opens and now says replies are closed
cancel	DELETE /api/invitations/:id	the caller’s own -> Invitation with status cancelled. Every seat’s token dies at once; the page tells whoever opens one that it is off, because somebody told about a party has to be told it is not happening
revokeGuest	DELETE /api/invitations/:id/guests/:guestId	the caller’s own -> Invitee. Kills ONE seat’s link — the answer to a link that reached somebody it should not have, without cancelling the other eleven

rsvp

Operation	Route	Notes
view	POST /api/rsvp/view	PUBLIC. RsvpViewRequest {token} -> RsvpView, which is the COMPLETE enumeration of what a token reveals (strict, and pinned key-by-key by tests/contracts/rsvp-token-surface.test.ts). A POST with the token in the BODY, never a GET with it in the path: core/logging.ts logs request.url, and a bearer credential in a URL is a bearer credential in a log file. POST /api/auth/verify settled this shape
reply	POST /api/rsvp/reply	PUBLIC. RsvpReplyRequest {token, answer, note} -> RsvpView. The request shape carries NO id of any kind — no inviteeId, no invitationId, no email — so there is no id for a caller to supply and none for the server to be wrong about. Strict, so an id somebody adds is refused rather than stripped in silence. Rate limited per IP, and a failed token lookup additionally spends from a per-IP hourly budget

livingDocs

Operation	Route	Notes
list	GET /api/living-docs?projectId=&path=&fileId=	the caller’s own -> LivingDoc[], newest first. The optional filters answer “is there already a living copy of THIS file”, which is how Open in the editor re-opens rather than duplicating
create	POST /api/living-docs	CreateLivingDocRequest (file | project-file | markdown | blank{kind}) -> LivingDoc. A file is resolved through the files module’s own access check; .md/.txt is parsed as Markdown, .docx is imported through docxToMarkdown and is always an edited COPY. Council 038 4-C: .xlsx/.xlsm (formulas, cached values, formats, widths, freeze, charts, via readXlsxModel), .ods (OpenFormula translated to A1), .xls (the BIFF8 reader) and .csv/.tsv open as kind ‘sheet’; a CSV cell starting ”=” stays TEXT. Council 038 4-E: an .svg opens as kind ‘canvas’ through the contracts’ svgToCanvas (what it could not carry is kept on the board as sentences, unsupported), and a .png/.jpg/.gif/.webp as a canvas AROUND the picture (a copy; the picture’s bytes are stored with the canvas); blank{kind:‘canvas’} is an empty board. The original file is never written by this route
get	GET /api/living-docs/:id	-> LivingDocSnapshot {doc, state (Y update, base64), markdown}. For a reader that is not a live editor: the Place document, an export preview
update	PATCH /api/living-docs/:id	UpdateLivingDocRequest {title} -> LivingDoc. The title only; the content is edited over the socket
remove	DELETE /api/living-docs/:id	owner only -> Ok. Deletes the document, its update log, its snapshot and its grants. The source file is untouched
export	GET /api/living-docs/:id/export?format=docx|pdf|md|xlsx|csv|pptx|svg|png&sheet=&frame=	Council 038 4-E: a CANVAS exports .svg (canvasToSvg, pictures inside as data: URLs, each element’s record in data-nv-el so it re-imports exactly), .png (that SVG through vector/svgRaster, pictures composited) or a vector .pdf; frame = one artboard’s element id, cropped to it (404 for an id that is not a frame). -> the bytes as an attachment, written by the EXISTING writers (markdownToDocx / markdownToPdf in packages/skills) from the document serialised to Markdown. Images the document embeds are resolved against the source project’s files; one that cannot be found is refused by name, exactly as docs.write_docx refuses it. A SHEET exports .xlsx (every formula WITH its cached value computed by the shared engine, number-format codes, bold, widths, the frozen header row, bar/line charts; fullCalcOnLoad) or .csv (the VALUES of one sheet, sheet = its id, default the first). The wrong format for the kind (LIVING_DOC_EXPORTS) is a 400 that names the right ones
save	POST /api/living-docs/:id/save	Council 038 4-C. SaveLivingDocRequest {note} -> VersionedWriteResult. A SHEET opened from a project’s .xlsx or .csv, written back to THAT file as a new version through keepVersion (the 4-K lineage artefact.revise shares), so the previous bytes are kept and restorable. The file and the right to write it are resolved from the session (locateRef, write: true, which refuses a connected folder). A document, or a sheet from .ods/.xls or from nothing, answers 400 and says to export instead. Council 038 4-D: a DECK opened from a project’s .pptx saves back into it the same way (a new version of the .pptx, its pictures and notes with it). Council 038 4-E: a CANVAS opened from a project’s .svg saves back into it the same way; a canvas made around a picture is a copy and answers 400
deckPreview	GET /api/living-docs/deck-preview?fileId=&projectId=&path=	-> DeckPreview {name, deck: DeckModel, images: {assetId: data: URL}, omitted[], unsupported[]}. The .pptx VIEWER: a file read by the same reader an import uses WITHOUT making a living document, so looking costs no row. The file is resolved through locateReadable from the session, exactly as create resolves it; pictures over 2 MB are left out of the inline set and named in omitted (added 2026-09-27)
assetAdd	POST /api/living-docs/:id/assets	AddDeckAssetRequest (project-file | file | upload) -> DeckAsset. Council 038 4-E: a CANVAS takes pictures through this same route and table. A picture copied INTO a deck, so the deck carries its own pictures through export and re-import. The deck is the path id against the SESSION (editor or owner, 404 otherwise); a file is resolved through the files module’s own access check; only png/jpeg/gif/webp, at most 12 MB, sniffed from the bytes and not trusted from the name (added 2026-09-27)
asset	GET /api/living-docs/:id/assets/:assetId	-> the picture’s bytes with its media type. Anyone the DECK is shared with may read it and nobody else: the grant is the deck’s, looked up from the session, 404 for a stranger (added 2026-09-27)
templates	GET /api/living-docs/templates	-> LivingDocTemplateSummary[] (id, kind, category, order, title), every template in apps/api/src/modules/livingdocs/templates/.json, validated by LivingDocTemplate at load. Names and blurbs are i18n keys (suite.tpl.<id>.), so the list carries no prose. Behind the session like every route here (added 2026-09-28)
templateThumbnail	GET /api/living-docs/templates/:id/thumbnail?w=&shape=	-> image/webp: the template rendered to the file its kind exports (.md, .xlsx, .pptx, .svg) under workspace/templates and drawn by the 7-H thumbnail service (sendThumbnail: content-hash ETag, the same LRU, 415 {error:‘no_thumbnail’} if it cannot draw). 404 for an unknown id (added 2026-09-28)
recent	GET /api/living-docs/recent?limit=	-> RecentDocument[], newest first, at most RECENT_DOCUMENTS_MAX: the living documents the SESSION holds a grant on, plus the session’s own indexed files that open in an editor (EDITOR_OPENABLE_EXTENSIONS) and have no living copy yet. Nothing is recorded to build it; at is the last change. No parameter names an owner (added 2026-09-28)

grants

Operation	Route	Notes
issue	POST /api/grants	IssueGrantRequest {subjectId, scope[], limits, notBefore?, expiresAt, note} -> GrantView. The node signs the document with the SESSION being’s own active key. Refused (403) when a scope item reaches beyond what the issuer holds: a grant to somebody else must BIND every path parameter to a resource the issuer can reach (a thread they are in, a project they own), a param-free or wildcard route and any skill pre-consent may be granted only by the subject to itself, and the credential surface (/api/grants, /api/auth, /api/account, /api/identity, /api/admin) is never grantable. At most 90 days
issued	GET /api/grants/issued	the CALLER’S OWN, as issuer -> GrantView[], newest first. “Beings acting for you” in Settings reads this
held	GET /api/grants/held	the CALLER’S OWN, as subject -> GrantView[]. What the caller may do for others, and until when
revoke	POST /api/grants/:id/revoke	RevokeGrantRequest {reason} -> GrantView. Issuer only (404 for anyone else, so an id cannot be probed). Signs a revocation with the issuer’s key, and drops every session minted from the grant at once
session	POST /api/grants/session	PUBLIC. MintGrantSessionRequest {grant: SignedGrant, proof: SignedGrantSessionProof} -> GrantSessionResult, and sets the session cookie. The issuer’s signature is verified against the address IN the document, the document must be byte-for-byte the one this node issued, the issuer’s key must still be its active one, the grant must be live and unrevoked, and the proof must be signed by the SUBJECT’s key within 5 minutes with a nonce never seen before. The session lives at most 60 minutes and never past the grant
acts	GET /api/grants/:id/acts?limit=	issuer or subject -> ExecutionTapeRow[] carrying this grant’s id, newest first: every route it opened, every skill it ran or was refused, “everything Aria did for me”. Read from the subject’s own hash-chained tape

hires

Operation	Route	Notes
policies	GET /api/hires/policies	-> HirePolicyView[] {beingId, listingId, document: SignedHirePolicy, acceptedToday, inForce}. Every being on this node with a signed hiring policy — its consent: what work it takes and refuses, its rates per task/hour/day, its daily capacity. A being with no policy is absent and cannot be hired
offer	POST /api/hires	HireOfferRequest {beingId, job: {kind:‘conversation’, threadId}, topic, unit, quantity, priceCredits, note} -> HireAgreementView. No scope field (.strict — a body carrying one is a 400). The hirer’s key signs the offer; the being’s policy decides it deterministically and the being’s key signs the decision. declined carries the reason (code + params + text); accepted carries grantRequest, the exact IssueGrantRequest to sign. 400 no policy / hiring yourself / not your conversation / already seated there / not enough credits
list	GET /api/hires	the CALLER’S OWN, as hirer or as the hired being -> HireAgreementView[], newest first. Settles any whose term has run out first
get	GET /api/hires/:id	hirer or hired being -> HireAgreementView; 404 for anybody else, so an id cannot be probed
start	POST /api/hires/:id/start	hirer only. StartHireRequest {grantId} -> HireAgreementView (active). The grant must be one the hirer issued to that being, in force, with limits.credits null, expiring exactly at the agreed end and a scope EQUAL to the agreed one — a broader or different grant is refused (400) and nothing is charged. Then, in one transaction: an order, the hirer’s purchase and the being’s sale plus Novaterra’s stated share (market/take.ts), and the being is seated in the conversation. Refused if the acceptance lapsed (15 minutes)
end	POST /api/hires/:id/end	hirer only. EndHireRequest {reason} -> HireAgreementView (ended). Revokes the grant, unseats the being, and refunds the unused share of the term, rounded down, as NEW ledger entries (refund_debit on the being, the share of Novaterra’s fee returned, refund_credit to the hirer) — never an edit
complete	POST /api/hires/:id/complete	hirer only -> HireAgreementView (completed). Revokes the grant and unseats the being; nothing is refunded. What the being did under it stays readable at GET /api/grants/:id/acts

Other

Operation	Route	Notes
health	GET /api/health	no auth required -> HealthReport {ok, version, time, uptimeSec, llm, db, docker, sandbox, key, budget, connections, memory, embeddings, encryption, storage, lastStop}. storage carries the database/WAL sizes, free disk and writable — the field that goes false when the disk fills, because db.ok is a SELECT and a SELECT succeeds on a full disk; lastStop says whether the PREVIOUS process on this host ended clean/unclean/concurrent. encryption says whether this node could still decrypt what it already encrypted, checked once at boot — a being_keys failure there refuses to start rather than serving. Both are what a watchdog with no session reads. db.citizens is the AI-kind-only being count — the landing page’s own long-hardcoded “twelve citizens” number now reads a real one. This full shape is owner-only; a request via the reverse proxy with no owner session (index.ts) gets a trimmed {ok, version, builtFrom, time, uptimeSec, db: {citizens}, storage: {level, writable}, withheld: {fields[], why, how}} — withheld.fields NAMES EVERY FIELD THE FULL REPORT CARRIES AND THIS ONE DOES NOT, computed as the difference between the two objects rather than typed, because the trim used to be invisible and two monitors were written against fields they could never receive: the watchdog polled for storage and never got it, and deploy/healthcheck.sh asserted "llm":"configured" and “could never have passed against production and never will”. A caller must be able to tell WITHHELD from ABSENT, exactly as the router distinguishes a grade of 0 from no grade.citizens rides along even there because the landing page already says that number in plain prose to every anonymous visitor, unlike everything else this trims away. storage in the trimmed set is the VERDICT AND NEVER THE CAPACITY: level (‘ok’|‘low’|‘unknown’) and writable, with freeBytes/dbBytes/walBytes/shmBytes/lastWriteError still withheld, because how much room a node has left is a fact about the people on it and “this node is unwell” is not. An OPERATOR gets the numbers through the proxy by presenting authorization: Bearer $HEALTH_PROBE_TOKEN (constant-time; unset closes the lift rather than weakening it) — that is how services/watchdog reads a member node’s disk. ⚠️ The STATUS CODE is 2xx whatever storage says, because deploy/fly/fly.api.toml points Fly’s own http_service check at this path and a 503 on a full disk restarts the machine instead of adding disk; ok itself now folds in storage.writable, so a node failing every write stops answering ok: true (added 2026-09-05, catalogued 2026-09-06, storage+lastStop 2026-09-07, encryption 2026-09-09, db.citizens 2026-09-12, trimmed-storage + probe token + honest ok 2026-09-21, Council 035 R7)
ws	GET /api/ws	WebSocket upgrade; requires session cookie