REST API

REST API

Hono, in packages/api. The SPA and API share one origin (no CORS); data routes live under /api. The app is built pure (no listen) so tests drive it with app.request(). Route types are exported as a chained sub-app for a typed RPC client.

Auth and errors

/api/* is guarded (session or bearer); see Authentication and Users. GET requests under the admin routes are open to any authenticated user; mutations require the admin role.

A single error boundary maps known failure shapes to status codes instead of leaking a 500:

Shape	Status
AppError not_found	404
AppError conflict (for example a version conflict)	409
AppError bad_input, zod validation, malformed JSON	400
unauthenticated / unauthorized	401
member hitting an admin mutation	403
anything else	500 (logged)

Endpoints

Public

Method	Path	Purpose
GET	/health	DB ping; 503 if the DB is unreachable.
GET	/auth/config	Which of wizard / password form / SSO the SPA should show.
GET	/api/setup/status	{ bootstrapped }.
POST	/api/setup	First-run bootstrap; self-disables once an admin exists.
GET	/auth/me	Current identity (or 401).
GET	/auth/login / /auth/callback / /auth/logout	OIDC flow and logout.
POST	/auth/password/login	Email plus password; sets the session cookie.

Knowledge and reference

Method	Path	Purpose
POST	/api/work-items/:source/:id/fetch	Fetch and store a raw work item.
GET	/api/knowledge/search?q=	Hybrid search.
GET / POST	/api/knowledge	List / create an entry.
GET / PATCH	/api/knowledge/:id	Fetch / patch (optimistic locking).
GET / POST	/api/knowledge/:id/feedback	List / add feedback.
GET	/api/reference, /api/reference/search, /api/reference/:id	Reference docs.
GET / POST	/api/analysis-runs	Audit runs.

Agent (SSE)

Method	Path	Purpose
POST	/api/agent/chat	Streamed agent turn (SSE: start, text, tool_use, approval_request, approval_resolved, result, error).
POST	/api/agent/approve	Resolve a pending write approval.
POST	/api/agent/uploads	Stage a document upload for the agent to ingest.

Admin (mutations require admin role)

Method	Path	Purpose
GET / POST	/api/users, PATCH /api/users/:id	User management.
GET / PUT	/api/users/team-members/:teamSlug	Team membership.
GET	/api/system	Effective settings plus read-only env facts (no secret values).
PUT	/api/settings/:key	Update a runtime setting.
GET / POST	/api/resolution-patterns	Resolution-pattern vocabulary.
GET / POST	/api/products/:slug/components	Per-product component glossary.
GET / POST	/api/products/:slug/labels	Per-product label vocabulary.
GET / POST	/api/customers	Customers.
GET / POST	/api/teams, /api/products	Org structure.
GET / POST	/api/source-connections, .../:slug/product-map	Source config and routing.

Request bodies are validated with zod. This list tracks the routes in packages/api/src; that source is authoritative.