# Routes (https://docs.neuralisapp.com/admin/routes)

`@neuralis/admin` has no tools and no commands. Its programmatic surface is
the set of feature-gated HTTP routes discovered from `src/routes/` (25 route
files), served under `/api/packages/@neuralis/admin/<pattern>`. The Admin
widget, the [admin skills](https://docs.neuralisapp.com/admin/skills.md) and the `neuralis request` CLI all
call the same routes, so one gate decides for every caller.

Each route reads the user, project and agent from the verified session, never
from the request. Most routes act on the **session's** project and refuse to
fan out when the session has none (`sources`, for example, answers `400`). The
feature tiers are explained on [Features](https://docs.neuralisapp.com/admin/features.md); the general route
mechanism is on [package-system Routes](https://docs.neuralisapp.com/package-system/routes.md).

## Reading [#reading]

| Pattern | Method | Feature | Returns |
| --- | --- | --- | --- |
| `health` | GET | `project.dashboard` | Vector store probe, disk, memory, configured LLM providers (read from the credential store, never from environment variables) |
| `dashboard/stats` | GET | `project.dashboard` | KPIs: users, projects, agents, packages, connectors, MCP servers, streams, today's usage |
| `dashboard/usage` | GET | `project.dashboard` | The usage series (see below) |
| `dashboard/codex-savings` | GET | `project.dashboard` | Codex subscription savings per connected subscription; `scope=platform` needs `platform.projects` and `platform.users` |
| `dashboard/pricing-basis` | GET | `project.dashboard` | The one sentence that says what every money figure means |
| `packages`, `streams` | GET | `project.dashboard` | Loaded packages; active agent streams of the session project |
| `projects`, `projects/:id` | GET | `project.dashboard` | Your projects and one project's detail, reduced field by field by feature; `404` for a project you do not belong to unless you hold `platform.projects` |
| `users` | GET | `project.members` | A discovery pointer to the host's user API (`{ href, mutable: false }`), not a user list |
| `presence` | GET | `project.members` | Who is online and on which kinds of client; `scope=platform` also needs `platform.users`. Held in memory only |
| `audit` | GET | `platform.audit` | Recent platform audit events |
| `logs`, `logs/sources` | GET | `project.audit` | The log reader; every platform-rooted source also needs `platform.audit`, and another member's run log needs `platform.scope`. Paths are display keys, never host paths |
| `config/roles` | GET | `project.roles` | This project's role map |
| `config` | GET | `platform.config` | Platform settings: environment-derived rows read-only, file-backed rows editable |
| `updates` | GET | `platform.config` | The installed release and the last release check, from its cached result |
| `endpoints/llm`, `endpoints/embedding` | GET | `platform.config` | The custom endpoint lists (never a key) |
| `sources` | GET | `project.sources` | Source configurations with live health |
| `vector/status` | GET | `platform.vector` | Target model, active model, serving collection, vector database and embedding host probes |
| `vector/collection` | GET | `platform.vector` + `platform.vector.maintain` | Brain-core's collection report: point counts, rebuild progress, today's embedding spend |
| `credentials` | GET | `project.credentials` | The scope-aware catalog with a `hasValue` flag per scope |
| `credentials/scope-targets` | GET | `platform.scope` | The users and agents the scope picker may target (ids and names only) |
| `credentials/use` | GET | `platform.scope` | The platform-wide per-credential call ceilings and their usage |
| `project-packages`, `project-packages/quarantine` | GET | `packages.manage` | The session project's packages with trust, state and gating feature; tools withheld from an agent's catalog (`?scope=platform` also needs `platform.projects`) |
| `platform-packages` | GET | `platform.packages` | Every package the host knows, pending requests, and whether a restart applies them |
| `canvas/graph`, `canvas/agent/:id`, `canvas/user/:id` | GET | `project.canvas` | The organization graph and per-entity detail; a non-member's detail needs `platform.users`, `lastActivity` needs `platform.audit` |
| `invite-links` | GET | `project.members.invite` | Pending invite links of the session project, never a link's secret |

## Changing [#changing]

| Pattern | Method | Feature | Effect |
| --- | --- | --- | --- |
| `config` | PATCH | `platform.config` | One runtime setting. An unknown embedding model answers `400`; the endpoint lists are written only through `endpoints/*` |
| `config/embedding-target` | PATCH | `platform.config` | The embedding target model and dimension, validated together. It starts nothing |
| `endpoints/llm`, `endpoints/embedding` | PUT | `platform.config`, a signed-in person only | Replace the whole list. Removing an embedding endpoint in use answers `409 endpoint_in_use` with nothing written |
| `endpoints/probe` | POST | `platform.config` | Ask whether an LLM endpoint answers and with which models |
| `config/roles` | PATCH | `project.roles` + the role-management flag | Replace the project's role map (see the rules below) |
| `sources` | PATCH | `project.sources` | A source's permissions, sync settings or description, through brain-core's one validated writer |
| `vector/reset` | POST | `platform.vector.reset` | Drop every vector collection and the embedding lock; needs `confirm: "RESET"`. `brain://` content and its history go with them |
| `vector/collection` | POST | `platform.vector` + `platform.vector.maintain` | `rebuild-estimate`, `rebuild-generation` (`202`) or `rebuild-cancel`; a conflicting state answers `409` |
| `cache/clear`, `rescan` | POST | `packages.manage` | Drop the project's package caches; re-scan its `_packages/` and source package folders and report `packageErrors[]` |
| `project-packages/trust`, `/build`, `/access-feature` | PUT · POST · PUT | `packages.manage` | Pin a dropped package's trust, build a WASM package, or attach the feature a role needs to see a package. A native package's trust never changes |
| `credentials/:id` | PUT · DELETE | `project.credentials.write` | Set or delete a value at your own scope; another scope also needs `platform.scope`. 10 changes per minute per caller, audited without the value |
| `credentials/use/:id` | PATCH | `platform.scope` + `project.credentials.write` | Set or clear one credential's call ceiling. LLM provider keys are refused; spend limits govern them |
| `platform-packages`, `…/requests/:id/approve`, `…/requests/:id`, `…/restart` | POST · POST · DELETE · POST | `platform.packages`; approve and restart also `platform.packages.approve` | Ask for an install, update or removal (staged, nothing runs), approve it by its sha512, dismiss it, or restart the host |
| `members-invite` | POST | `project.members.invite` + the invite flag | Invite a new user. No password travels either way; the first one is set by a reset in the Users tab |
| `invite-links`, `invite-links/:id` | POST · DELETE | `project.members.invite` + the invite flag | Issue a one-time link for one email and role, or revoke one. It expires after `inviteLinkTtlHours` (default 168) |
| `projects-create` | POST | `platform.projects.create` + owner strength | Create a project; owner strength is checked before the instance capacity |
| `agents-assign` | POST | `project.agents.assign` + the role-management flag | Assign or unassign an agent to a member (who may manage it; who may use it is the Agents tab's attach) |
| `agents-admin/:id` | DELETE | `core.agents` + agent-core's per-agent check | Delete a project agent; the route adds transport and an audit row, never authority |

## Rules every caller meets [#rules-every-caller-meets]

- **Whole-object bodies.** `config/roles` replaces the whole role map, so a
  role left out is a deletion and is authorized as one. `sources` replaces the
  whole `permissions` object (sync settings merge key by key). Read first, edit,
  send everything back; a partial body answers `200` and drops what it omitted.
- **Role edits.** You may edit only roles strictly weaker than your own, never
  your own role, and grant or revoke only features you hold. Built-in
  priorities are fixed; every priority is an integer in `1..99`.
- **Immutable source rules.** A source rule the package declared immutable
  survives every PATCH: a body that drops or alters one answers `409` and
  nothing is written.
- **Uniform refusals.** An unknown role and a too-strong role, an unknown agent
  and a non-member, a missing agent and a denied delete each answer the same
  `403`, so a refusal reveals nothing.

## The usage series [#the-usage-series]

`GET dashboard/usage` takes `range` (`24h`, `7d`, `30d` or `all`), `groupBy`
(`model`, `agent`, `user` or `project`) and `scope` (`project` or `platform`).
`scope=project` always means the session's project. Buckets are computed on the
server; one usage row is one model's share of a turn. The response carries the
same pricing-basis sentence as `dashboard/pricing-basis`: figures are estimates
from the model catalog's list rates, and a model the catalog does not price
records `$0`.

## Reaching other packages [#reaching-other-packages]

Data from other packages (streams, connectors, MCP servers, usage, source
health) is read through their typed package APIs, never through internal MCP
calls; the pattern is described on [package-system Routes](https://docs.neuralisapp.com/package-system/routes.md).
