brain/API.md

API reference

Go API: http://localhost:8080. The web UI uses the same paths through its server-side proxy at http://localhost:3000 and its NextAuth session.

Successful responses are JSON unless marked Markdown. Errors are {"error":"message"}. Data endpoints require authentication: 401 without a valid session, 404 for another user's private record, 403 for non-admin administration, 400 for invalid input, 409 for duplicates.

Authentication

Method	Path	Returns
GET	/healthz	{"status":"ok"} (process liveness)
GET	/readyz	{"status":"ready"} after database ping; 503 when unavailable
POST	/api/signup	201 {ok:true} — the same uniform body for fresh, duplicate and operator-reserved addresses (review CR-03: no existence oracle); body {email,password,name?}
POST	/api/auth/login	{ok:true,user:{id,name,email,image,role}} and signed HttpOnly cookie
GET	/api/auth/session	{user} or null for no valid cookie
POST	/api/auth/signout	{ok:true} and expired cookie
GET	/api/me	{user,effectiveUser,isAdmin,viewingAs}; real and effective identities
GET	/api/auth/oidc/status	{enabled,issuerSet,clientIdSet,clientSecretSet,issuer}; never includes secrets
GET	/api/auth/oidc/login	501, client-owned Authelia integration stub
GET, POST	/api/auth/callback/authelia	501, client-owned callback stub

The browser's NextAuth /api/auth/* endpoints remain on the Next server. Direct Go API consumers use the computer_session cookie from login. Go login accepts JSON and rejects foreign browser origins. The custom Next.js login endpoint also requires the configured same-origin Origin header. Login and signup are throttled per client IP (429 with Retry-After), plus a consecutive-failure lockout per IP+email on login; loopback clients are exempt. Browser traffic arrives through the trusted Next proxy, which forwards the observed client IP in X-Computer-Client-Ip signed with HMAC-SHA256 under the shared secret (X-Computer-Client-Sig); Go buckets on that identity only when the signature verifies and falls back to the direct peer otherwise, so proxied browsers neither share one bucket nor forge another identity. ADMIN_EMAILS reserves administrator addresses for operator provisioning and disables public first-admin bootstrap while set. Automatic promotion of an existing allowlisted user requires emailVerified; DB administrator roles remain authoritative. First-signup administrator promotion is one-shot: once bootstrap completion is recorded (AppSetting adminBootstrap), the absence of a qualifying administrator — e.g. after demoting the last one — never re-opens promotion through signup. Recovery is operator-driven (ADMIN_EMAILS + make seed, or promotion by an existing admin).

Bookmarks

Bookmark responses are permission-specific. Owners receive camelCase scalar fields plus tags:[{tag}], contact, sharedWith:[{userId,user}] and owner (with email). Authenticated shared readers receive a narrowed allowlist — URL, title/description, notes, preview metadata, dueDate, isPublic, kanbanStatus, timestamps, tags and owner:{id,name} — never the owner's contact record, the recipient list, alerts, mailbox watches or board placement. Detail responses also include pageLinks:[{pageId,page}], limited to the effective user's pages.

Method	Path	Returns / behavior
GET	/api/bookmarks	Array, newest-updated then ID descending; query search,tagId,contactId,kanban,date,shared,limit,cursor; default/max page size 200
POST	/api/bookmarks	201 bookmark; body {url,title?,description?,notes?,dueDate?,alertAt?,kanbanStatus?,contactId?,tagIds?,isPublic?,imapWatchEnabled?,imapQuery?}
GET	/api/bookmarks/{id}	Owner-full or shared-reader projection if visible; public-only access uses the redacted public endpoint
PUT	/api/bookmarks/{id}	Updated bookmark, owner only; fields above plus kanbanColumnId; omitted fields stay unchanged; nullable fields can be cleared. Requires version (the revision the client edited from): 400 when missing, 409 when stale — success bumps version (review CR-04)
DELETE	/api/bookmarks/{id}	{ok:true}, owner only
POST	/api/bookmarks/{id}/share	{ok:true}; body {userIds?,isPublic?}; adds shares
DELETE	/api/bookmarks/{id}/share/{userId}	{ok:true}; revokes that direct share
GET	/api/bookmarks/{id}/markdown	Markdown attachment, owned/shared only
GET	/api/preview?url=...	{title,description,ogTitle,ogDescription,ogImage,favicon}; nullable on fetch failure
GET	/api/public/bookmarks/{id}	Public bookmark projection without login; private records return 404

Public HTML pages remain at /share/bookmark/{id} on the Next.js server. For pagination, read the X-Next-Cursor response header and pass that opaque value as cursor with the same filters. An absent header marks the final page. limit must be between 1 and 200. The web proxy forwards the cursor header. Public responses allowlist URL/preview/notes/date/tag fields only; owner identity, contacts, share recipients, mailbox queries, and alert metadata are excluded. Updating alertAt resets alertSent; replacing tagIds is transactional. Tags, columns and contacts are checked for accessibility/ownership. The version contract covers the owner-driven PUT (fields and tag replacement) and kanban card moves (PUT /api/kanban/cards/{id}): kanban column deletion moves bookmarks server-side and bumps their version too, so a stale board save 409s instead of moving a card back into a deleted column. Sharing (POST /share) and the server-driven alertSent flag are deliberately outside the contract (review CR-04).

Input limits are enforced per field, not just by the 1 MiB request-body cap: bookmark url 2048, title 500, description 2000, notes 100000 and imapQuery 500 characters; tag names 80; page content 524288 characters and icon 64; collection names/properties/views and item values have their own documented bounds. Caps on these fields reject over-limit input with 400; a few older metadata fields (page titles, kanban labels, collection names/options) still trim to their existing limits.

Outbound preview fetches are restricted to HTTP/HTTPS ports 80/443 and mailbox connections to IMAP ports 143/993 (the fixture/LAN escape hatches are test-only). CardDAV keeps the configured HTTPS port.

Tags, kanban and pages

Method	Path	Returns / behavior
GET	/api/tags	Owned/shared tags with _count.bookmarks and sharedWith
POST	/api/tags	201 tag; body {name,color?}
PUT	/api/tags/{id}	Updated tag; body {name?,color?,shareUserIds?}, owner only
DELETE	/api/tags/{id}	{ok:true}
DELETE	/api/tags/{id}/share/{userId}	{ok:true}, revokes tag share
GET	/api/kanban/columns	Ordered columns; creates four defaults if none exist
POST	/api/kanban/columns	201 column; body {label,color?}
PUT	/api/kanban/columns	Ordered columns; body {order:[id,...]}, complete permutation required
PATCH	/api/kanban/columns/{id}	Updated column; body {label?,color?}
DELETE	/api/kanban/columns/{id}	{ok:true,movedTo,moved}; moves cards, never deletes bookmarks; refuses last column
PUT	/api/kanban/cards/{id}	Moved bookmark; body {columnId,position,version}. Reorders the target column (0-based position, clamped at the end) and normalizes every card's kanbanPosition. Owner only. version is REQUIRED: 400 when missing/invalid, 409 when stale; success bumps the moved card's version
GET	/api/pages?search=...	Pages, pinned first, with parentId and _count.{bookmarks,children}; title/content substring search treats % and _ literally and uses trigram indexes
POST	/api/pages	201 page; body {title?,content?,parentId?}. parentId must be an owned page; a missing/foreign parent is 400
PUT	/api/pages	{ok:true}; complete {order:[id,...]}
GET	/api/pages/{id}	Page plus ordered bookmarks:[{bookmark}], owner-scoped backlinks:[{id,title,updatedAt}], resolved outgoing links:[{id,title}], and embeds:[{collectionId,viewId,position,collection,view}]
PATCH	/api/pages/{id}	Updated page; {title?,content?,pinned?,icon?,parentId?,version?,addBookmarkId?,removeBookmarkId?}. version (the base revision from GET) is REQUIRED with content: 400 when missing, 409 when stale. Metadata-only patches (including moving a page) stay version-free and do not bump the revision. Moving under itself or a descendant is rejected 400 (no cycles)
GET	/api/pages/{id}/backlinks	Owner-scoped [{id,title,updatedAt}] from PageLink — the pages whose Markdown links here
GET	/api/pages/{id}/revisions	Version history metadata [{id,version,title,icon,createdAt,length}], newest first; bodies fetched separately
GET	/api/pages/{id}/revisions/{revisionId}	Full immutable revision snapshot {...,content}
POST	/api/pages/{id}/revisions/{revisionId}/restore	Restores a snapshot as a new version; body {version} (current base) — 400 missing, 409 stale. The restore itself is recorded in history
DELETE	/api/pages/{id}	Moves the page to Trash; keeps bookmarks and promotes child pages. Restoring also restores its revisions and creates a new revision
GET	/api/pages/{id}/markdown	Markdown attachment

Connected pages (phase 3)

Page hierarchy, internal links and live collection embeds are ordinary Markdown contained in the page body; the server rebuilds the resolved graph in the same transaction as every content save:

• [label](computer:page/<pageId>) links to another page. /pages?id=<id> and page/<id> are accepted as hand-written aliases. Only owned targets are stored, so a backlink can never reveal another account's page title; self-links are ignored.
• {{collection:<collectionId>}} embeds the collection's live default view; {{collection:<collectionId>|view=<viewId>}} pins a saved view's filters/sorts. Only owned collections are stored, and item reads still go through the normal collection endpoint, so an embed displays data without publishing it or widening bookmark access.
• Deleting a page removes its links/embeds, promotes its children, and keeps its bookmarks. Deleting a collection removes its embeds; deleting a view falls the embed back to the collection's default view.

Trust (phase 4)

Deleting a bookmark, page or collection now moves it to the owner's Trash. The snapshot is taken in the same transaction as the hard delete and includes intrinsic content plus owner-scoped links (tags, page links, collection memberships, page revisions). It deliberately excludes access grants: bookmark public flags, bookmark/tag shares and collection shares are never restored, so revoking access while an item is in the Trash cannot be undone by restoring it. Deleted bookmarks keep their existing delete endpoints; the UI and docs now call this “move to trash”.

Method	Path	Returns / behavior
GET	/api/trash	Owner's deleted items [{id,type,originalId,title,deletedAt}], newest first
POST	/api/trash/{id}/restore	Restores the item; 404 for another owner. Page restores recreate their history and append a new revision. Neither bookmark isPublic nor any share is restored
DELETE	/api/trash/{id}	Permanently removes one Trash entry (explicit purge)
GET	/api/export	Owner-scoped structured JSON archive: user, bookmarks, tags, pages (content + revisions), collections (properties, views, items, shares) and contacts. Credentials are never exported

Collections

Contextual workflows over existing bookmarks (phase 2 of the Notion-like upgrades). Collections are owner-scoped unless explicitly shared; membership references bookmarks without owning them — removing an item or a whole collection never touches the bookmark. An explicit CollectionShare gives a recipient read-only access to the collection and the narrowed bookmark projection for member bookmarks owned by the collection owner. A bookmark that the collection owner can only see through someone else's share is omitted, so collection sharing never passes a third-party grant onwards. Revoking the share or removing the item removes that access immediately, and mutations remain owner-only. Items whose bookmark the caller cannot see are omitted from lists/counts and behave as not-found for mutations; re-sharing restores the membership. Every mutating PATCH requires the expected version (400 missing, 409 stale). Indirect mutations advance revisions too (review CR-09): item reorder bumps every affected item's version, and property deletion bumps the versions of items whose value it dropped and views whose filter/sort definition it changed. Deletions are idempotent removals and take no revision — they never write state computed from a client snapshot.

Method	Path	Returns / behavior
GET	/api/collections	Owned and explicitly shared collections with shared, owner, _count.{items,properties,views}; item counts include only bookmarks the caller can see
POST	/api/collections	201 detail {...collection,properties:[],views:[default Table view]}; body {name,description?,icon?}
GET	/api/collections/{id}	Readable collection detail (owner or share recipient) plus ordered properties, views, authorized _count, shared; owner also gets sharedWith
PATCH	/api/collections/{id}	Updated collection; {version,name?,description?,icon?}, bumps version; owner only
DELETE	/api/collections/{id}	Moves the collection to Trash; memberships/properties/views cascade, bookmarks kept; owner only
POST	/api/collections/{id}/share	Owner only; {userIds:[...]} grants read-only access, idempotent
DELETE	/api/collections/{id}/share/{userId}	Owner only; revokes read-only access immediately
POST	/api/collections/{id}/properties	201 property; {name,type,config?}. Types: TEXT,NUMBER,SELECT,MULTI_SELECT,DATE,CHECKBOX,URL (RELATION reserved, rejected). SELECT config {options:[{label,color?}]} — the server assigns stable option ids; DATE config {mode:"date"|"datetime"}. Duplicate name → 409
PATCH	/api/collections/{id}/properties/{propertyId}	Updated property; {version,name?,position?,config?}. Type and date-mode changes are rejected (400) — conversion must never destroy values. Option updates send the full list: existing ids rename/recolor (identity preserved), omitted ids are removed but refused (400 with the using-item count) while any item still carries them
DELETE	/api/collections/{id}/properties/{propertyId}	{ok:true}; strips the property's values from all items and its clauses/sorts/grouping from saved views
GET	/api/collections/{id}/items?viewId=&cursor=&limit=	Items {...item,bookmark} (bookmark uses the permission-specific projection), visible bookmarks only, ≤limit (default/max 200) with X-Next-Cursor. With viewId: the view's filters (AND/OR over typed operator allowlists) and its FIRST sort key run server-side; ordering always tie-breaks on item id. Without viewId: canonical manual order (position,id)
POST	/api/collections/{id}/items	201 item; {bookmarkId,propertyValues?}. 400 if the bookmark is not currently accessible; duplicate membership → 409. Values are validated per property type; DATE values store canonically (YYYY-MM-DD or fixed-width UTC RFC3339) so comparisons never shift across timezones
PUT	/api/collections/{id}/items	{ok:true}; complete {order:[itemId,...]} permutation
PATCH	/api/collections/{id}/items/{itemId}	Updated item; {version,propertyValues?,position?}. propertyValues merges: omitted keys untouched, null removes a value, unknown property ids 400
DELETE	/api/collections/{id}/items/{itemId}	{ok:true}; membership only, bookmark untouched
POST	/api/collections/{id}/views	201 view; {name,type?,filters?,sorts?,groupByPropertyId?,displaySettings?}, types TABLE,BOARD,CALENDAR,LIST (default TABLE)
PATCH	/api/collections/{id}/views/{viewId}	Updated view; {version,name?,type?,position?,filters?,sorts?,groupByPropertyId?,displaySettings?}
DELETE	/api/collections/{id}/views/{viewId}	{ok:true}

Filter shape: {operator:"AND"|"OR",clauses:[{propertyId,op,value?}]} (max 20 clauses; no nested groups). Operator allowlists per type: TEXT/URL eq,ne,contains,empty,notEmpty; NUMBER/DATE eq,ne,gt,gte,lt,lte,empty, notEmpty; SELECT/CHECKBOX eq,ne,empty,notEmpty; MULTI_SELECT contains, empty,notEmpty. Sorts: max 3 {field,dir} where field is position, addedAt, title or a sortable property id (not multi-select); only the first drives server-side ordering/pagination in this phase. ne matches missing values (IS DISTINCT FROM). Property ids and values are bind parameters end to end — filter JSON never reaches SQL text. Collection sharing does not exist yet; views/counts can only expose what the owner can already see.

Signals and integrations

Method	Path	Returns / behavior
GET	/api/bookmarks/{id}/signals	{sources,signals,types}, newest 50 events
POST	/api/bookmarks/{id}/signals	201 watcher for {type:"email",config:{from?,subject?}}; {checked,created} for {action:"check"}
PATCH	/api/signal-sources/{id}	Updated watcher for {enabled:boolean}
DELETE	/api/signal-sources/{id}	{ok:true}
GET	/api/alerts/check	Undismissed bookmarks due within 15 minutes, soonest first
DELETE	/api/alerts/{bookmarkId}	{ok:true}; sets alertSent
GET	/api/contacts	Synced contacts with _count.bookmarks
POST	/api/contacts/sync	{synced,removed}; {nextcloudUrl,username,password,cardDavPath?}. Mirrors the configured address book: contacts previously imported from the SAME source URL that the server no longer returns are removed (removed), but only on a complete, non-empty snapshot — partial or empty responses never delete. Manually created contacts and other address books' imports are untouched; bookmarks keep working (contactId is SET NULL)
GET	/api/settings/imap	Configuration with masked password, or null
POST	/api/settings/imap	{ok:true}; {host,port?,tls?,username,password,folder?}; empty/masked password preserves an existing password. port must be 143 or 993, and TLS is required outside the test/LAN flags
POST	/api/imap/test	{ok:true} after real connection/login; same mailbox fields and port rules
GET	/api/imap/check	{matches:[{bookmarkId,title,from,externalId,occurredAt}]} for legacy watchers; if a search fails after finding matches, the partial matches are returned with an error field
GET	/api/shared-dates	Created/received dates with creator and recipient
POST	/api/shared-dates	201 array of created shares for {date,note?,recipientIds:[...]}
DELETE	/api/shared-dates/{id}	{ok:true}, creator only
GET	/api/users/search?q=...	Safe user projections; minimum two characters, maximum ten results

Email signals are deduplicated by source and Message-ID. Failed mailbox checks are recorded on lastStatus rather than reported as successful email matches; messages fetched before a partial failure are still persisted (the checkpoint does not advance, so the failed batch is retried and deduplicated). Sharing a tag or date exposes associated bookmarks read-only; direct-share revocation does not remove access independently granted by a tag/date share.

Administration

Always uses the real user, even while viewing another account.

Method	Path	Returns / behavior
GET	/api/admin/users	Safe user projections with bookmark/page/tag counts; excludes @example.com test users
PATCH	/api/admin/users	{ok:true} for {userId,role:"USER"|"ADMIN"}; refuses self-demotion
POST	/api/admin/view-as	{ok:true}; {userId} sets an eight-hour HttpOnly cookie, {userId:null} clears it

Route registration: internal/http/server.go. Only the client-owned OIDC login/callback remain stubs; application data routes use PostgreSQL.