Files
waggle-os/docs/reference/api.md
shumeiko.it dd6564451a docs: bring the command and local API references up to date (P2.4)
commands.md lists all 23 registered slash commands with their working
aliases and drops the FTS5 and two-mind wording. api.md explains the
bearer session token and that the API is internal, fixes the session
route parameters, lists the memory routes served through the memory
contract, the current chat stream events and the permissions body, and
removes the team, import and KVARK enterprise-pack routes.
2026-11-01 02:01:57 +01:00

13 KiB

Local API reference

The Waggle server runs on http://localhost:3333 and listens on 127.0.0.1 only. The web UI uses this API; it is not a stable public interface and can change between releases. Endpoints accept and return JSON unless noted otherwise. The routes live in packages/server/src/local/routes/.

Authentication

Every /api/* request needs the session token as Authorization: Bearer <token>. Server-Sent Event streams that cannot send headers accept it as ?token=. The web UI gets the token from GET /api/auth/session-token, which answers only same-origin requests from the page the server serves (the desktop app gets it through its own launch credential). Requests with a Host header other than a local one are refused.

This page lists the main route groups, not every route.

Chat

Method Path Description
POST /api/chat Send a message and receive an SSE stream of the agent's reply. Body: { message, workspaceId?, sessionId?, model?, persona? }
GET /api/history Get conversation history. Query: ?session=ID&workspace=ID

The chat endpoint streams the reply as Server-Sent Events; see Chat stream events.

Workspaces

Method Path Description
GET /api/workspaces List all workspaces
POST /api/workspaces Create a workspace. Body: { name, group, icon?, model?, personaId?, templateId?, storageType?: 'virtual' | 'local', storagePath? }
GET /api/workspaces/:id Get workspace by ID
PUT /api/workspaces/:id Update workspace. Body: { name?, group?, icon?, model?, personaId? }
DELETE /api/workspaces/:id Delete workspace
GET /api/workspaces/:id/context Workspace catch-up context: summary, threads, decisions, suggestions, stats
GET /api/workspaces/:id/files List ingested files for a workspace

Sessions

Method Path Description
GET /api/workspaces/:workspaceId/sessions List sessions for a workspace, sorted by last active
POST /api/workspaces/:workspaceId/sessions Create a new session. Body: { title? }
GET /api/workspaces/:workspaceId/sessions/search Search across sessions. Query: ?q=query&limit=20
GET /api/workspaces/:workspaceId/sessions/:sessionId/export Export a session as Markdown (text/markdown)
GET /api/workspaces/:workspaceId/sessions/:sessionId/timeline Tool events of a session
PATCH /api/sessions/:sessionId Rename a session. Body: { title }. Query: ?workspace=ID
DELETE /api/sessions/:sessionId Delete a session. Query: ?workspace=ID

Memory

All memory routes go through the memory contract (memory.md). Some paths still say "frames", the name used by the old memory engine; they return memory records.

Method Path Description
GET /api/memory/capabilities What the memory store supports, and the extraction setting
PUT /api/memory/settings Turn background fact extraction on or off. Body: { extraction: boolean }
GET /api/memory/search Search memory. Query: ?q=query&scope=all|personal|workspace|global&workspace=ID&limit=20&since=&until= (all is personal plus the given workspace; global is personal plus every workspace)
GET /api/memory/frames Newest personal and workspace memories. Query: ?workspace=ID&limit=50&since=&until=
POST /api/memory/frames Save a memory. Body: { content, workspaceId?, importance?, kind?, source? }
PUT /api/memory/frames/:id Edit a memory's text or importance
DELETE /api/memory/frames/:id Delete a memory
GET /api/memory/stats Memory counts. Query: ?workspace=ID
GET /api/memory List memories. Query: ?mind=personal|workspace&workspace=ID&kind=&status=&q=&limit=
GET /api/memory/:id One memory
POST /api/memory Create a memory stated by the user
PATCH /api/memory/:id Edit text, importance, kind, title, tags, evidence or status
DELETE /api/memory/:id Delete a memory
POST /api/memory/:id/archive Archive a memory (reversible)
POST /api/memory/:id/confirm Mark a memory as confirmed by the user
GET /api/memory/:id/trace The execution that produced a memory ("why did you do that?")
POST /api/memory/erase Forget one memory ({ id }) or every memory saved from one chat ({ sessionId })
POST /api/memory/merge Merge several memories of one scope into one
GET /api/memory/graph Always returns an empty graph: the knowledge graph is not part of this release

Agent

Method Path Description
GET /api/agent/status Agent status: model, tokens used, estimated cost, turn count
GET /api/agent/cost Detailed cost breakdown with formatted summary
POST /api/agent/cost/reset Reset cost tracking (takes effect on server restart)
GET /api/agent/model Current model name
PUT /api/agent/model Switch model. Body: { model }
GET /api/agents/active Active sub-agent orchestrator state

Approval Gates

Method Path Description
GET /api/approval/pending List pending approval requests
POST /api/approval/:requestId Approve or deny. Body: { approved: boolean, reason? }

Settings

Method Path Description
GET /api/settings Read config: default model, providers (masked keys), paths
PUT /api/settings Update config. Body: { defaultModel?, providers? }
POST /api/settings/test-key Validate API key format. Body: { provider, apiKey }
POST /api/settings/probe-provider Test a stored provider key with the provider. Body: { provider } → { configured, valid, verified, error? }
GET /api/settings/permissions Read the approval settings
PUT /api/settings/permissions Update the approval settings. Body: { defaultAutonomy?, externalGates?, workspaceOverrides? } (yoloMode is still accepted)

Vault

Method Path Description
GET /api/vault List all secrets (names and types only, no values)
POST /api/vault Add or update a secret. Body: { name, value, type? }
DELETE /api/vault/:name Delete a secret
POST /api/vault/:name/reveal Decrypt and return the full value

Skills

Method Path Description
GET /api/skills List all installed skills
GET /api/skills/:name Get full skill content
POST /api/skills Create a new skill. Body: { name, content }
PUT /api/skills/:name Update skill content. Body: { content }
DELETE /api/skills/:name Remove a skill
GET /api/skills/suggestions Contextual skill recommendations. Query: ?context=text&topN=3
GET /api/skills/hash-status Check which skills have changed on disk
POST /api/skills/starter-pack Install all starter skills
GET /api/skills/starter-pack/catalog Browse starter skills with install state and family grouping
POST /api/skills/starter-pack/:id Install a single starter skill
GET /api/skills/capability-packs/catalog List all packs with skill states
POST /api/skills/capability-packs/:id Install all skills in a pack

Plugins

Method Path Description
GET /api/plugins List all installed plugins
POST /api/plugins/install Install a plugin. Body: { sourceDir }
DELETE /api/plugins/:name Uninstall a plugin

Capabilities

Method Path Description
GET /api/capabilities/status Aggregated capability dashboard: plugins, MCP, skills, tools, commands, hooks, workflows
POST /api/capabilities/plugins/:name/enable Enable a plugin
POST /api/capabilities/plugins/:name/disable Disable a plugin

Marketplace

Method Path Description
GET /api/marketplace/search Search catalog. Query: ?query=text&type=skill&category=cat&limit=20&offset=0
GET /api/marketplace/packs List all capability packs
GET /api/marketplace/packs/:slug Pack detail with packages
POST /api/marketplace/install Install package. Body: { packageId, installPath?, settings?, force? }
POST /api/marketplace/uninstall Uninstall package. Body: { packageId }
GET /api/marketplace/installed List installed packages
POST /api/marketplace/security-check Security scan without install. Body: { packageId }
GET /api/marketplace/sources List marketplace sources
POST /api/marketplace/sync Sync from sources. Body: { sources?: string[] }

Connectors

Method Path Description
GET /api/connectors List all connectors with status
GET /api/connectors/:id/health Check connector health
POST /api/connectors/:id/connect Store credentials. Body: { token?, apiKey?, refreshToken?, expiresAt?, scopes?, email? }
POST /api/connectors/:id/disconnect Remove credentials from vault

Personas

Method Path Description
GET /api/personas List all available personas (ID, name, description, icon, affinity, commands)

Cron (Scheduling)

Method Path Description
POST /api/cron Create schedule. Body: { name, cronExpr, jobType, jobConfig?, workspaceId?, enabled? }
GET /api/cron List all schedules
GET /api/cron/:id Get one schedule
PATCH /api/cron/:id Update schedule. Body: { name?, cronExpr?, jobConfig?, workspaceId?, enabled? }
DELETE /api/cron/:id Delete schedule
POST /api/cron/:id/trigger Manually trigger a schedule

Tasks

Method Path Description
GET /api/workspaces/:id/tasks List tasks. Query: `?status=open
POST /api/workspaces/:id/tasks Create task. Body: { title, assigneeName?, assigneeId? }
PATCH /api/workspaces/:id/tasks/:taskId Update task (status, assignment)
DELETE /api/workspaces/:id/tasks/:taskId Delete task

Fleet (Mission Control)

Method Path Description
GET /api/fleet List active workspace sessions with status and duration
POST /api/fleet/:workspaceId/pause Pause a workspace session
POST /api/fleet/:workspaceId/resume Resume a paused session
POST /api/fleet/:workspaceId/kill Abort and close a session

File Ingestion

Method Path Description
POST /api/ingest Ingest files. Body: { files: [{ name, content (base64) }], workspaceId? }. Up to 10 MB per file; the request body is limited to 15 MB.

Supported types: images (PNG, JPG, GIF, WebP, SVG), documents (PDF, DOCX, PPTX), spreadsheets (XLSX, CSV), text/code (50+ extensions), archives (ZIP).

Feedback

Method Path Description
POST /api/feedback Record thumbs up or down on a reply. Body: { sessionId, messageIndex, rating: "up"|"down", reason?, detail? }
GET /api/feedback/stats Feedback statistics

Notifications

Method Path Description
GET /api/notifications/stream SSE stream of notifications (cron, approval, task, message, agent events)

Audit

Method Path Description
GET /api/audit/installs Recent install audit trail. Query: ?limit=20

Built-in provider proxy

Method Path Description
POST /v1/chat/completions OpenAI-compatible endpoint used by the agent loop and memory extraction. Translates Claude requests to Anthropic's Messages API and forwards other providers' models to their OpenAI-compatible APIs

Commands

Method Path Description
POST /api/commands/execute Execute a slash command. Body: { command, workspaceId, sessionId }

Chat stream events

POST /api/chat answers with Server-Sent Events. The event names the chat route sends:

Event Description
token A chunk of the agent's text
step A progress step of the turn (recall, thinking, tool use and so on)
tool The agent calls a tool
tool_result The result of a tool call
approval_required A tool call waits for the user's approval
approval_held A tool call was held for later approval
model_switch The turn moved to another model
file_created A tool created a file
notification A notification for the user
done The turn is complete
error The turn failed