API v1
Overview
The two ways to call the API — type-safe RPC and generated REST.
The server exposes the same router two ways. Pick the one that fits your caller.
RPC client (TypeScript)
Full type inference, no codegen. The way the web and terminal clients call it.
REST & OpenAPI
A generated HTTP surface with an interactive reference — for anything not written in TypeScript.
The surfaces
| Path | Surface |
|---|---|
/rpc | Type-safe oRPC endpoint the clients call. |
/v1 | Generated OpenAPI document + interactive reference. |
/api/auth/* | Better Auth routes (sign-in, session, organization, etc.). |
/health | Deep health check (verifies the database). |
Both /rpc and /v1 are generated from one router definition, so
they never drift. See API & oRPC for how that works.
Router map
The top-level routers, each in its own module under packages/api/src/routers:
| Router | Responsibility |
|---|---|
spaces | Create and manage spaces. |
spaceMembers | Space membership and roles (myRole). |
pages | Page CRUD, lifecycle, tree, drafts, revisions. |
pageAccess | Per-page ACLs (get, setVisibility, members). |
comments | Create, resolve, moderate comments. |
tags | Tag CRUD and assignment. |
attachments | Upload and delete attachments. |
links | Internal link / backlink tracking. |
activity | Activity feed / audit stream. |
search | Full-text search. |
me | Per-user state (favorites, subscriptions). |
onboarding | First-run org creation and sample seeding. |
dashboard | Aggregated home-screen data. |
health | Liveness probe. |
Authorization
Every non-public procedure is gated. Organization capabilities use
requireOrgPermission / assertOrgPermission; content actions use space/page
capabilities. See Permissions.