REST overview
Conventions
- Most
/api/*handlers expectrequireSessionUser(or tighter helpers) fromserver/utils/auth.ts. - Agent routes embed
[id]and additionally check membership/ownership per operation. - JSON APIs should return JSON; an HTML document with HTTP 200 on an
/api/*path often means the SPA router intercepted the request (bad base URL or mis-proxy).
Groups
| Prefix | Purpose |
|---|---|
/api/auth/* | Magic link, MFA, logout, WebSocket tickets |
/api/users/me/* | Session user utilities |
/api/agents/* | Agents, members, invites, keys, services, connections, join, onboarding helpers |
/api/agents/:id/policies/* | Policy CRUD, preview, simulate, versions |
/api/agents/:id/sessions/* | Tool/session inspection and resets |
/api/agents/:id/entities/* | Harvested entities for policy UX (GitHub today) |
/api/agents/:id/preview | Agent preview helpers |
/api/audit/* | Audit streams/exports |
/api/dashboard/* | Aggregated stats |
/api/tools/catalog | Tool listing |
/api/connectors/meta | Connector metadata |
/api/github/*, /api/github-app/* | GitHub App UX + provisioning |
/api/status | Simple OK JSON |
/api/mcp/mock-call | Session-gated MCP exercise endpoint |
MCP and discovery
- Proxy JSON-RPC:
/mcp/...(server/routes/mcp/[...].ts) with Bearer proxy keys. - OAuth authorization-server metadata may be exposed under
.well-known/when enabled.
Other routes (not under /api)
GET /alive— minimal liveness JSON (server/routes/alive.get.ts).
See Health endpoints.