# 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 `. 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](#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](../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|in_progress|done` | | 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 |