Simmetric Chat
返回文档
指南 04

API 参考

Express 服务器（端口 3000，前缀 /api）的 REST API，带交互式 Swagger UI 和由服务器自身提供的 OpenAPI 规范，此处按领域记录了其认证机制、速率限制和响应约定。

5 分钟阅读

Express 服务器（端口 3000，前缀 /api）的 REST API，带交互式 Swagger UI 和由服务器自身提供的 OpenAPI 规范，此处按领域记录了其认证机制、速率限制和响应约定。

认证

方法Header用途
JWTAuthorization: Bearer <token>内部用户（frontend、Tauri）
API 密钥X-Api-Key: sk-...Widget 嵌入、程序化集成
Collector 密钥X-Collector-Secretserver↔collector（恒定时间比较）
查询令牌?token=OCR 图片访问

中间件（packages/server/src/middleware/）：auth.ts、rbac.ts、license.ts、rateLimit.ts、widgetCors.ts。

速率限制

限制器限制（生产/开发）范围
general200 / 2000 req/minIP
auth10 / 100 req/minIP
probe10 / 100 req/minIP
widget chat30 / 200 req/min（每个 widget 覆盖）widgetId
widget 每日每天 5 / 50 条消息widgetId+IP
widget 会话每天 50 / 500 次创建IP
widget lead每小时 3 / 30IP

没有专用的聊天速率限制器：ReAct 代理在内部强制执行自己的限制（每用户并发、token 预算、wallclock 超时 - agentBudgetService.ts）；全局 200/min 限制器仍是安全网。带有 X-Widget-Id 头的请求跳过全局限制器（widget 服务在上游对其进行限流）；widget 使用 rateLimitPerMinute / sessionLimitPerDay 作为每个 widget 的覆盖。

响应约定

  • 成功：JSON 实体或 { ok: true }。
  • 错误：{ error: string }（Zod 验证错误附带 details）。
  • 许可证门控：402 { error, feature, tier, limit?, current? }。
  • RBAC：401（未认证）、403（权限不足）。
  • SSE：event: <type>\ndata: <json>\n\n。

Auth - /api/auth（routes/auth.ts）

方法路径认证RBAC说明
POST/auth/registerpublic—仅当 ALLOW_REGISTRATION=true 时；body registerSchema
POST/auth/admin-registerJWTrequireAdminbody adminRegisterSchema
POST/auth/loginpublic—body loginSchema（safeParse → 无效时 400）→ { user, token }
GET/auth/meJWT—当前个人资料
GET/auth/usersJWTrequireAdmin用户列表
POST/auth/change-passwordJWT—changePasswordSchema
POST/auth/set-initial-passwordJWT—首次登录（mustChangePassword）
POST/auth/admin-reset-passwordJWTrequireAdmin重置用户的密码

用户 - /api/users（routes/users.ts、authMiddleware）

方法路径RBAC说明
GET/usersrequireAdmin分页列表
GET/users/:idself/admin
PUT/PATCH/users/:idself/adminupdateUserSchema
DELETE/users/:idrequireAdmin
POST/DELETE/users/:id/avatarJWT头像上传/移除（multipart）

角色 - /api/roles（routes/roles.ts、authMiddleware）

方法路径RBAC说明
GET/roles/me/menu-sectionsJWT可见的侧边栏部分
GET/rolesrequireAdmin角色列表
GET/roles/:roleIdrequireAdmin详情（UUID）
POST/rolesrequireAdmin创建角色（createRoleSchema、isDefault=false）
PUT/roles/:roleIdrequireAdmin更新（原子权限替换）
PUT/roles/:roleId/menu-sectionsrequireAdmin菜单部分
DELETE/roles/:roleIdrequireAdmin
POST/roles/assignrequireAdmin给用户分配角色
POST/roles/revokerequireAdmin撤销角色

项目 - /api/projects（routes/projects.ts、authMiddleware）

方法路径RBAC许可证说明
GET/projectsJWT—分页列表
POST/projectsproject:createmax_projects创建
GET/projects/:projectIdrequireProjectAccess—
GET/projects/:projectId/usagerequireProjectAccess—使用统计
GET/projects/:projectId/exportrequireProjectAccess—存档流
PUT/projects/:projectIdrequireProjectAccess—
DELETE/projects/:projectIdrequireProjectAccess—软删除
POST/DELETE/projects/:projectId/accessrequireProjectAccess—ProjectAccess 管理

工作区 - /api/workspaces（routes/workspaces.ts、authMiddleware）

方法路径RBAC许可证说明
GET/workspacesJWT—列表
POST/workspacesworkspace:createmax_workspaces创建
GET/PUT/DELETE/workspaces/:workspaceIdrequireWorkspaceAccess—软删除
PUT/workspaces/:workspaceId/restorerequireWorkspaceAccess—恢复软删除
POST/workspaces/:workspaceId/accessrequireWorkspaceAccess—WorkspaceAccess
GET/POST/PUT/DELETE/workspaces/:workspaceId/folders[/:folderId]requireWorkspaceAccess—聊天文件夹
PUT/workspaces/:workspaceId/folders/:folderId/restorerequireWorkspaceAccess—

聊天 - 挂载于 /api/workspaces 下（routes/chat*.ts、authMiddleware）

方法路径RBAC说明
POST/workspaces/:id/chatrequireWorkspaceAccess非流式 → { chat, message }
POST/workspaces/:id/chat/streamrequireWorkspaceAccessSSE
GET/workspaces/:id/chatsrequireWorkspaceAccess分页列表（chatList.ts）
GET/workspaces/:id/chats/:chatId/messagesrequireWorkspaceAccess分页消息
PUT/workspaces/:id/chats/:chatIdrequireWorkspaceAccess重命名（chatCrud.ts）
PATCH/workspaces/:id/chats/:chatId/modelrequireWorkspaceAccess每个聊天的模型 { providerId?, model? }
PATCH/workspaces/:id/chats/:chatId/folderrequireWorkspaceAccess移动到文件夹
DELETE/workspaces/:id/chats/:chatIdrequireWorkspaceAccess
PUT/workspaces/:id/chats/:chatId/moverequireWorkspaceAccess重新排序
POST/DELETE/workspaces/:id/chats/:chatId/pinrequireWorkspaceAccess固定聊天
DELETE/PUT/workspaces/:id/chats/:chatId/messages/:messageIdrequireWorkspaceAccess删除/编辑消息
GET/workspaces/:id/agent-configrequireWorkspaceAccess工作区代理配置（chatAgentConfig.ts）
PUT/workspaces/:id/agent-configrequireWorkspaceAccess
GET/workspaces/:id/chats/exportrequireWorkspaceAccess导出（json/md/pdf）（chatExport.ts）
GET/workspaces/:id/chats/:chatId/exportrequireWorkspaceAccess
POST/workspaces/:id/chats/import/previewrequireWorkspaceAccess导入预览（chatImport.ts）
POST/workspaces/:id/chats/import/confirmrequireWorkspaceAccess确认导入
GET/workspaces/:id/chats/:chatId/tokensrequireWorkspaceAccess已用 token（chatTokens.ts）
GET/workspaces/:id/tokens/todayrequireWorkspaceAccess

SSE - /workspaces/:id/chat/stream

事件：token、status、citations（{ sources }）、done（{ chatId, messageId, modelUsed, providerUsed, mcpSources }）、error（{ error }），以及 plan 和 wiki_edit。

文档与上传（routes/documents.ts、routes/uploads.ts）

方法路径RBAC说明
GET/documentsJWT列表
GET/documents/:idJWT详情
GET/documents/:id/textJWT提取的文本
POST/documents/uploaddocument:writemultipart 上传
PUT/documents/:id/status（预中间件）Collector 回调
DELETE/documents/:iddocument:delete软删除
POST/uploadsdocument:write草稿暂存（uploads.ts）
POST/uploads/:id/assigndocument:write将草稿分配给工作区
GET/uploads/pendingdocument:write待处理草稿
DELETE/PATCH/uploads/:iddocument:write

API 密钥 - /api/api-keys（routes/apiKeys.ts、authMiddleware）

GET 列出您自己的密钥，POST 创建一个新密钥（原始 sk-... 密钥仅显示一次），DELETE /:keyId 撤销。

自 v0.20.1 起 API 密钥为 HMAC-SHA256：sk- 密钥不再使用 bcrypt 哈希，而是使用专用的 HMAC-SHA256 摘要（API_KEY_HMAC_SECRET，一个与 JWT/加密密钥轮换解耦的专用环境变量），验证是在 api_keys.key_hash（Postgres 唯一索引）上的索引化 O(1) 查找，而非 bcrypt 循环比较。v0.20.1 中的破坏性变更：操作员必须重新签发 widget/collector 密钥（见 docs/API_KEY_MIGRATION.md）。自 v0.22.0 起密钥比较（X-Api-Key cache-bust、X-Collector-Secret）为时序安全（crypto.timingSafeEqual 带长度保护）。密钥缺失/无效 → 401；服务器端 HMAC 配置错误 → 500（大声失败）。

Agent Skills - /api/agent（routes/skills.ts）

GET /api/agent/skills → 内置技能（rag_search、workspace_memory、document_temp_process）。

MCP 连接 - /api/mcp-connections（routes/mcp.ts、authMiddleware + requireAdmin）

GET 列表、GET /statuses（实时运行时）、POST 创建、PUT /:id（启用时自动断开/重连）、DELETE /:id、POST /:id/toggle、POST /:id/test（10 秒超时，toolCount）。

MCP Pins - /api/chats/:chatId/pins（routes/mcpPins.ts）

GET、POST（mcpPinCreateSchema）、DELETE /:pinId。

MCP 服务器入站（用于 IDE）- agent/mcpServer.ts

GET /api/mcp/sse（SSE 传输）、POST /api/mcp/message（JSON-RPC）。

市场 - /api/mcp-marketplace（routes/marketplace.ts、authMiddleware + requireAdmin）

GET 列表（查询 ?search、?category、?workspaceId 用于 isInstalled）、GET /:entryId、POST 创建条目、POST /:entryId/install、POST /:entryId/uninstall。见 07 - MCP Marketplace。

Providers / 模型 - /api/providers（routes/providers.ts、authMiddleware）

GET /models/available（前端选择器）、GET 列表、GET/:id、POST 创建、PUT/:id、DELETE/:id、PUT /:id/set-default、GET /:id/models、POST /:id/models/refresh（发现）、POST /:providerId/models/pull、PUT/DELETE /:providerId/models/:modelId、PUT /:providerId/models/:modelId/set-default。

Provider 预设 - /api/provider-presets（routes/providerPresets.ts）

GET 列表、GET /:presetId、POST /:presetId/install。

Widget（管理）- /api/widgets（routes/widgets.ts、authMiddleware + requireAdmin）

GET 列表、POST（许可证 widget_enabled + max_widgets）、GET/PUT/DELETE /:id、PUT /:id/workspaces（白名单）、GET /:id/workspaces、GET /:id/leads（分页）、GET /:id/leads/export（CSV、许可证 lead_export）、GET /:id/leads/:leadId。分析：GET /analytics/daily、/analytics/topics、/analytics/summary。

内部 Widget（嵌入）- /api/internal/widget（routes/internalWidget.ts、apiKeyMiddleware + widgetCors）

通过 API 密钥（X-Api-Key）认证。POST /search（RAG、通过 widgetId 防 IDOR）、POST /lead、GET /:id/config、GET /session/:token、POST /session、PATCH /session/:token/increment、PATCH /session/:token/chat/archive。见 06 - Widget Integration。

备份（routes/backups.ts、backupDestinations.ts、backupJobs.ts、restore.ts）

分组路径权限许可证
日志/api/system/backupsbackup:log:read—
目标/api/backup-destinationsbackup:destination:read/writemax_backup_destinations
任务/api/backup-jobsbackup:job:read/write—
恢复/api/backups、/api/backups/restore/:logId[/dry-run]backup:log:read / backup:restore:write—

POST /backup-jobs/:id/run（手动触发）、POST /backup-destinations/:id/test。

Webhooks - /api/webhooks（routes/webhooks.ts、authMiddleware + requireAdmin + requireFeature("webhooks")）

CRUD + POST /:id/test。HMAC-SHA256、指数退避重试（5 次尝试）、5 次失败后自动禁用。

推送 - /api/system/push（routes/push.ts）

GET /vapid-key（公钥）、POST/DELETE /subscribe（许可证 push_notifications）、POST /test（管理员）。

许可证 - /api/license（routes/license.ts）

GET /license/info（公开）→ { license, features }。

SSO - /api/sso（routes/sso.ts、authMiddleware + requireAdmin + requireFeature("sso_enabled")）

GET /config、PUT /config、POST /test。

模板 - /api/templates（routes/templates.ts、authMiddleware）

GET 列表、GET /:id、POST 创建、PUT/DELETE /:id（requireAdmin）。{{var}} 插值。

Settings - /api/system/settings（routes/settings.ts、authMiddleware + requireAdmin）

GET /embedding-config、GET /vector-db-config、GET settings、PUT settings（{ updated, rejected }）、POST/DELETE /branding/icon（许可证 white_label）。见 03 - Configuration。

系统 - /api/system（routes/system.ts）

GET /is-initialized（公开）、POST /initialize（设置向导，仅在未初始化时）、POST /reset-db（管理员）、POST /reindex-documents（管理员、RAG 重新索引）、POST /ocr/prewarm（管理员）。

审计 / 事件日志 - /api/event-logs（routes/eventLogs.ts、authMiddleware + requireAdmin + requireFeature("audit_log_immutable")）

GET 带过滤器（类型/用户/工作区/日期/操作）、游标分页。

分析 - /api/system/analytics（routes/analytics.ts、authMiddleware + requireAdmin）

GET /tokens、/models、/top-users。

存档 - /api/archives（routes/archives.ts + archivePages.ts、archiveConfig.ts、archiveSearch.ts、archiveGraph.ts、archiveExport.ts、archiveIndex.ts、archiveImport.ts、archiveSchemaTemplates.ts）

GET 列表、POST（archive:write）、GET/PUT/DELETE /:archiveId（删除需 archive:delete）、POST /from-template、POST /:archiveId/reindex。页面：GET/POST /:archiveId/pages、GET/PUT/DELETE /:archiveId/pages/:slug。配置、搜索（混合 RRF）、图谱、导出、索引、导入（copy-from-doc、import/:jobId、import/:jobId/callback）、schema 模板。

OCR - /api/ocr + /api/archives/:id/jobs（routes/ocr.ts、authMiddleware）

OCR 目录位于 /api/ocr。存档任务：GET /archives/:id/jobs、GET /:jobId、POST /:jobId/approve、POST /:jobId/reject、DELETE /:jobId、GET /:jobId/pages/:pageNumber/image（查询令牌认证）。

合成 - /api/synthesis（routes/synthesis.ts、authMiddleware）

GET /status、GET /pending/count、POST /trigger（archive:write + 功能限制）、GET /:runId、POST /:runId/approve、POST /:runId/reject、DELETE /:runId、PATCH /:runId/rename。

Wiki - /api/wiki-write、/api/wikilinks、/api/wiki-edits（routes/wikiChat.ts、wikilinks.ts）

POST /wiki-write/preview、POST /wiki-write/:runId/approve|reject|undo、GET /wiki-write/history/:archiveId、POST /wiki-write/distill。链接：POST /wikilinks/resolve、GET /wikilinks/:archiveId[/:pageSlug]、维护 GET/POST /wikilinks/maintenance/:archiveId[/merge]。

聊天保留 - /api/system/chat-retention（routes/chatRetention.ts）

PUT（system:write、confirmDataLoss: true、已审计）。见 03 - Configuration。

健康检查 - /（routes/health.ts）

GET /（公开、{ uptime }）、GET /api/health（公开、{ status, checks: { database, collector, disk } }）、GET /api/health/rag。

Widget Service - 端口 3211（packages/widget）

GET /health、GET /widget/:id.js（加载器）、GET /widget/:id（HTML iframe）、GET /api/config/:id（branding+trigger+lead）、POST /api/config/:id/cache-bust、POST /api/sessions（匿名会话）、POST /api/chat/:id/stream（SSE、x-session-token）、POST /api/lead/:id（线索捕获）。

Collector Service - 端口 3210（packages/collector）

GET /api/health、GET /api/ingest/chunks/:documentId、POST /api/ingest（X-Collector-Secret、multipart）、POST /api/ingest/query（向量搜索）、DELETE /api/ingest/:documentId、POST /api/ingest/reembed、POST /api/ingest/youtube、POST /api/ingest/wiki-pages、DELETE /api/ingest/wiki-pages/:pageId、POST /api/ingest/archive-page。

交叉链接