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 |