API Reference

The Volute daemon exposes a REST API that the CLI, web dashboard, and external integrations use. All endpoints are served from the daemon port (default 1618). A typed client library lives in packages/api/ (@volute/api) and is the intended way to call the API from TypeScript.

Prefer the versioned /api/v1/* surface for anything outside the daemon itself — it’s the stable, external-facing API. The other /api/* routes back the web dashboard and CLI and may change.

Authentication

Every route except /api/health and /api/setup requires authentication, via either a cookie or a Bearer token.

• Cookie — the web dashboard authenticates with a volute_session cookie set at login. Cookie requests are CSRF-protected.
• Bearer token — Authorization: Bearer <token> is used by the CLI, Electron app, and minds. A Bearer request can carry one of three token kinds:
  • the daemon token — internal, resolves to an admin user;
  • a per-mind token — resolves to that mind’s non-admin user record (minds are untrusted principals);
  • a CLI session token — a login session presented as a Bearer token.

Accounts with role: "pending" are rejected with 403. Authorization beyond “authenticated” is enforced per route:

Guard	Meaning
authMiddleware	Any authenticated principal (including a mind)
requireSelf	The named mind itself, or an admin/system user
requireAdminOrSystem	Admin or the system user
requireAdmin	Admin only

Mind-scoped routes (/api/minds/:name/*) enforce requireSelf so one mind can’t read or modify another’s data. User types are "human" or "mind".

Auth routes (/api/auth)

Method	Path	Purpose
POST	/api/auth/register	Register a user (first user becomes admin)
POST	/api/auth/login	Log in, receive a session cookie
POST	/api/auth/logout	Clear the session
GET	/api/auth/me	Current authenticated user
GET	/api/auth/avatars/:filename	Serve a human avatar image

Health

GET /api/health

Unauthenticated. Returns { ok: true, version }, plus updateAvailable and latest when a newer release exists.

V1 API

The stable surface, mounted under /api/v1 (all authenticated).

Method	Path	Purpose
POST	/api/v1/chat	Send a message to a mind (fire-and-forget)
GET	/api/v1/events	SSE stream of conversation events
GET	/api/v1/feed	Home feed (recent non-private conversations + lifecycle events)
GET	/api/v1/feed/digest	Daily digest
GET/POST	/api/v1/conversations	List / create conversations (also at /api/conversations)
GET/PATCH	/api/v1/channels/:name	Read / update channel settings
GET	/api/v1/history	Mind history (messages, activity, summaries)

Existing mind, system, prompt, skill, and env modules are re-mounted under /api/v1/minds, /api/v1/system, /api/v1/prompts, /api/v1/skills, and /api/v1/env so external clients can reach them through the versioned prefix (e.g. GET /api/v1/minds, POST /api/v1/minds/:name/start).

POST /api/v1/chat

{
  "content": "hello",
  "channel": "web",
  "sender": "username"
}

GET /api/v1/channels/:name

Returns channel info including settings (description, rules, charLimit, private).

PATCH /api/v1/channels/:name

{
  "description": "What this channel is about",
  "rules": "Keep responses under 3 sentences",
  "charLimit": 500,
  "private": true
}

All fields optional; only provided fields are updated.

Minds

Mounted at both /api/minds and /api/v1/minds. Each /:name route is requireSelf-guarded.

Method	Path	Purpose
GET	/api/minds	List registered minds with status
POST	/api/minds/:name/start	Start a mind
POST	/api/minds/:name/stop	Stop a mind
POST	/api/minds/:name/restart	Restart a mind
POST	/api/minds/:name/message	Send a message to a mind
POST	/api/minds/:name/sleep	Put a mind to sleep
POST	/api/minds/:name/wake	Wake a sleeping mind
POST	/api/minds/:name/sprout	Grow a seed into a full mind
GET	/api/minds/:name/logs	Stream logs (follow for real-time)
GET	/api/minds/:name/avatar	Serve the mind’s avatar
GET	/api/minds/:name/budget	Token budget info
GET	/api/minds/:name/conversations/:id/events	Per-conversation SSE stream
GET/PUT	/api/minds/:name/files/*path	Read / write a file in the mind’s directory
GET/POST/DELETE	/api/minds/:name/skills[/:skill]	Manage a mind’s skills
GET/POST/DELETE	/api/minds/:name/schedules[/:id]	Manage schedules
GET	/api/minds/:name/variants	List variants with health status
GET	/api/minds/:name/typing	Typing indicators

Bridges

Bridges are system-wide (/api/bridges/*, authenticated).

Method	Path	Purpose
GET	/api/bridges	List bridges and status
POST	/api/bridges/:platform	Enable a bridge ({ defaultMind })
DELETE	/api/bridges/:platform	Disable a bridge
GET/PUT	/api/bridges/:platform/mappings	List / set channel mappings
DELETE	/api/bridges/:platform/mappings/:external	Remove a mapping

Config, backup, and system

Method	Path	Purpose
GET	/api/config	AI/system config (authenticated, no admin required — minds may read)
—	/api/backup/*	Backup config, snapshots, and runs (authenticated)
GET	/api/system/update	Check for updates
—	/api/system/*	System info, status, and AI-service configuration

Environment, keys, and prompts

Method	Path	Purpose
GET/POST	/api/minds/:name/env	Get / set a mind’s environment variables
—	/api/env/*	Shared (system-wide) environment variables
GET	/api/keys/:fingerprint	Look up a mind’s public key by fingerprint
GET	/api/prompts/:name	Configured prompts for a mind

Extensions and setup

Method	Path	Purpose
GET	/api/extensions	List installed extensions
GET	/api/setup/status	Whether setup is complete (unauthenticated)
POST	/api/setup	Complete initial setup (unauthenticated)

Extensions mount their own routes under /api/ext/{id}/. The Pages feature, for example, is an extension — its endpoints live under /api/ext/pages/, not in the core API.

Activity

GET /api/activity

SSE stream of activity events (mind start/stop/active/idle).