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
| Route | Method | Feature | Purpose |
|---|---|---|---|
read | POST | files.read | Read 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 |
list | GET, POST | files.read | List a scope as a tree; GET takes its options from the query string so a folder view can be linked |
search | POST | files.search | Semantic / filter / grep, the same search_mode vocabulary as the tool |
write | POST | files.write | The twin of fs_write (same operation keys, plus id to address a pending node); a refusal answers 200 with ok:false |
upload | POST (multipart) | files.write | Upload 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 |
raw | GET | files.read | Stream 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 |
events | GET (SSE) | files.read | Per-project filesystem event stream, plus a content-free pending:changed signal |
pending | GET, POST | files.read; mutating verbs files.write | The review queue: list (paged with cursor, count_only, include_orphans), preview, revert, discard, dismiss, scan-orphans, discard-orphans |
approve | POST | files.write | Confirm 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
| Route | Method | Feature | Purpose |
|---|---|---|---|
git/status · branch · diff · log · log-stats · show · commit · outgoing · repos | GET | files.read | Change-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 · restore | POST | files.write + write policy | Stage and commit; a destructive op returns a rescue point that restore undoes |
git/fetch · pull · push | POST | files.write + exec policy | Remote operations with the caller's own connected token (Connecting a git remote) |
Index health
| Route | Method | Feature | Purpose |
|---|---|---|---|
health · health/scan | GET, POST | files.read | Cheap count stats; the on-demand orphan/duplicate scan |
health/gc | POST only | files.write | gc, 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-uris | GET | files.write | The most-rewritten files in the last hour, filtered to what the caller may read |
health/collection | GET, POST | platform.vector.maintain | Collection 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
| Route | Method | Feature | Purpose |
|---|---|---|---|
sources · sources/<slug> | GET | files.read | List sources, or one source's public config (description and the resolved description_effective) |
sources | POST, PATCH, DELETE | sources.mount | Create, 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/schema | GET | files.read | Connector kinds and their config schemas, by registry kind (host, brain, webtop) |
sources/discoverable · sources/browse | GET | sources.mount (privileged zones also sources.privileged) | Unattached roots to suggest; one directory level at a time |
sources/health | GET | files.read | Sync-status rows for the sources the caller can see |
sources/preflight | POST | sources.mount | Validate and authorize a create body without writing |
sources/enabled | POST | sources.mount | Toggle a source live / disabled ('auto' is machine-only) |
sources/sync · sources/reindex | POST | sources.sync | Sync, rescan, or a scoped re-embed (force: true) / its estimate (estimate: true); 202 + the queued job |
sources/cancel · sources/reset · sources/sync-status | POST, GET | sources.sync | Cancel 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
| Route | Method | Feature | Purpose |
|---|---|---|---|
policies/uri/manifests | GET | files.read | The per-package uriPolicies baselines resolved at boot |
policies/uri/<source> | GET | files.read | A source's effective merged path permissions |
policies/uri | POST | sources.policy | Patch 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 asuri_policy_deniedfirst, so the 404 is whatlistreturns, and whatwriteanduploadreturn for a URI with no scheme;readreports 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.