Referencia de API
API REST del servidor Express (puerto 3000, prefijo /api), con una interfaz Swagger interactiva y una spec OpenAPI servida por el propio servidor, documentada aquí por dominio con sus mecanismos de autenticación, límites de velocidad y convenciones de re…
API REST del servidor Express (puerto 3000, prefijo /api), con una interfaz Swagger interactiva y una spec OpenAPI servida por el propio servidor, documentada aquí por dominio con sus mecanismos de autenticación, límites de velocidad y convenciones de respuesta.
Autenticación
| Método | Header | Uso |
|---|---|---|
| JWT | Authorization: Bearer <token> | Usuarios internos (frontend, Tauri) |
| API key | X-Api-Key: sk-... | Embed de widget, integraciones programáticas |
| Secreto collector | X-Collector-Secret | Server↔collector (comparación en tiempo constante) |
| Token de consulta | ?token= | Acceso a imágenes OCR |
Middlewares (packages/server/src/middleware/): auth.ts, rbac.ts, license.ts, rateLimit.ts, widgetCors.ts.
Límites de velocidad
| Limitador | Límite (prod/dev) | Ámbito |
|---|---|---|
| general | 200 / 2000 req/min | IP |
| auth | 10 / 100 req/min | IP |
| probe | 10 / 100 req/min | IP |
| chat widget | 30 / 200 req/min (override por widget) | widgetId |
| widget diario | 5 / 50 mensajes por día | widgetId+IP |
| sesión widget | 50 / 500 creaciones por día | IP |
| widget lead | 3 / 30 por hora | IP |
No hay limitador de velocidad dedicado al chat: el agente ReAct aplica sus propios límites internamente (concurrencia por usuario, presupuestos de tokens, timeouts wallclock - agentBudgetService.ts); el limitador global de 200/min sigue siendo la red de seguridad. Las peticiones con header X-Widget-Id se saltan el limitador global (el servicio widget las limita aguas arriba); los widgets usan rateLimitPerMinute / sessionLimitPerDay como overrides por widget.
Convenciones de respuesta
- Éxito: entidad JSON o
{ ok: true }. - Error:
{ error: string }(+detailspara errores de validación Zod). - Gating de licencia:
402 { error, feature, tier, limit?, current? }. - RBAC:
401(sin auth),403(permisos insuficientes). - SSE:
event: <type>\ndata: <json>\n\n.
Auth - /api/auth (routes/auth.ts)
| Método | Path | Auth | RBAC | Notas |
|---|---|---|---|---|
| POST | /auth/register | public | — | Solo si ALLOW_REGISTRATION=true; body registerSchema |
| POST | /auth/admin-register | JWT | requireAdmin | body adminRegisterSchema |
| POST | /auth/login | public | — | body loginSchema (safeParse → 400 si inválido) → { user, token } |
| GET | /auth/me | JWT | — | Perfil actual |
| GET | /auth/users | JWT | requireAdmin | Lista de usuarios |
| POST | /auth/change-password | JWT | — | changePasswordSchema |
| POST | /auth/set-initial-password | JWT | — | Primer login (mustChangePassword) |
| POST | /auth/admin-reset-password | JWT | requireAdmin | Reiniciar contraseña de un usuario |
Usuarios - /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 | Subida/eliminación avatar (multipart) |
Roles - /api/roles (routes/roles.ts, authMiddleware)
| Método | Path | RBAC | Notas |
|---|---|---|---|
| GET | /roles/me/menu-sections | JWT | Secciones visibles de la sidebar |
| GET | /roles | requireAdmin | Lista de roles |
| GET | /roles/:roleId | requireAdmin | Detalle (UUID) |
| POST | /roles | requireAdmin | Crear rol (createRoleSchema, isDefault=false) |
| PUT | /roles/:roleId | requireAdmin | Actualizar (reemplazo atómico de permisos) |
| PUT | /roles/:roleId/menu-sections | requireAdmin | Secciones de menú |
| DELETE | /roles/:roleId | requireAdmin | |
| POST | /roles/assign | requireAdmin | Asignar un rol a un usuario |
| POST | /roles/revoke | requireAdmin | Revocar un rol |
Proyectos - /api/projects (routes/projects.ts, authMiddleware)
| Método | Path | RBAC | Licencia | Notas |
|---|---|---|---|---|
| GET | /projects | JWT | — | Lista paginada |
| POST | /projects | project:create | max_projects | Creación |
| GET | /projects/:projectId | requireProjectAccess | — | |
| GET | /projects/:projectId/usage | requireProjectAccess | — | Estadísticas de uso |
| GET | /projects/:projectId/export | requireProjectAccess | — | Stream de archivo |
| PUT | /projects/:projectId | requireProjectAccess | — | |
| DELETE | /projects/:projectId | requireProjectAccess | — | Soft delete |
| POST/DELETE | /projects/:projectId/access | requireProjectAccess | — | Gestión ProjectAccess |
Workspaces - /api/workspaces (routes/workspaces.ts, authMiddleware)
| Método | Path | RBAC | Licencia | Notas |
|---|---|---|---|---|
| GET | /workspaces | JWT | — | Lista |
| POST | /workspaces | workspace:create | max_workspaces | Creación |
| 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 | — | Carpetas de chat |
| PUT | /workspaces/:workspaceId/folders/:folderId/restore | requireWorkspaceAccess | — |
Chat - montado bajo /api/workspaces (routes/chat*.ts, authMiddleware)
| Método | Path | RBAC | Notas |
|---|---|---|---|
| POST | /workspaces/:id/chat | requireWorkspaceAccess | No-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 | Mensajes paginados |
| PUT | /workspaces/:id/chats/:chatId | requireWorkspaceAccess | Renombrar (chatCrud.ts) |
| PATCH | /workspaces/:id/chats/:chatId/model | requireWorkspaceAccess | Modelo por chat { providerId?, model? } |
| PATCH | /workspaces/:id/chats/:chatId/folder | requireWorkspaceAccess | Mover a carpeta |
| DELETE | /workspaces/:id/chats/:chatId | requireWorkspaceAccess | |
| PUT | /workspaces/:id/chats/:chatId/move | requireWorkspaceAccess | Reordenar |
| POST/DELETE | /workspaces/:id/chats/:chatId/pin | requireWorkspaceAccess | Fijar chat |
| DELETE/PUT | /workspaces/:id/chats/:chatId/messages/:messageId | requireWorkspaceAccess | Borrar/editar mensaje |
| GET | /workspaces/:id/agent-config | requireWorkspaceAccess | Config de agente del 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 | Vista previa 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 }), más plan y wiki_edit.
Documentos y subidas (routes/documents.ts, routes/uploads.ts)
| Método | Path | RBAC | Notas |
|---|---|---|---|
| GET | /documents | JWT | Lista |
| GET | /documents/:id | JWT | Detalle |
| GET | /documents/:id/text | JWT | Texto extraído |
| POST | /documents/upload | document:write | Subida multipart |
| PUT | /documents/:id/status | (pre-middleware) | Callback del collector |
| DELETE | /documents/:id | document:delete | Soft delete |
| POST | /uploads | document:write | Staging de borradores (uploads.ts) |
| POST | /uploads/:id/assign | document:write | Asignar borrador a un workspace |
| GET | /uploads/pending | document:write | Borradores pendientes |
| DELETE/PATCH | /uploads/:id | document:write |
API keys - /api/api-keys (routes/apiKeys.ts, authMiddleware)
GET lista tus propias claves, POST crea una nueva (la clave cruda sk-... se muestra una sola vez), DELETE /:keyId revoca.
Desde v0.20.1 las API keys son HMAC-SHA256: la clave sk- ya no se hashea con bcrypt sino con un digest HMAC-SHA256 dedicado (API_KEY_HMAC_SECRET, una env var dedicada desacoplada de la rotación de claves JWT/cifrado) y la verificación es una búsqueda indexada O(1) en api_keys.key_hash (índice único de Postgres), no una comparación en bucle bcrypt. Cambio ruptura en v0.20.1: los operadores deben re-emitir las claves widget/collector (ver docs/API_KEY_MIGRATION.md). Desde v0.22.0 las comparaciones de secretos (X-Api-Key cache-bust, X-Collector-Secret) son timing-safe (crypto.timingSafeEqual con guarda de longitud). Clave ausente/inválida → 401; mala configuración HMAC del lado del servidor → 500 (fail-loud).
Agent Skills - /api/agent (routes/skills.ts)
GET /api/agent/skills → skills integradas (rag_search, workspace_memory, document_temp_process).
Conexiones MCP - /api/mcp-connections (routes/mcp.ts, authMiddleware + requireAdmin)
GET lista, GET /statuses (runtime en vivo), POST crear, PUT /:id (auto-desconexión/reconexión cuando está activado), 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 del 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 crear entrada, POST /:entryId/install, POST /:entryId/uninstall. Ver 07 - MCP Marketplace.
Providers / Modelos - /api/providers (routes/providers.ts, authMiddleware)
GET /models/available (selector del frontend), GET lista, GET/:id, POST crear, PUT/:id, DELETE/:id, PUT /:id/set-default, GET /:id/models, POST /:id/models/refresh (descubrimiento), 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 (licencia widget_enabled + max_widgets), GET/PUT/DELETE /:id, PUT /:id/workspaces (whitelist), GET /:id/workspaces, GET /:id/leads (paginado), GET /:id/leads/export (CSV, licencia 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)
Autenticación vía API key (X-Api-Key). POST /search (RAG, seguro contra IDOR vía 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 | Permisos | Licencia |
|---|---|---|---|
| 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 (disparador manual), POST /backup-destinations/:id/test.
Webhooks - /api/webhooks (routes/webhooks.ts, authMiddleware + requireAdmin + requireFeature("webhooks"))
CRUD + POST /:id/test. HMAC-SHA256, retry con backoff exponencial (5 intentos), auto-desactivación tras 5 fallos.
Push - /api/system/push (routes/push.ts)
GET /vapid-key (clave pública), POST/DELETE /subscribe (licencia push_notifications), POST /test (admin).
Licencia - /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 crear, PUT/DELETE /:id (requireAdmin). Interpolación {{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 (licencia white_label). Ver 03 - Configuration.
Sistema - /api/system (routes/system.ts)
GET /is-initialized (público), POST /initialize (asistente de setup, solo cuando no está inicializado), POST /reset-db (admin), POST /reindex-documents (admin, reindex RAG), POST /ocr/prewarm (admin).
Audit / Event log - /api/event-logs (routes/eventLogs.ts, authMiddleware + requireAdmin + requireFeature("audit_log_immutable"))
GET con filtros (tipo/usuario/workspace/fecha/acción), paginación por cursor.
Analytics - /api/system/analytics (routes/analytics.ts, authMiddleware + requireAdmin)
GET /tokens, /models, /top-users.
Archivos - /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 borrar), POST /from-template, POST /:archiveId/reindex. Páginas: GET/POST /:archiveId/pages, GET/PUT/DELETE /:archiveId/pages/:slug. Config, búsqueda (RRF híbrido), grafo, export, índice, import (copy-from-doc, import/:jobId, import/:jobId/callback), plantillas de schema.
OCR - /api/ocr + /api/archives/:id/jobs (routes/ocr.ts, authMiddleware)
Catálogo OCR en /api/ocr. Jobs de archivos: 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 + límite 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. Enlaces: POST /wikilinks/resolve, GET /wikilinks/:archiveId[/:pageSlug], mantenimiento GET/POST /wikilinks/maintenance/:archiveId[/merge].
Retención 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 - puerto 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 (sesión anónima), POST /api/chat/:id/stream (SSE, x-session-token), POST /api/lead/:id (captura de leads).
Collector Service - puerto 3210 (packages/collector)
GET /api/health, GET /api/ingest/chunks/:documentId, POST /api/ingest (X-Collector-Secret, multipart), POST /api/ingest/query (búsqueda vectorial), 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
- Detalle de Auth/RBAC: 08 - Administration
- Cómo integrar el widget: 06 - Widget Integration
- Ciclo de vida MCP: 07 - MCP Marketplace