API routes

The host exposes ~113 route plugins, almost all under /api/v1/. This page is a hand-curated catalog grouped by area — not an exhaustive endpoint-by-endpoint dump. An auto-generated OpenAPI spec covering every endpoint is on the roadmap.

Note

Most /api/ routes require 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.

A handful of routes are exempt because they run before a workspace id is known or authenticate another way: bare /health and other non-/api routes (the MCP surface, static SPA assets), /api/v1/health, /api/v1/version, /api/v1/auth/bootstrap (which may name one default workspace but never enumerates), the inbound webhook routes (/api/v1/webhooks/*, HMAC-verified), the OAuth callbacks (they recover the workspace from the OAuth state parameter), and the activity SSE stream (it reads ?workspace_id= inside the handler).

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	Build metadata: { version, channel, commit, built_at, node_version }

First-run setup

Method	Path	Notes
GET	/api/v1/setup/status	Setup wizard health checks + next_step
POST	/api/v1/setup/complete	Mark wizard done. Idempotent
GET	/api/v1/workspace/stats	Counts for empty-state displays
GET	/api/v1/dashboard/overview	Single-round-trip dashboard snapshot (totals, activity, attention list)

See First-run setup for the wizard flow.

Workspaces + settings

Method	Path	Notes
GET	/api/v1/workspaces	The caller’s own workspace only — one row, never a directory. Discovery before you hold anything is GET /api/v1/auth/bootstrap.
GET	/api/v1/workspace-settings	Per-workspace config
PUT	/api/v1/workspace-settings	Update settings

Daily notes

Method	Path	Notes
GET	/api/v1/daily-notes/:date	Read a date’s notes
GET	/api/v1/daily-notes/:date/text	Plain-text rendering
POST	/api/v1/daily-notes/inject	Inject a logCard. Honors Idempotency-Key header
GET	/api/v1/tags	Workspace tag set (server-extracted #hashtags)

Folios

Folios are the unified narrative substrate: plain collections plus the engine-maintained taste / domain / project textures.

Method	Path	Notes
GET	/api/v1/folios	List folios (all kinds) with AI summary
GET	/api/v1/folios/overview	Cross-folio overview
GET	/api/v1/folios/:id	Get one folio (includes backfill_status, pinned_count)
GET	/api/v1/folios/:id/read	Read folio with members + source openers
POST	/api/v1/folios/:id	Create / update folio metadata
GET	/api/v1/folios/:id/entries	Walk logCards belonging to a folio
GET	/api/v1/folios/:id/members	List members (pinned + auto)
POST	/api/v1/folios/:id/members	Pin an artifact to the folio
DELETE	/api/v1/folios/:id/members/:memberId	Unpin a member
POST	/api/v1/folios/:id/backfill	Trigger a texture backfill (engine folios only)
GET|PUT|DELETE	/api/v1/folios/:id/sources	Link a folio to an upstream source (repo, label, calendar, drive folder)
POST	/api/v1/folios/:id/visual-fit	Run vision-judged photo membership

Knowledge graph + curation

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
GET	/api/v1/engine/entities	Fuzzy entity search
GET	/api/v1/edges	List typed edges (each carries source_kind + confidence)
GET	/api/v1/curation/suggestions	Pending curator proposals
POST	/api/v1/curation/suggestions/:id/{accept,reject,silence,run-agent}	Resolve a suggestion
POST	/api/v1/curation/re-triage	Re-run triage over open suggestions

See Knowledge graph for the model.

Connectors + integrations

Method	Path	Notes
GET	/api/v1/connectors	List connector manifests (?tier=core|community)
GET	/api/v1/connectors/:name/schema	One manifest
GET	/api/v1/connectors/:name/policy	Compiled streaming-policy + ETag
GET|POST|PUT|DELETE	/api/v1/integrations	CRUD for integrations
PATCH	/api/v1/integrations/:id	Per-integration retention cap update
GET	/api/v1/app-sources	List paired application sources, their status, granted scopes, and Host permission flags; credentials are never returned
POST	/api/v1/app-sources/pair	Exchange a pasted App Source Protocol pairing bundle; indexing, entity extraction, and visual hydration start disabled
PATCH	/api/v1/app-sources/:id	Update semantic-indexing, entity-extraction, or visual-hydration permission flags
POST	/api/v1/app-sources/:id/rotate	Rotate the scoped source credential, revoking the old credential only after replacement succeeds
POST	/api/v1/app-sources/:id/revoke	Revoke the remote source credential and stop local work
DELETE	/api/v1/app-sources/:id	Disconnect locally while retaining credential and resource provenance for audit
GET|PUT|DELETE	/api/v1/sync-rules/:name	Per-integration sync config
POST	/api/v1/sync-rules/:name/preview	Dry-run a rule against existing data
POST	/api/v1/sync-rules/:name/apply-retroactive	Apply retention caps to existing artifacts (HMAC-gated, idempotent)
GET|PUT|DELETE	/api/v1/oauth-apps	OAuth client credentials (encrypted at rest, never .env)
GET	/api/v1/auth/hosted/providers	Hosted provider availability for the linked workspace and its entitlement
POST	/api/v1/auth/google/hosted/start	Start hosted Google consent; optional { account_id } binds re-authentication to the selected existing account
POST	/api/v1/auth/google/hosted/poll	Advance the hosted connection and claim its delivery; optional ?connection_id= selects the start result
GET	/api/v1/auth/google/hosted/status	Read the durable connection verdict without claiming a delivery; optional ?connection_id=

OAuth + connect flows live under /api/v1/auth/<provider> (Google, GitHub device flow, Strava, Spotify, Tidal, Beeper, Linear, Readwise, Reddit, Last.fm, Peloton, Whoop). Each provider exposes start/callback/status/disconnect routes as applicable; callbacks recover the workspace from the OAuth state parameter. See Connectors.

Edge harvesters + sync

Native macOS sources push through paired-device routes. See 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/apple-notes/sync	Apple Notes edge push
POST	/api/v1/safari/sync	Safari reading list + history edge push
POST	/api/v1/imessage/sync	iMessage edge push
POST	/api/v1/ai-sessions/sync	AI coding-session capture (default-off)
POST	/api/v1/streams/:connector/events	Streaming push endpoint

Agents + chat

POST /api/v1/agent/message is the single canonical chat contract for every client (iOS, macOS, CLI). It accepts prompt or question plus optional session_id / active_folio_id / model / stream, and returns gateway frames as SSE (or a non-streaming JSON body).

Chat is multi-engine, resolved per workspace from chat_runtime:

• openclaw — the premium default, routed through the OpenClaw Gateway.
• host_native — the OSS chat floor: an in-process tool loop against the workspace’s configured model, no gateway required, grounded by a retrieval whitelist; it can also load the host’s MCP write tools on demand when you ask it to write (opt down with CARABASE_CHAT_READ_ONLY).
• codex_cli / claude_code — vendor-CLI bridges (read-write by default) that drive your local codex login / claude login and reach the mesh over the host’s own MCP surface.

With chat_runtime: auto, the host picks OpenClaw when a gateway is configured, otherwise falls back to host-native — so a self-host chats out of the box with no gateway.

Method	Path	Notes
POST	/api/v1/agent/message	Canonical chat contract (SSE or JSON)
GET	/api/v1/chat/options	Runtime-aware model/reasoning controls honored by the current engine
GET	/api/v1/chat/models	Legacy host-native-only model menu
POST	/api/v1/chat/stream	Legacy SSE shim (macOS 502/503 fallback)
POST	/api/v1/agent-tasks	Dispatch an agentic flow
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	Runtime provider availability
POST	/api/v1/skills/ask-knowledge	The hero retrieval skill (cb ask)

MCP server

The host serves Carabase’s retrieval tools over MCP to OpenClaw and to tailnet clients (Claude Desktop, Cursor, Codex).

Method	Path	Notes
POST	/mcp	Streamable HTTP JSON-RPC; initialize mints a session
GET	/mcp	Optional server-push SSE stream
DELETE	/mcp	Terminate a session
GET	/mcp/sse	Legacy SSE transport
POST	/mcp/messages	Legacy SSE transport message channel
GET|POST|DELETE	/api/v1/mcp-access/clients	Mint / list / revoke per-client tokens

Access is fail-open under tailnet trust until you mint a token, after which every /mcp/* request must present a bearer. See MCP tools for the tool catalog.

Imports + artifacts

Method	Path	Notes
POST	/api/v1/imports	Upload a notes-app / social / export archive (multipart, 1 GB 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
GET	/api/v1/artifacts/:id/download	Download the raw bytes
POST	/api/v1/artifacts/upload	Upload a file (images also enter the visual + OCR lanes)
GET	/api/v1/attachments/:id/download	Download a file artifact

Search + mesh

Method	Path	Notes
POST	/api/v1/search	Unified Summon search backend (lexical + semantic)
POST	/api/v1/mesh/resolve	Resolve a carabase:// mesh URI to its source
GET	/api/v1/surfaces	Read-only link-index of connected surfaces

Observability

Method	Path	Notes
GET	/api/v1/traces	Skill / workflow / cron / tool spans
GET	/api/v1/traces/:id	One trace
GET	/api/v1/traces/_facets	Filter facets
GET	/api/v1/activity/stream	Live activity feed (SSE; reads ?workspace_id=)
GET	/api/v1/activity/graph	Live knowledge-graph subgraph
GET	/api/v1/workspace/llm-usage	LLM usage ledger

Webhooks

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

SOUL.md

The per-workspace owner profile is injected into every turn’s system prompt. Drafts are proposed through curation rather than written directly.

Method	Path	Notes
GET	/api/v1/soul-profile	Read the owner profile
POST	/api/v1/soul-profile/ensure	Idempotent seed
POST	/api/v1/soul-profile/regenerate	Propose a redrafted profile
POST	/api/v1/soul-profile/reset	Destructive reset

LLM providers + routing

Method	Path	Notes
GET	/api/v1/llm-providers	List configured providers
GET|PUT|DELETE	/api/v1/llm-providers/:provider	Provider credentials (encrypted, per (workspace, provider))
GET|PUT	/api/v1/model-routing	Role-to-model routing config