From c84f4ac905a01ffaec6d333c241e76cf905d06ac Mon Sep 17 00:00:00 2001
From: Thieu Nguyen <79964592+thieung@users.noreply.github.com>
Date: Thu, 2 Apr 2026 08:24:08 +0700
Subject: [PATCH] docs: sync API endpoint documentation with codebase (#632)

Add ~55 undocumented REST endpoints and ~30 undocumented WS methods.
Remove 14 stale entries (custom tools HTTP, sessions HTTP, delegations WS).
New sections: tenants, system-configs, edition, TTS, browser, zalo, export/import.
---
 docs/18-http-api.md      | 200 ++++++++++++++++++++++++++++++---------
 docs/19-websocket-rpc.md |  97 +++++++++++++++----
 2 files changed, 234 insertions(+), 63 deletions(-)

diff --git a/docs/18-http-api.md b/docs/18-http-api.md
index b2ea6ad0..44c56e6f 100644
--- a/docs/18-http-api.md
+++ b/docs/18-http-api.md
@@ -234,6 +234,26 @@ Rules:
 - unset reasoning resolves to `off`
 - the runtime may normalize unsupported efforts, and the actual decision is surfaced in trace span metadata
 
+### Export & Import
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/v1/agents/{id}/export/preview` | Preview agent export |
+| `GET` | `/v1/agents/{id}/export` | Export agent config |
+| `GET` | `/v1/agents/{id}/export/download/{token}` | Download export file |
+| `GET` | `/v1/export/download/{token}` | Global export download |
+| `POST` | `/v1/agents/import/preview` | Preview agent import |
+| `POST` | `/v1/agents/import` | Import agent |
+| `POST` | `/v1/agents/{id}/import` | Merge import into existing agent |
+
+### Team Export & Import
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/v1/teams/{id}/export/preview` | Preview team export |
+| `GET` | `/v1/teams/{id}/export` | Export team config |
+| `POST` | `/v1/teams/import` | Import team |
+
 ### Codex Pool Activity
 
 | Method | Path | Description |
@@ -275,6 +295,8 @@ Use `direct_selection_count` plus the `selected_provider` sequence to verify rea
 | `PUT` | `/v1/skills/{id}` | Update skill metadata |
 | `DELETE` | `/v1/skills/{id}` | Delete skill (not system skills) |
 | `POST` | `/v1/skills/{id}/toggle` | Toggle skill enabled/disabled state |
+| `PUT` | `/v1/skills/{id}/tenant-config` | Set tenant-level skill config |
+| `DELETE` | `/v1/skills/{id}/tenant-config` | Delete tenant-level skill config |
 
 ### Skill Grants
 
@@ -303,6 +325,14 @@ Use `direct_selection_count` plus the `selected_provider` sequence to verify rea
 | `POST` | `/v1/skills/install-dep` | Install single dependency |
 | `GET` | `/v1/skills/runtimes` | Check runtime availability |
 
+### Export & Import
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/v1/skills/export/preview` | Preview skills export bundle |
+| `GET` | `/v1/skills/export` | Export skills bundle |
+| `POST` | `/v1/skills/import` | Import skills bundle |
+
 ---
 
 ## 6. Providers
@@ -323,6 +353,9 @@ LLM provider management. API keys are encrypted with AES-256-GCM in the database
 |--------|------|-------------|
 | `POST` | `/v1/providers/{id}/verify` | Test provider+model with minimal LLM call |
 | `GET` | `/v1/providers/{id}/models` | List models plus any known reasoning capability metadata |
+| `POST` | `/v1/providers/{id}/verify-embedding` | Verify embedding model configuration |
+| `GET` | `/v1/providers/{id}/codex-pool-activity` | Provider-level Codex pool activity |
+| `GET` | `/v1/embedding/status` | Check global embedding availability |
 | `GET` | `/v1/providers/claude-cli/auth-status` | Check Claude CLI login status |
 
 **Supported types:** `anthropic_native`, `openai_compat`, `chatgpt_oauth`, `gemini_native`, `dashscope`, `bailian`, `minimax`, `claude_cli`, `acp`
@@ -361,19 +394,7 @@ Notes:
 
 ---
 
-## 7. Sessions
-
-| Method | Path | Description |
-|--------|------|-------------|
-| `GET` | `/v1/sessions` | List sessions (paginated) |
-| `GET` | `/v1/sessions/{key}` | Get session with messages |
-| `DELETE` | `/v1/sessions/{key}` | Delete session |
-| `POST` | `/v1/sessions/{key}/reset` | Clear session messages |
-| `PATCH` | `/v1/sessions/{key}` | Update label, model, metadata |
-
----
-
-## 8. MCP Servers
+## 7. MCP Servers
 
 Model Context Protocol server management.
 
@@ -387,6 +408,7 @@ Model Context Protocol server management.
 | `PUT` | `/v1/mcp/servers/{id}` | Update server |
 | `DELETE` | `/v1/mcp/servers/{id}` | Delete server |
 | `POST` | `/v1/mcp/servers/test` | Test connection (no save) |
+| `POST` | `/v1/mcp/servers/{id}/reconnect` | Reconnect MCP server |
 | `GET` | `/v1/mcp/servers/{id}/tools` | List runtime-discovered tools |
 
 ### Agent Grants
@@ -415,9 +437,27 @@ Model Context Protocol server management.
 
 Grants support `tool_allow` and `tool_deny` JSON arrays for fine-grained tool filtering.
 
+### User Credentials
+
+Per-user credential storage for MCP servers (e.g., API keys users provide for external services).
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `PUT` | `/v1/mcp/servers/{id}/user-credentials` | Set user credentials |
+| `GET` | `/v1/mcp/servers/{id}/user-credentials` | Get user credentials |
+| `DELETE` | `/v1/mcp/servers/{id}/user-credentials` | Delete user credentials |
+
+### Export & Import
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/v1/mcp/export/preview` | Preview MCP export bundle |
+| `GET` | `/v1/mcp/export` | Export MCP servers + grants |
+| `POST` | `/v1/mcp/import` | Import MCP config bundle |
+
 ---
 
-## 9. Tools
+## 8. Tools
 
 ### Built-in Tools
 
@@ -426,18 +466,8 @@ Grants support `tool_allow` and `tool_deny` JSON arrays for fine-grained tool fi
 | `GET` | `/v1/tools/builtin` | List all built-in tools |
 | `GET` | `/v1/tools/builtin/{name}` | Get tool definition |
 | `PUT` | `/v1/tools/builtin/{name}` | Update enabled/settings |
-
-### Custom Tools
-
-| Method | Path | Description |
-|--------|------|-------------|
-| `GET` | `/v1/tools/custom` | List custom tools (paginated) |
-| `POST` | `/v1/tools/custom` | Create custom tool |
-| `GET` | `/v1/tools/custom/{id}` | Get tool details |
-| `PUT` | `/v1/tools/custom/{id}` | Update tool |
-| `DELETE` | `/v1/tools/custom/{id}` | Delete tool |
-
-Query parameters for list: `agent_id`, `search`, `limit`, `offset`
+| `PUT` | `/v1/tools/builtin/{name}/tenant-config` | Set tenant-level tool config |
+| `DELETE` | `/v1/tools/builtin/{name}/tenant-config` | Delete tenant-level tool config |
 
 ### Direct Invocation
 
@@ -496,6 +526,10 @@ Per-agent entity-relation graph.
 | `POST` | `/v1/agents/{agentID}/kg/extract` | LLM-powered entity extraction |
 | `GET` | `/v1/agents/{agentID}/kg/stats` | Knowledge graph statistics |
 | `GET` | `/v1/agents/{agentID}/kg/graph` | Full graph for visualization |
+| `POST` | `/v1/agents/{agentID}/kg/dedup/scan` | Scan for duplicate entities |
+| `GET` | `/v1/agents/{agentID}/kg/dedup` | List dedup candidates |
+| `POST` | `/v1/agents/{agentID}/kg/merge` | Merge duplicate entities |
+| `POST` | `/v1/agents/{agentID}/kg/dedup/dismiss` | Dismiss dedup candidate |
 
 ---
 
@@ -517,6 +551,16 @@ Per-agent entity-relation graph.
 |--------|------|-------------|
 | `GET` | `/v1/contacts` | List contacts (paginated) |
 | `GET` | `/v1/contacts/resolve?ids=...` | Resolve contacts by IDs (max 100) |
+| `POST` | `/v1/contacts/merge` | Merge contacts into unified identity |
+| `POST` | `/v1/contacts/unmerge` | Unmerge previously merged contacts |
+| `GET` | `/v1/contacts/merged/{tenantUserId}` | List merged contacts for tenant user |
+
+### Tenant Users
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/v1/tenant-users` | List tenant users |
+| `GET` | `/v1/users/search` | Search users by query |
 
 ### Group Writers
 
@@ -546,20 +590,7 @@ Compaction runs in the background. Falls back to hard delete if no LLM provider
 
 ---
 
-## 14. Delegations
-
-Agent task delegation and authorization history.
-
-| Method | Path | Description |
-|--------|------|-------------|
-| `GET` | `/v1/delegations` | List delegations (paginated, filterable) |
-| `GET` | `/v1/delegations/{id}` | Get delegation record |
-
-**Filters:** `source_agent_id`, `target_agent_id`, `team_id`, `user_id`, `status`, `limit`, `offset`
-
----
-
-## 15. Team Events
+## 14. Team Events
 
 Team activity and audit trail.
 
@@ -583,6 +614,15 @@ CLI authentication credentials for secure command execution. Requires **admin ro
 | `GET` | `/v1/cli-credentials/presets` | Get preset credential templates |
 | `POST` | `/v1/cli-credentials/{id}/test` | Test credential connection (dry-run) |
 
+### Per-User Credentials
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/v1/cli-credentials/{id}/user-credentials` | List user credentials for CLI cred |
+| `GET` | `/v1/cli-credentials/{id}/user-credentials/{userId}` | Get user credential |
+| `PUT` | `/v1/cli-credentials/{id}/user-credentials/{userId}` | Set user credential |
+| `DELETE` | `/v1/cli-credentials/{id}/user-credentials/{userId}` | Delete user credential |
+
 ---
 
 ## 17. Runtime & Packages Management
@@ -745,7 +785,9 @@ Workspace file management.
 |--------|------|-------------|
 | `GET` | `/v1/storage/files` | List files with depth limiting |
 | `GET` | `/v1/storage/files/{path...}` | Read file (JSON or raw) |
+| `POST` | `/v1/storage/files` | Upload file (admin) |
 | `DELETE` | `/v1/storage/files/{path...}` | Delete file/directory |
+| `PUT` | `/v1/storage/move` | Move/rename file (admin) |
 | `GET` | `/v1/storage/size` | Stream storage size (Server-Sent Events, cached 60 min) |
 
 **Query parameters:**
@@ -770,6 +812,7 @@ Workspace file management.
 | Method | Path | Description |
 |--------|------|-------------|
 | `GET` | `/v1/files/{path...}` | Serve workspace file by path |
+| `POST` | `/v1/files/sign` | Generate signed URL for token-based file access |
 
 Auth via Bearer token or `?token=` query param (for `<img>` tags). MIME type auto-detected. Path traversal blocked.
 
@@ -900,7 +943,62 @@ Notes:
 
 ---
 
-## 26. System
+## 26. Edition
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/v1/edition` | Get current edition info (lite vs standard) |
+
+---
+
+## 27. Tenants
+
+Multi-tenant management (admin only).
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/v1/tenants` | List tenants |
+| `POST` | `/v1/tenants` | Create tenant |
+| `GET` | `/v1/tenants/{id}` | Get tenant |
+| `PATCH` | `/v1/tenants/{id}` | Update tenant |
+| `GET` | `/v1/tenants/{id}/users` | List tenant users |
+| `POST` | `/v1/tenants/{id}/users` | Add user to tenant |
+| `DELETE` | `/v1/tenants/{id}/users/{userId}` | Remove user from tenant |
+
+---
+
+## 28. System Configs
+
+Key-value system configuration store.
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/v1/system-configs` | List all system configs |
+| `GET` | `/v1/system-configs/{key}` | Get config by key |
+| `PUT` | `/v1/system-configs/{key}` | Set config value (admin) |
+| `DELETE` | `/v1/system-configs/{key}` | Delete config (admin) |
+
+---
+
+## 29. Team Workspace & Attachments
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/v1/teams/{teamId}/workspace/upload` | Upload file to team workspace |
+| `PUT` | `/v1/teams/{teamId}/workspace/move` | Move workspace item |
+| `GET` | `/v1/teams/{teamId}/attachments/{attachmentId}/download` | Download task attachment |
+
+---
+
+## 30. Shell Deny Groups
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/v1/shell-deny-groups` | List shell command deny group patterns |
+
+---
+
+## 31. System
 
 | Method | Path | Description |
 |--------|------|-------------|
@@ -919,7 +1017,7 @@ Notes:
 
 ---
 
-## 27. MCP Bridge
+## 32. MCP Bridge
 
 Exposes GoClaw tools to Claude CLI via streamable HTTP at `/mcp/bridge`. Only listens on localhost. Protected by gateway token with HMAC-signed context headers.
 
@@ -966,6 +1064,7 @@ The following operations are **only available via WebSocket RPC**, not HTTP:
 - **Cron jobs:** List, create, update, delete, logs (use WebSocket method `cron.*`)
 - **Send messages:** Send to channels (use WebSocket method `send.*`)
 - **Config management:** Get, apply, patch (use WebSocket method `config.*`)
+- **Delegations:** List, get delegation history (use WebSocket method `delegations.*`) — _not currently registered as WS methods either; may be removed_
 
 These endpoints require an active WebSocket connection to the `/ws` endpoint with proper authentication and agent context.
 
@@ -981,7 +1080,6 @@ These endpoints require an active WebSocket connection to the `/ws` endpoint wit
 | `internal/http/skills.go` | Skill management + grants + versions |
 | `internal/http/providers.go` | Provider CRUD + verification + models |
 | `internal/http/mcp.go` | MCP server management + grants + requests |
-| `internal/http/custom_tools.go` | Custom tool CRUD |
 | `internal/http/builtin_tools.go` | Built-in tool management |
 | `internal/http/tools_invoke.go` | Direct tool invocation |
 | `internal/http/channel_instances.go` | Channel instance management + contacts |
@@ -995,8 +1093,9 @@ These endpoints require an active WebSocket connection to the `/ws` endpoint wit
 | `internal/http/media_serve.go` | Media file serving |
 | `internal/http/files.go` | Workspace file serving |
 | `internal/http/api_keys.go` | API key management + revoke |
-| `internal/http/delegations.go` | Delegation history API |
 | `internal/http/team_events.go` | Team event history API |
+| `internal/http/team_attachments.go` | Team attachment downloads |
+| `internal/http/workspace_upload.go` | Team workspace upload + move |
 | `internal/http/secure_cli.go` | CLI credential management |
 | `internal/http/packages.go` | Runtime package management (apk/pip/npm) |
 | `internal/http/pending_messages.go` | Pending message groups + compaction |
@@ -1007,3 +1106,16 @@ These endpoints require an active WebSocket connection to the `/ws` endpoint wit
 | `cmd/gateway.go` | Handler instantiation and wiring |
 | `cmd/pkg-helper/main.go` | Root-privileged system package helper (apk add/del) |
 | `internal/skills/package_lister.go` | Query installed packages from apk/pip3/npm |
+| `internal/http/edition.go` | Edition info endpoint |
+| `internal/http/system_configs.go` | System config key-value store |
+| `internal/http/tenants.go` | Multi-tenant management |
+| `internal/http/mcp_user_credentials.go` | MCP per-user credentials |
+| `internal/http/mcp_export.go` | MCP export |
+| `internal/http/mcp_import.go` | MCP import |
+| `internal/http/skills_export.go` | Skills export |
+| `internal/http/skills_import.go` | Skills import |
+| `internal/http/agents_export.go` | Agent export |
+| `internal/http/agents_import.go` | Agent import |
+| `internal/http/contact_merge_handlers.go` | Contact merge/unmerge |
+| `internal/http/user_search.go` | User search |
+| `internal/http/secure_cli_user_credentials.go` | CLI per-user credentials |
diff --git a/docs/19-websocket-rpc.md b/docs/19-websocket-rpc.md
index a8bbb525..4f13aebc 100644
--- a/docs/19-websocket-rpc.md
+++ b/docs/19-websocket-rpc.md
@@ -127,6 +127,13 @@ Inject a message into the session transcript without triggering the agent.
 **Request:** `{sessionKey, message, label}`
 **Response:** `{ok: true, messageId: "..."}`
 
+### `chat.session.status`
+
+Check if a session has a running agent invocation.
+
+**Request:** `{sessionKey}`
+**Response:** `{running: true, runId: "..."}`
+
 ---
 
 ## 3. Agents
@@ -203,6 +210,15 @@ Delete an agent (admin only).
 
 **Request:** `{agentId, name?, content?}`
 
+### Agent Links
+
+| Method | Description |
+|--------|-------------|
+| `agents.links.list` | List agent links |
+| `agents.links.create` | Create agent link |
+| `agents.links.update` | Update agent link |
+| `agents.links.delete` | Delete agent link |
+
 ---
 
 ## 4. Sessions
@@ -295,6 +311,7 @@ Get JSON schema for config form generation.
 |--------|-------------|
 | `channels.list` | List enabled channels |
 | `channels.status` | Get channel connection status |
+| `channels.toggle` | Toggle channel enabled/disabled |
 
 ### Channel Instances
 
@@ -357,6 +374,8 @@ sequenceDiagram
 |--------|-------------|
 | `teams.tasks.list` | List team tasks (filterable) |
 | `teams.tasks.get` | Get task with comments/events |
+| `teams.tasks.get-light` | Get task without comments/events (lightweight) |
+| `teams.tasks.active-by-session` | Get active task for a session |
 | `teams.tasks.create` | Create task |
 | `teams.tasks.approve` | Approve task |
 | `teams.tasks.reject` | Reject task |
@@ -365,6 +384,7 @@ sequenceDiagram
 | `teams.tasks.events` | List task events |
 | `teams.tasks.assign` | Assign to member |
 | `teams.tasks.delete` | Delete task |
+| `teams.tasks.delete-bulk` | Bulk delete tasks |
 
 ### Team Context
 
@@ -403,18 +423,7 @@ sequenceDiagram
 
 ---
 
-## 12. Delegations
-
-| Method | Description |
-|--------|-------------|
-| `delegations.list` | List delegation history (filterable) |
-| `delegations.get` | Get delegation record |
-
-**Filters:** `source_agent_id`, `target_agent_id`, `team_id`, `user_id`, `status`
-
----
-
-## 13. Usage & Quotas
+## 12. Usage & Quotas
 
 | Method | Description |
 |--------|-------------|
@@ -424,7 +433,7 @@ sequenceDiagram
 
 ---
 
-## 14. API Keys
+## 13. API Keys
 
 Admin-only methods.
 
@@ -438,7 +447,7 @@ See [20 — API Keys & Auth](20-api-keys-auth.md) for the full authentication mo
 
 ---
 
-## 15. Messaging
+## 14. Messaging
 
 ### `send`
 
@@ -449,7 +458,7 @@ Route an outbound message to a channel.
 
 ---
 
-## 16. Logs
+## 15. Logs
 
 ### `logs.tail`
 
@@ -462,7 +471,56 @@ Log entries are delivered as events while tailing is active.
 
 ---
 
-## 17. Permission Matrix
+## 16. Tenants
+
+Multi-tenant management (admin only).
+
+| Method | Description |
+|--------|-------------|
+| `tenants.list` | List tenants |
+| `tenants.get` | Get tenant details |
+| `tenants.create` | Create tenant |
+| `tenants.update` | Update tenant |
+| `tenants.users.list` | List tenant users |
+| `tenants.users.add` | Add user to tenant |
+| `tenants.users.remove` | Remove user from tenant |
+| `tenants.mine` | Get current user's tenant |
+
+---
+
+## 17. TTS (Text-to-Speech)
+
+| Method | Description |
+|--------|-------------|
+| `tts.status` | Get TTS status and current provider |
+| `tts.enable` | Enable TTS |
+| `tts.disable` | Disable TTS |
+| `tts.convert` | Convert text to speech audio |
+| `tts.setProvider` | Set TTS provider |
+| `tts.providers` | List available TTS providers |
+
+---
+
+## 18. Browser Automation
+
+| Method | Description |
+|--------|-------------|
+| `browser.act` | Execute browser action (click, type, navigate) |
+| `browser.snapshot` | Get accessibility snapshot of current page |
+| `browser.screenshot` | Take screenshot of current page |
+
+---
+
+## 19. Zalo Personal
+
+| Method | Description |
+|--------|-------------|
+| `zalo.personal.qr.start` | Start Zalo QR code authentication |
+| `zalo.personal.contacts` | List Zalo personal contacts |
+
+---
+
+## 20. Permission Matrix
 
 Methods are gated by role. The role is determined at `connect` time from the token type and scopes.
 
@@ -474,7 +532,7 @@ Methods are gated by role. The role is determined at `connect` time from the tok
 
 ### Admin-Only Methods
 
-`config.apply`, `config.patch`, `agents.create`, `agents.update`, `agents.delete`, `channels.toggle`, `device.pair.approve`, `device.pair.deny`, `device.pair.revoke`, `teams.*`, `api_keys.*`
+`config.apply`, `config.patch`, `agents.create`, `agents.update`, `agents.delete`, `channels.toggle`, `device.pair.approve`, `device.pair.deny`, `device.pair.revoke`, `teams.*`, `api_keys.*`, `tenants.*`
 
 ### Write Methods (Operator+)
 
@@ -486,7 +544,7 @@ All other methods: list, get, preview, status, history, etc.
 
 ---
 
-## 18. Events
+## 21. Events
 
 The server pushes events to connected clients via event frames. Key event types:
 
@@ -532,7 +590,8 @@ The server pushes events to connected clients via event frames. Key event types:
 | `internal/gateway/methods/teams_tasks.go` | Team task management |
 | `internal/gateway/methods/teams_workspace.go` | Team workspace |
 | `internal/gateway/methods/exec_approval.go` | Exec approval flow |
-| `internal/gateway/methods/delegations.go` | Delegation history |
+| `internal/gateway/methods/agent_links.go` | Agent links management |
+| `internal/gateway/methods/tenants.go` | Tenant management |
 | `internal/gateway/methods/usage.go` | Usage records |
 | `internal/gateway/methods/quota_methods.go` | Quota consumption |
 | `internal/gateway/methods/api_keys.go` | API key management |