API Reference
API Overview
Headless API reference for Nous-OSS
API Overview
Nous exposes two headless API surfaces:
- tRPC for first-party web and CLI clients
- Public MCP over Streamable HTTP for approved external clients
Both surfaces are thin adapters over the same canonical runtime. tRPC owns first-party procedure routing; the public MCP edge owns machine-to-machine discovery and admission. Neither creates a second business-logic stack.
tRPC
Base URL
- Development:
http://localhost:4317 - Route:
/api/trpc
Transport
- Queries and mutations — HTTP (batched)
- Subscriptions — WebSocket (Phase 1: not implemented; streaming deferred to Phase 2+)
Authentication
When NOUS_BASIC_AUTH is set, include the Authorization: Basic header. The tRPC client adds it automatically when the env var is present.
Routers
| Router | Purpose |
|---|---|
projects | Project CRUD, workflow authoring, visual debugging, dashboard, and governed project configuration |
chat | Send messages, get history |
traces | Execution traces |
memory | Memory entries, export, delete |
packages | Canonical app-install/settings preparation, governed app install/settings save, and active app-panel projection |
preferences | Vault-backed provider keys, available models, model selection persistence, and system status |
config | Configuration get/update |
health | System health check, status snapshots, provider health, and agent status |
firstRun | First-run flow status and completion |
witness | Witness verification reports, checkpoints, and key-epoch operations |
See Procedures for the full reference.
Public MCP
The public MCP edge is hosted by the web app and exposed at the canonical /mcp route.
Endpoints
- Transport:
POST /mcp - Protected Resource Metadata:
GET /.well-known/oauth-protected-resource/mcp - Authorization Server Metadata:
GET /.well-known/oauth-authorization-server/mcp
Authentication and admission
/mcprequires OAuth bearer posture before any tool mapping, namespace bootstrap, or shared handler execution- Admission validates request schema, token posture, audience, origin, and scopes at the boundary
- External callers are represented as
ExternalClientsubjects only at the public boundary; internal agent classes are unchanged
See Public MCP Edge for the machine-facing reference.