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.
This commit is contained in:
@@ -1,22 +1,35 @@
|
||||
# API Reference
|
||||
# Local API reference
|
||||
|
||||
The Waggle local server runs on `http://localhost:3333`. All endpoints accept and return JSON unless otherwise noted.
|
||||
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 agent responses. Body: `{ message, workspaceId, sessionId, model? }` |
|
||||
| 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 responses via Server-Sent Events (SSE). Events include `message`, `tool_call`, `tool_result`, `approval_request`, `done`, and `error`.
|
||||
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?, directory?, teamId? }` |
|
||||
| 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 |
|
||||
@@ -27,20 +40,40 @@ The chat endpoint streams responses via Server-Sent Events (SSE). Events include
|
||||
|
||||
| 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` |
|
||||
| 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/search` | Search memory. Query: `?q=query&scope=all|personal|workspace&limit=20&workspace=ID` |
|
||||
| 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` |
|
||||
| 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
|
||||
|
||||
@@ -67,9 +100,9 @@ The chat endpoint streams responses via Server-Sent Events (SSE). Events include
|
||||
| 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? }` |
|
||||
| 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
|
||||
|
||||
@@ -120,7 +153,6 @@ The chat endpoint streams responses via Server-Sent Events (SSE). Events include
|
||||
| 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 |
|
||||
@@ -176,23 +208,16 @@ The chat endpoint streams responses via Server-Sent Events (SSE). Events include
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
| POST | `/api/ingest` | Ingest files. Body: `{ files: [{ name, content (base64) }], workspaceId? }`. Max 15MB. |
|
||||
| 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).
|
||||
|
||||
## Import
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
| POST | `/api/import/preview` | Preview import from ChatGPT or Claude export. Body: `{ data, source: "chatgpt"|"claude" }` |
|
||||
| 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"|"down", reason?, detail? }` |
|
||||
| GET | `/api/feedback/stats` | Improvement stats: positive rate, top issues, corrections, trend |
|
||||
| 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
|
||||
|
||||
@@ -206,19 +231,11 @@ Supported types: images (PNG, JPG, GIF, WebP, SVG), documents (PDF, DOCX, PPTX),
|
||||
|--------|------|-------------|
|
||||
| GET | `/api/audit/installs` | Recent install audit trail. Query: `?limit=20` |
|
||||
|
||||
## Team
|
||||
## Built-in provider proxy
|
||||
|
||||
| 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. |
|
||||
| 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
|
||||
|
||||
@@ -226,17 +243,20 @@ Supported types: images (PNG, JPG, GIF, WebP, SVG), documents (PDF, DOCX, PPTX),
|
||||
|--------|------|-------------|
|
||||
| POST | `/api/commands/execute` | Execute a slash command. Body: `{ command, workspaceId, sessionId }` |
|
||||
|
||||
## SSE Streaming
|
||||
## Chat stream events
|
||||
|
||||
The `/api/chat` endpoint uses Server-Sent Events for real-time streaming. Event types:
|
||||
`POST /api/chat` answers with Server-Sent Events. The event names the chat route sends:
|
||||
|
||||
| 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 |
|
||||
| `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 |
|
||||
|
||||
Reference in New Issue
Block a user