API Reference
The Waggle local server runs on http://localhost:3333. All endpoints accept and return JSON unless otherwise noted.
Chat
| Method |
Path |
Description |
| POST |
/api/chat |
Send a message and receive an SSE stream of agent responses. Body: { message, workspaceId, sessionId, model? } |
| GET |
/api/history |
Get conversation history. Query: ?session=ID&workspace=ID |
The chat endpoint streams responses via Server-Sent Events (SSE). Events include message, tool_call, tool_result, approval_request, done, and error.
Workspaces
| Method |
Path |
Description |
| GET |
/api/workspaces |
List all workspaces |
| POST |
/api/workspaces |
Create a workspace. Body: { name, group, icon?, model?, personaId?, directory?, teamId? } |
| 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/:wid/sessions |
List sessions for a workspace, sorted by last active |
| POST |
/api/workspaces/:wid/sessions |
Create a new session. Body: { title? } |
| GET |
/api/workspaces/:wid/sessions/search |
Search across sessions. Query: ?q=query&limit=20 |
| GET |
/api/workspaces/:wid/sessions/:sid/export |
Export session as Markdown. Returns text/markdown |
| PATCH |
/api/sessions/:id |
Rename a session. Body: { title }. Query: ?workspace=ID |
| DELETE |
/api/sessions/:id |
Delete a session. Query: ?workspace=ID |
Memory
| Method |
Path |
Description |
| GET |
/api/memory/search |
Search memory. Query: `?q=query&scope=all |
| GET |
/api/memory/frames |
Recent frames without search. Query: ?workspace=ID&limit=50 |
| GET |
/api/memory/graph |
Knowledge graph entities and relations. Query: ?workspace=ID |
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 |
Live-probe a STORED provider key by id. Body: { provider } → { configured, valid, verified, error? } |
| GET |
/api/settings/permissions |
Read permission settings (YOLO mode, external gates) |
| PUT |
/api/settings/permissions |
Update permissions. Body: { yoloMode?, externalGates?, workspaceOverrides? } |
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 |
| GET |
/api/marketplace/enterprise-packs |
Enterprise packs (requires KVARK) |
| 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? }. Max 15MB. |
Supported types: images (PNG, JPG, GIF, WebP, SVG), documents (PDF, DOCX, PPTX), spreadsheets (XLSX, CSV), text/code (50+ extensions), archives (ZIP).
Import
| Method |
Path |
Description |
| POST |
/api/import/preview |
Preview import from ChatGPT or Claude export. Body: `{ data, source: "chatgpt" |
| POST |
/api/import/commit |
Import and save to personal memory. Body: { data, source } |
Feedback
| Method |
Path |
Description |
| POST |
/api/feedback |
Record feedback. Body: `{ sessionId, messageIndex, rating: "up" |
| GET |
/api/feedback/stats |
Improvement stats: positive rate, top issues, corrections, trend |
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 |
Team
| Method |
Path |
Description |
| POST |
/api/team/connect |
Connect to team server. Body: { serverUrl, token } |
| POST |
/api/team/disconnect |
Disconnect from team server |
| GET |
/api/team/status |
Current team connection status |
Anthropic Proxy
| Method |
Path |
Description |
| POST |
/v1/chat/completions |
OpenAI-compatible endpoint that translates to Anthropic API. Used by internal agent loop. |
Commands
| Method |
Path |
Description |
| POST |
/api/commands/execute |
Execute a slash command. Body: { command, workspaceId, sessionId } |
SSE Streaming
The /api/chat endpoint uses Server-Sent Events for real-time streaming. Event types:
| Event |
Description |
message |
Agent text chunk |
tool_call |
Agent is calling a tool (shows tool name and input) |
tool_result |
Tool execution result |
approval_request |
Agent needs approval before proceeding |
approval_resolved |
Approval was granted or denied |
memory_saved |
A memory frame was auto-saved |
done |
Agent turn complete |
error |
Error occurred |
