@brain-core

Routes

brain-core's HTTP routes under /api/packages/brain-core — filesystem, git, health, source management and URI policy — grouped by the feature that gates them.

Every route is served at /api/packages/brain-core/<pattern> and discovered by the package-system route dispatcher, which enforces the declared feature against the caller's grants before the handler runs. The handler then takes the project and agent from the verified session — a projectId in the body or query that disagrees with it is a 403. The workspace UI and skill scripts (through the per-stream session ticket and neuralis request) call these routes; the model calls the fs_* tools, which carry the same gates. Other native packages call brain-core's typed package API directly, never over HTTP or MCP.

Several modules guarantee only files.read and re-check a stronger feature in the handler for their mutating verbs; the tables name the feature that actually decides.

Filesystem

RouteMethodFeaturePurpose
readPOSTfiles.readRead files[] (URI strings or {uri, line_start?, line_end?}) with the fs_read options; every entry is path-policy checked first, failures ride a 200 per file
listGET, POSTfiles.readList a scope as a tree; GET takes its options from the query string so a folder view can be linked
searchPOSTfiles.searchSemantic / filter / grep, the same search_mode vocabulary as the tool
writePOSTfiles.writeThe twin of fs_write (same operation keys, plus id to address a pending node); a refusal answers 200 with ok:false
uploadPOST (multipart)files.writeUpload bytes, and the Files widget's "New File"; never overwrites (lands as name (2).ext), answers indexed, and refuses a target whose content may not be read before writing any bytes
rawGETfiles.readStream raw bytes; images (not SVG), video, audio, PDF, text and JSON inline, the executable document class (SVG, HTML, XHTML, XML, +xml) always as an attachment
eventsGET (SSE)files.readPer-project filesystem event stream, plus a content-free pending:changed signal
pendingGET, POSTfiles.read; mutating verbs files.writeThe review queue: list (paged with cursor, count_only, include_orphans), preview, revert, discard, dismiss, scan-orphans, discard-orphans
approvePOSTfiles.writeConfirm a pending change against its fresh preview fingerprint

Approve, revert and dismiss carry the expectedFingerprint from a fresh preview; a state that needs acknowledgement additionally needs acknowledgeCurrentState:true, which grants no permission. Freshness, tenant, owner, source scope and READ/WRITE policy run again at apply.

Git

RouteMethodFeaturePurpose
git/status · branch · diff · log · log-stats · show · commit · outgoing · reposGETfiles.readChange-set, branches, diffs, paged history, per-commit line totals, file content at a revision, a commit's files, the unpushed file list, the repositories in a source
git/stage · unstage · discard · commit · branch · checkout · restorePOSTfiles.write + write policyStage and commit; a destructive op returns a rescue point that restore undoes
git/fetch · pull · pushPOSTfiles.write + exec policyRemote operations with the caller's own connected token (Connecting a git remote)

Index health

RouteMethodFeaturePurpose
health · health/scanGET, POSTfiles.readCheap count stats; the on-demand orphan/duplicate scan
health/gcPOST onlyfiles.writegc, repair-orphans, repair-pending or the read-only deduplicate; dryRun defaults to false, a concurrent pass answers 409 action_in_progress, GET answers 405
health/hot-urisGETfiles.writeThe most-rewritten files in the last hour, filtered to what the caller may read
health/collectionGET, POSTplatform.vector.maintainCollection maintenance and the embedding-model rebuild (rebuild-estimate, rebuild-generation, rebuild-cancel; the first two answer 409 embedding_disabled while embedding is off)

Source management

RouteMethodFeaturePurpose
sources · sources/<slug>GETfiles.readList sources, or one source's public config (description and the resolved description_effective)
sourcesPOST, PATCH, DELETEsources.mountCreate, update, remove. PATCH preserves an omitted sync (pass clearSync: true to disable indexing) but replaces permissions wholesale — round-trip the current object. DELETE sources/<slug> takes ?purge=1
sources/kinds · sources/kinds/:kind/schemaGETfiles.readConnector kinds and their config schemas, by registry kind (host, brain, webtop)
sources/discoverable · sources/browseGETsources.mount (privileged zones also sources.privileged)Unattached roots to suggest; one directory level at a time
sources/healthGETfiles.readSync-status rows for the sources the caller can see
sources/preflightPOSTsources.mountValidate and authorize a create body without writing
sources/enabledPOSTsources.mountToggle a source live / disabled ('auto' is machine-only)
sources/sync · sources/reindexPOSTsources.syncSync, rescan, or a scoped re-embed (force: true) / its estimate (estimate: true); 202 + the queued job
sources/cancel · sources/reset · sources/sync-statusPOST, GETsources.syncCancel a job, forget sync state (deletes no file and no vector), read the queue

Two fields escalate beyond sources.mount on create and update: a privileged root (the platform app zone, the Neuralis source tree, the whole host) also requires sources.privileged, and packageFolders — the folders of a source that load as package code — requires owner/admin strength, resolved from the role's priority rather than its name. A root on a paired device is the exception to both: only that device's owner attaches or edits it, and device.own alone admits them. A mutation on another user's or agent's source also needs files.writeOthers (reading it, files.readOthers).

URI policy

RouteMethodFeaturePurpose
policies/uri/manifestsGETfiles.readThe per-package uriPolicies baselines resolved at boot
policies/uri/<source>GETfiles.readA source's effective merged path permissions
policies/uriPOSTsources.policyPatch path rules (source, addPaths / removePatterns); editing another user's or agent's source is also a write on that scope

A caller cannot add a non-removable rule (only a trusted manifest declares one), and removing one answers 409 immutable_policy_floor. The rule semantics are on URI policies.

Refusals

The read, write, upload, raw, search and git/* routes check the URI policy inside the handler, before the filesystem is touched:

  • a denied path: 403 { code: 'uri_policy_denied', capability, uri };
  • a disabled source: 409 { code: 'source_disabled', source, scope, nextStep: 'enable_source' };
  • a slug the project has no config for: 404 { code: 'source_not_configured', retryable: false, nextStep: 'check_configured_sources', availableSources } — the caller's own visible sources, so a wrong guess is fixable in one round trip. The in-handler guard denies an unconfigured source as uri_policy_denied first, so the 404 is what list returns, and what write and upload return for a URI with no scheme; read reports per file inside a 200.

While the vector store is not available, every route that needs the index answers 503 { error: 'vector_store_unavailable', message, reason, retryable } at once — never an opaque 500 and never a wait; write keeps its 200 { ok: false, code: 'vector_store_unavailable' } shape. Files on folder sources keep serving: read, raw, list, pending changes, grep search and git/* work, and a new file still lands (it is indexed when the store is back). A brain:// file, semantic and filter search, an edit, move or delete of an existing file and the pending-review verbs wait for the store; a held sync runs by itself when it returns.

Connectors never enforce policy themselves: every gate sits above them, which is why a route is the safe way in and a raw connector call is not.

On this page