Referência da API
API REST do servidor Express (porta 3000, prefixo /api), com interface Swagger interativa e spec OpenAPI servida pelo próprio servidor, documentada aqui por domínio com seus mecanismos de autenticação, limites de velocidade e convenções de resposta.
API REST do servidor Express (porta 3000, prefixo /api), com interface Swagger interativa e spec OpenAPI servida pelo próprio servidor, documentada aqui por domínio com seus mecanismos de autenticação, limites de velocidade e convenções de resposta.
Autenticação
| Método | Header | Uso |
|---|---|---|
| JWT | Authorization: Bearer <token> | Usuários internos (frontend, Tauri) |
| Chave de API | X-Api-Key: sk-... | Embed de widget, integrações programáticas |
| Segredo do collector | X-Collector-Secret | Server↔collector (comparação em tempo constante) |
| Token de consulta | ?token= | Acesso a imagens OCR |
Middlewares (packages/server/src/middleware/): auth.ts, rbac.ts, license.ts, rateLimit.ts, widgetCors.ts.
Limites de velocidade
| Limitador | Limite (prod/dev) | Escopo |
|---|---|---|
| general | 200 / 2000 req/min | IP |
| auth | 10 / 100 req/min | IP |
| probe | 10 / 100 req/min | IP |
| chat do widget | 30 / 200 req/min (override por widget) | widgetId |
| widget diário | 5 / 50 mensagens por dia | widgetId+IP |
| sessão widget | 50 / 500 criações por dia | IP |
| lead do widget | 3 / 30 por hora | IP |
Não há limitador de velocidade dedicado ao chat: o agente ReAct aplica seus próprios limites internamente (concorrência por usuário, orçamentos de tokens, timeouts wallclock - agentBudgetService.ts); o limitador global de 200/min permanece como rede de segurança. Requisições com header X-Widget-Id ignoram o limitador global (o serviço de widget limita antes); widgets usam rateLimitPerMinute / sessionLimitPerDay como overrides por widget.
Convenções de resposta
- Sucesso: entidade JSON ou
{ ok: true }. - Erro:
{ error: string }(+detailspara erros de validação Zod). - Gating de licença:
402 { error, feature, tier, limit?, current? }. - RBAC:
401(sem auth),403(permissões insuficientes). - SSE:
event: <type>\ndata: <json>\n\n.
Auth - /api/auth (routes/auth.ts)
| Método | Path | Auth | RBAC | Notas |
|---|---|---|---|---|
| POST | /auth/register | public | — | Apenas se ALLOW_REGISTRATION=true; body registerSchema |
| POST | /auth/admin-register | JWT | requireAdmin | body adminRegisterSchema |
| POST | /auth/login | public | — | body loginSchema (safeParse → 400 se inválido) → { user, token } |
| GET | /auth/me | JWT | — | Perfil atual |
| GET | /auth/users | JWT | requireAdmin | Lista de usuários |
| POST | /auth/change-password | JWT | — | changePasswordSchema |
| POST | /auth/set-initial-password | JWT | — | Primeiro login (mustChangePassword) |
| POST | /auth/admin-reset-password | JWT | requireAdmin | Redefinir a senha de um usuário |
Usuários - /api/users (routes/users.ts, authMiddleware)
| Método | Path | RBAC | Notas |
|---|---|---|---|
| GET | /users | requireAdmin | Lista paginada |
| GET | /users/:id | self/admin | |
| PUT/PATCH | /users/:id | self/admin | updateUserSchema |
| DELETE | /users/:id | requireAdmin | |
| POST/DELETE | /users/:id/avatar | JWT | Upload/remoção de avatar (multipart) |
Papéis - /api/roles (routes/roles.ts, authMiddleware)
| Método | Path | RBAC | Notas |
|---|---|---|---|
| GET | /roles/me/menu-sections | JWT | Seções visíveis da sidebar |
| GET | /roles | requireAdmin | Lista de papéis |
| GET | /roles/:roleId | requireAdmin | Detalhe (UUID) |
| POST | /roles | requireAdmin | Criar papel (createRoleSchema, isDefault=false) |
| PUT | /roles/:roleId | requireAdmin | Atualizar (substituição atômica de permissões) |
| PUT | /roles/:roleId/menu-sections | requireAdmin | Seções de menu |
| DELETE | /roles/:roleId | requireAdmin | |
| POST | /roles/assign | requireAdmin | Atribuir um papel a um usuário |
| POST | /roles/revoke | requireAdmin | Revogar um papel |
Projetos - /api/projects (routes/projects.ts, authMiddleware)
| Método | Path | RBAC | Licença | Notas |
|---|---|---|---|---|
| GET | /projects | JWT | — | Lista paginada |
| POST | /projects | project:create | max_projects | Criação |
| GET | /projects/:projectId | requireProjectAccess | — | |
| GET | /projects/:projectId/usage | requireProjectAccess | — | Estatísticas de uso |
| GET | /projects/:projectId/export | requireProjectAccess | — | Fluxo de arquivo |
| PUT | /projects/:projectId | requireProjectAccess | — | |
| DELETE | /projects/:projectId | requireProjectAccess | — | Soft delete |
| POST/DELETE | /projects/:projectId/access | requireProjectAccess | — | Gestão ProjectAccess |
Workspaces - /api/workspaces (routes/workspaces.ts, authMiddleware)
| Método | Path | RBAC | Licença | Notas |
|---|---|---|---|---|
| GET | /workspaces | JWT | — | Lista |
| POST | /workspaces | workspace:create | max_workspaces | Criação |
| GET/PUT/DELETE | /workspaces/:workspaceId | requireWorkspaceAccess | — | Soft delete |
| PUT | /workspaces/:workspaceId/restore | requireWorkspaceAccess | — | Restaurar soft-deleted |
| POST | /workspaces/:workspaceId/access | requireWorkspaceAccess | — | WorkspaceAccess |
| GET/POST/PUT/DELETE | /workspaces/:workspaceId/folders[/:folderId] | requireWorkspaceAccess | — | Pastas de chat |
| PUT | /workspaces/:workspaceId/folders/:folderId/restore | requireWorkspaceAccess | — |
Chat - montado sob /api/workspaces (routes/chat*.ts, authMiddleware)
| Método | Path | RBAC | Notas |
|---|---|---|---|
| POST | /workspaces/:id/chat | requireWorkspaceAccess | Não-streaming → { chat, message } |
| POST | /workspaces/:id/chat/stream | requireWorkspaceAccess | SSE |
| GET | /workspaces/:id/chats | requireWorkspaceAccess | Lista paginada (chatList.ts) |
| GET | /workspaces/:id/chats/:chatId/messages | requireWorkspaceAccess | Mensagens paginadas |
| PUT | /workspaces/:id/chats/:chatId | requireWorkspaceAccess | Renomear (chatCrud.ts) |
| PATCH | /workspaces/:id/chats/:chatId/model | requireWorkspaceAccess | Modelo por chat { providerId?, model? } |
| PATCH | /workspaces/:id/chats/:chatId/folder | requireWorkspaceAccess | Mover para pasta |
| DELETE | /workspaces/:id/chats/:chatId | requireWorkspaceAccess | |
| PUT | /workspaces/:id/chats/:chatId/move | requireWorkspaceAccess | Reordenar |
| POST/DELETE | /workspaces/:id/chats/:chatId/pin | requireWorkspaceAccess | Fixar chat |
| DELETE/PUT | /workspaces/:id/chats/:chatId/messages/:messageId | requireWorkspaceAccess | Excluir/editar mensagem |
| GET | /workspaces/:id/agent-config | requireWorkspaceAccess | Config de agente do workspace (chatAgentConfig.ts) |
| PUT | /workspaces/:id/agent-config | requireWorkspaceAccess | |
| GET | /workspaces/:id/chats/export | requireWorkspaceAccess | Export (json/md/pdf) (chatExport.ts) |
| GET | /workspaces/:id/chats/:chatId/export | requireWorkspaceAccess | |
| POST | /workspaces/:id/chats/import/preview | requireWorkspaceAccess | Prévia de import (chatImport.ts) |
| POST | /workspaces/:id/chats/import/confirm | requireWorkspaceAccess | Confirmar import |
| GET | /workspaces/:id/chats/:chatId/tokens | requireWorkspaceAccess | Tokens usados (chatTokens.ts) |
| GET | /workspaces/:id/tokens/today | requireWorkspaceAccess |
SSE - /workspaces/:id/chat/stream
Eventos: token, status, citations ({ sources }), done ({ chatId, messageId, modelUsed, providerUsed, mcpSources }), error ({ error }), além de plan e wiki_edit.
Documentos e uploads (routes/documents.ts, routes/uploads.ts)
| Método | Path | RBAC | Notas |
|---|---|---|---|
| GET | /documents | JWT | Lista |
| GET | /documents/:id | JWT | Detalhe |
| GET | /documents/:id/text | JWT | Texto extraído |
| POST | /documents/upload | document:write | Upload multipart |
| PUT | /documents/:id/status | (pre-middleware) | Callback do collector |
| DELETE | /documents/:id | document:delete | Soft delete |
| POST | /uploads | document:write | Staging de rascunhos (uploads.ts) |
| POST | /uploads/:id/assign | document:write | Atribuir rascunho a um workspace |
| GET | /uploads/pending | document:write | Rascunhos pendentes |
| DELETE/PATCH | /uploads/:id | document:write |
Chaves de API - /api/api-keys (routes/apiKeys.ts, authMiddleware)
GET lista suas próprias chaves, POST cria uma nova (a chave bruta sk-... é mostrada apenas uma vez), DELETE /:keyId revoga.
Desde v0.20.1 as chaves de API são HMAC-SHA256: a chave sk- não é mais hashada com bcrypt, mas com um digest HMAC-SHA256 dedicado (API_KEY_HMAC_SECRET, uma env var dedicada desacoplada da rotação de chaves JWT/criptografia) e a verificação é uma busca indexada O(1) em api_keys.key_hash (índice único do Postgres), não uma comparação em loop bcrypt. Mudança quebradora em v0.20.1: operadores devem reemitir chaves de widget/collector (ver docs/API_KEY_MIGRATION.md). Desde v0.22.0 as comparações de segredos (X-Api-Key cache-bust, X-Collector-Secret) são timing-safe (crypto.timingSafeEqual com proteção de comprimento). Chave ausente/inválida → 401; configuração HMAC incorreta no servidor → 500 (fail-loud).
Agent Skills - /api/agent (routes/skills.ts)
GET /api/agent/skills → skills integradas (rag_search, workspace_memory, document_temp_process).
Conexões MCP - /api/mcp-connections (routes/mcp.ts, authMiddleware + requireAdmin)
GET lista, GET /statuses (runtime ao vivo), POST criar, PUT /:id (auto-desconectar/reconectar quando ativado), DELETE /:id, POST /:id/toggle, POST /:id/test (timeout 10s, toolCount).
MCP Pins - /api/chats/:chatId/pins (routes/mcpPins.ts)
GET, POST (mcpPinCreateSchema), DELETE /:pinId.
Entrada do servidor MCP (para IDEs) - agent/mcpServer.ts
GET /api/mcp/sse (transporte SSE), POST /api/mcp/message (JSON-RPC).
Marketplace - /api/mcp-marketplace (routes/marketplace.ts, authMiddleware + requireAdmin)
GET lista (query ?search, ?category, ?workspaceId para isInstalled), GET /:entryId, POST criar entrada, POST /:entryId/install, POST /:entryId/uninstall. Ver 07 - MCP Marketplace.
Providers / Modelos - /api/providers (routes/providers.ts, authMiddleware)
GET /models/available (seletor do frontend), GET lista, GET/:id, POST criar, PUT/:id, DELETE/:id, PUT /:id/set-default, GET /:id/models, POST /:id/models/refresh (descoberta), POST /:providerId/models/pull, PUT/DELETE /:providerId/models/:modelId, PUT /:providerId/models/:modelId/set-default.
Presets de Provider - /api/provider-presets (routes/providerPresets.ts)
GET lista, GET /:presetId, POST /:presetId/install.
Widget (admin) - /api/widgets (routes/widgets.ts, authMiddleware + requireAdmin)
GET lista, POST (licença widget_enabled + max_widgets), GET/PUT/DELETE /:id, PUT /:id/workspaces (whitelist), GET /:id/workspaces, GET /:id/leads (paginado), GET /:id/leads/export (CSV, licença lead_export), GET /:id/leads/:leadId. Analytics: GET /analytics/daily, /analytics/topics, /analytics/summary.
Widget interno (embed) - /api/internal/widget (routes/internalWidget.ts, apiKeyMiddleware + widgetCors)
Autenticação via chave de API (X-Api-Key). POST /search (RAG, seguro contra IDOR via widgetId), POST /lead, GET /:id/config, GET /session/:token, POST /session, PATCH /session/:token/increment, PATCH /session/:token/chat/archive. Ver 06 - Widget Integration.
Backup (routes/backups.ts, backupDestinations.ts, backupJobs.ts, restore.ts)
| Grupo | Path | Permissões | Licença |
|---|---|---|---|
| Logs | /api/system/backups | backup:log:read | — |
| Destinos | /api/backup-destinations | backup:destination:read/write | max_backup_destinations |
| Jobs | /api/backup-jobs | backup:job:read/write | — |
| Restore | /api/backups, /api/backups/restore/:logId[/dry-run] | backup:log:read / backup:restore:write | — |
POST /backup-jobs/:id/run (disparo manual), POST /backup-destinations/:id/test.
Webhooks - /api/webhooks (routes/webhooks.ts, authMiddleware + requireAdmin + requireFeature("webhooks"))
CRUD + POST /:id/test. HMAC-SHA256, retry com backoff exponencial (5 tentativas), auto-desativação após 5 falhas.
Push - /api/system/push (routes/push.ts)
GET /vapid-key (chave pública), POST/DELETE /subscribe (licença push_notifications), POST /test (admin).
Licença - /api/license (routes/license.ts)
GET /license/info (público) → { license, features }.
SSO - /api/sso (routes/sso.ts, authMiddleware + requireAdmin + requireFeature("sso_enabled"))
GET /config, PUT /config, POST /test.
Templates - /api/templates (routes/templates.ts, authMiddleware)
GET lista, GET /:id, POST criar, PUT/DELETE /:id (requireAdmin). Interpolação {{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 (licença white_label). Ver 03 - Configuration.
Sistema - /api/system (routes/system.ts)
GET /is-initialized (público), POST /initialize (assistente de setup, apenas quando não inicializado), POST /reset-db (admin), POST /reindex-documents (admin, reindex RAG), POST /ocr/prewarm (admin).
Auditoria / Event log - /api/event-logs (routes/eventLogs.ts, authMiddleware + requireAdmin + requireFeature("audit_log_immutable"))
GET com filtros (tipo/usuário/workspace/data/ação), paginação por cursor.
Analytics - /api/system/analytics (routes/analytics.ts, authMiddleware + requireAdmin)
GET /tokens, /models, /top-users.
Arquivos - /api/archives (routes/archives.ts + archivePages.ts, archiveConfig.ts, archiveSearch.ts, archiveGraph.ts, archiveExport.ts, archiveIndex.ts, archiveImport.ts, archiveSchemaTemplates.ts)
GET lista, POST (archive:write), GET/PUT/DELETE /:archiveId (archive:delete para excluir), POST /from-template, POST /:archiveId/reindex. Páginas: GET/POST /:archiveId/pages, GET/PUT/DELETE /:archiveId/pages/:slug. Config, busca (RRF híbrido), grafo, export, índice, import (copy-from-doc, import/:jobId, import/:jobId/callback), templates de schema.
OCR - /api/ocr + /api/archives/:id/jobs (routes/ocr.ts, authMiddleware)
Catálogo OCR em /api/ocr. Jobs de arquivos: GET /archives/:id/jobs, GET /:jobId, POST /:jobId/approve, POST /:jobId/reject, DELETE /:jobId, GET /:jobId/pages/:pageNumber/image (auth por query token).
Synthesis - /api/synthesis (routes/synthesis.ts, authMiddleware)
GET /status, GET /pending/count, POST /trigger (archive:write + limite de feature), 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. Links: POST /wikilinks/resolve, GET /wikilinks/:archiveId[/:pageSlug], manutenção GET/POST /wikilinks/maintenance/:archiveId[/merge].
Retenção de chats - /api/system/chat-retention (routes/chatRetention.ts)
PUT (system:write, confirmDataLoss: true, auditado). Ver 03 - Configuration.
Health - / (routes/health.ts)
GET / (público, { uptime }), GET /api/health (público, { status, checks: { database, collector, disk } }), GET /api/health/rag.
Widget Service - porta 3211 (packages/widget)
GET /health, GET /widget/:id.js (loader), GET /widget/:id (iframe HTML), GET /api/config/:id (branding+trigger+lead), POST /api/config/:id/cache-bust, POST /api/sessions (sessão anônima), POST /api/chat/:id/stream (SSE, x-session-token), POST /api/lead/:id (captura de leads).
Collector Service - porta 3210 (packages/collector)
GET /api/health, GET /api/ingest/chunks/:documentId, POST /api/ingest (X-Collector-Secret, multipart), POST /api/ingest/query (busca vetorial), 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.
Cross-link
- Detalhe de Auth/RBAC: 08 - Administration
- Como incorporar o widget: 06 - Widget Integration
- Ciclo de vida MCP: 07 - MCP Marketplace