API routes

The host exposes ~40 route plugins under /api/v1/. This page is a hand-curated catalog; the auto-generated OpenAPI / Scalar reference is scheduled for v0.2.

Note

Every route except /health, /api/v1/health, /api/v1/version, and /api/v1/workspaces requires an x-workspace-id: <uuid> header. The middleware looks up the workspace, sets a Postgres session variable for RLS, and returns 400/404 if the header is missing or invalid.

Health + version

Method	Path	Notes
GET	/health	Bare liveness, no /api prefix
GET	/api/v1/health	Liveness + version + echoed workspace id
GET	/api/v1/version	Full build metadata: { version, channel, commit, built_at, node_version }

First-run setup

Method	Path	Notes
GET	/api/v1/setup/status	Setup wizard health checks
POST	/api/v1/setup/complete	Mark wizard done. Idempotent
GET	/api/v1/workspace/stats	Counts for empty-state displays

Workspaces

Method	Path	Notes
GET	/api/v1/workspaces	List workspaces (exempt from middleware)
GET	/api/v1/workspace-settings	Per-workspace config
PUT	/api/v1/workspace-settings	Update settings

Daily notes + folios

Method	Path	Notes
GET	/api/v1/daily-notes/:date	Read a date’s notes
POST	/api/v1/daily-notes/inject	Inject a logCard. Honors Idempotency-Key header
GET	/api/v1/folios	List folios with AI summary
GET	/api/v1/folios/:id	Get one folio
POST	/api/v1/folios/:id/synthesize	Manual synthesis trigger
GET	/api/v1/folios/:id/entries	Walk logCards belonging to a folio
PATCH	/api/v1/folios/:id	Update folio metadata + readme

Knowledge graph

Method	Path	Notes
GET	/api/v1/entities	List entities (filter: ?canonical=true)
GET	/api/v1/entities/:id	Get one entity
POST	/api/v1/entities	Create canonical entity
PATCH	/api/v1/entities/:id	Update entity (e.g. set concept_role)
GET	/api/v1/engine/entities	Fuzzy search
GET	/api/v1/curation/suggestions	Pending curator proposals
POST	`/api/v1/curation/suggestions/:id/accept	reject

Connectors + integrations

Method	Path	Notes
GET	/api/v1/connectors	List connector manifests (`?tier=core
GET	/api/v1/connectors/:name/schema	One manifest
`GET	POST	PUT
`GET	PUT	DELETE`
`GET	GET	PUT
POST	`/api/v1/auth/github/device/start	poll`
DELETE	/api/v1/auth/github	Disconnect GitHub
GET	/api/v1/auth/google	Google OAuth start
GET	/api/v1/auth/google/callback	Google OAuth callback

Edge harvesters

Method	Path	Notes
GET	/api/v1/harvester-devices	List paired devices
POST	/api/v1/harvester-devices/pairing-codes	Mint a pairing code
POST	/api/v1/harvester-devices/claim	Exchange code for token (returns plaintext once)
DELETE	/api/v1/harvester-devices/:id	Soft-revoke
POST	/api/v1/granola/sync	Granola edge push

Agents + chat

Method	Path	Notes
POST	/api/v1/agent/message	Synchronous agent message
POST	/api/v1/chat/stream	SSE streaming chat
POST	/api/v1/agent-tasks	Dispatch an agentic flow (INSTRUCT)
GET	/api/v1/agent-tasks/:id	Poll an agent task
POST	/api/v1/agent-tasks/:id/cancel	Best-effort cancel
GET	/api/v1/agent-tasks/:id/events	SSE fan-out
GET	/api/v1/agent-runtime/status	Provider availability

MCP server

Method	Path	Notes
GET	/mcp/sse	Establish SSE stream
POST	/mcp/messages?sessionId=<id>	Send JSON-RPC messages

See MCP tools for the tool catalog.

Imports + artifacts

Method	Path	Notes
POST	/api/v1/imports	Upload notes-app archive (multipart, 500 MB cap)
GET	/api/v1/imports/:id	Poll import progress
POST	/api/v1/imports/:id/commit	Commit with routing
GET	/api/v1/artifacts/:id	Read an artifact body

Webhooks

Method	Path	Notes
POST	/api/v1/webhooks/:channel	Inbound webhook (Slack, Telegram, Matrix, etc.). HMAC-verified. Exempt from workspace middleware

SOUL.md

Method	Path	Notes
GET	/api/v1/soul-profile	Read the per-workspace owner profile
PUT	/api/v1/soul-profile	Overwrite
POST	`/api/v1/soul-profile/ensure	reset`

For the canonical, always-current list, grep src/server.ts for server.register(.