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.
263 lines
13 KiB
Markdown
263 lines
13 KiB
Markdown
# 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](#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 |
|