moving

docs/reference/api.md

@@ -0,0 +1,242 @@
+# 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|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` |
+
+## 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|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? }`. 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"|"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 |
+
+## 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 |