# Routes (https://docs.neuralisapp.com/brain-core/routes)

Every route is served at `/api/packages/brain-core/<pattern>` and discovered by
the package-system [route dispatcher](https://docs.neuralisapp.com/package-system/routes.md), 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](https://docs.neuralisapp.com/package-system/sessions.md) — 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](https://docs.neuralisapp.com/brain-core/tools.md), 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 [#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 [#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](https://docs.neuralisapp.com/brain-core/app-surfaces.md#connecting-a-git-remote)) |

## Index health [#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 [#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 [#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](https://docs.neuralisapp.com/package-system/uri-policies.md).

## Refusals [#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.
