Référence API
API REST du serveur Express (port 3000, préfixe /api), avec une interface Swagger interactive et une spec OpenAPI servie par le serveur lui-même, documentée ici par domaine avec ses mécanismes d'authentification, ses limites de débit et ses conventions d…
API REST du serveur Express (port 3000, préfixe /api), avec une interface Swagger interactive et une spec OpenAPI servie par le serveur lui-même, documentée ici par domaine avec ses mécanismes d'authentification, ses limites de débit et ses conventions de réponse.
Authentification
| Méthode | Header | Utilisation |
|---|---|---|
| JWT | Authorization: Bearer <token> | Utilisateurs internes (frontend, Tauri) |
| Clé API | X-Api-Key: sk-... | Embarquement widget, intégrations programmatiques |
| Secret collector | X-Collector-Secret | Server↔collector (comparaison en temps constant) |
| Token de requête | ?token= | Accès aux images OCR |
Middlewares (packages/server/src/middleware/) : auth.ts, rbac.ts, license.ts, rateLimit.ts, widgetCors.ts.
Limites de débit
| Limiteur | Limite (prod/dev) | Portée |
|---|---|---|
| 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 par widget) | widgetId |
| widget daily | 5 / 50 messages par jour | widgetId+IP |
| widget session | 50 / 500 créations par jour | IP |
| widget lead | 3 / 30 par heure | IP |
Il n'y a pas de limiteur de débit dédié au chat : l'agent ReAct applique ses propres limites en interne (concurrence par utilisateur, budgets de tokens, timeouts wallclock - agentBudgetService.ts) ; le limiteur global de 200/min reste le filet de sécurité. Les requêtes portant un header X-Widget-Id contournent le limiteur global (le service widget les limite en amont) ; les widgets utilisent rateLimitPerMinute / sessionLimitPerDay comme overrides par widget.
Conventions de réponse
- Succès : entité JSON ou
{ ok: true }. - Erreur :
{ error: string }(+detailspour les erreurs de validation Zod). - Gating de licence :
402 { error, feature, tier, limit?, current? }. - RBAC :
401(pas d'authentification),403(permissions insuffisantes). - SSE :
event: <type>\ndata: <json>\n\n.
Auth - /api/auth (routes/auth.ts)
| Méthode | Path | Auth | RBAC | Notes |
|---|---|---|---|---|
| POST | /auth/register | public | — | Uniquement si ALLOW_REGISTRATION=true ; body registerSchema |
| POST | /auth/admin-register | JWT | requireAdmin | body adminRegisterSchema |
| POST | /auth/login | public | — | body loginSchema (safeParse → 400 si invalide) → { user, token } |
| GET | /auth/me | JWT | — | Profil courant |
| GET | /auth/users | JWT | requireAdmin | Liste des utilisateurs |
| POST | /auth/change-password | JWT | — | changePasswordSchema |
| POST | /auth/set-initial-password | JWT | — | Première connexion (mustChangePassword) |
| POST | /auth/admin-reset-password | JWT | requireAdmin | Réinitialiser le mot de passe d'un utilisateur |
Utilisateurs - /api/users (routes/users.ts, authMiddleware)
| Méthode | Path | RBAC | Notes |
|---|---|---|---|
| GET | /users | requireAdmin | Liste paginée |
| GET | /users/:id | self/admin | |
| PUT/PATCH | /users/:id | self/admin | updateUserSchema |
| DELETE | /users/:id | requireAdmin | |
| POST/DELETE | /users/:id/avatar | JWT | Upload/suppression avatar (multipart) |
Rôles - /api/roles (routes/roles.ts, authMiddleware)
| Méthode | Path | RBAC | Notes |
|---|---|---|---|
| GET | /roles/me/menu-sections | JWT | Sections de sidebar visibles |
| GET | /roles | requireAdmin | Liste des rôles |
| GET | /roles/:roleId | requireAdmin | Détail (UUID) |
| POST | /roles | requireAdmin | Créer un rôle (createRoleSchema, isDefault=false) |
| PUT | /roles/:roleId | requireAdmin | Mise à jour (remplacement atomique des permissions) |
| PUT | /roles/:roleId/menu-sections | requireAdmin | Sections de menu |
| DELETE | /roles/:roleId | requireAdmin | |
| POST | /roles/assign | requireAdmin | Attribuer un rôle à un utilisateur |
| POST | /roles/revoke | requireAdmin | Retirer un rôle |
Projets - /api/projects (routes/projects.ts, authMiddleware)
| Méthode | Path | RBAC | Licence | Notes |
|---|---|---|---|---|
| GET | /projects | JWT | — | Liste paginée |
| POST | /projects | project:create | max_projects | Création |
| GET | /projects/:projectId | requireProjectAccess | — | |
| GET | /projects/:projectId/usage | requireProjectAccess | — | Statistiques d'utilisation |
| GET | /projects/:projectId/export | requireProjectAccess | — | Flux d'archive |
| PUT | /projects/:projectId | requireProjectAccess | — | |
| DELETE | /projects/:projectId | requireProjectAccess | — | Suppression douce |
| POST/DELETE | /projects/:projectId/access | requireProjectAccess | — | Gestion ProjectAccess |
Workspaces - /api/workspaces (routes/workspaces.ts, authMiddleware)
| Méthode | Path | RBAC | Licence | Notes |
|---|---|---|---|---|
| GET | /workspaces | JWT | — | Liste |
| POST | /workspaces | workspace:create | max_workspaces | Création |
| GET/PUT/DELETE | /workspaces/:workspaceId | requireWorkspaceAccess | — | Suppression douce |
| PUT | /workspaces/:workspaceId/restore | requireWorkspaceAccess | — | Restaurer supprimé |
| POST | /workspaces/:workspaceId/access | requireWorkspaceAccess | — | WorkspaceAccess |
| GET/POST/PUT/DELETE | /workspaces/:workspaceId/folders[/:folderId] | requireWorkspaceAccess | — | Dossiers de chat |
| PUT | /workspaces/:workspaceId/folders/:folderId/restore | requireWorkspaceAccess | — |
Chat - monté sous /api/workspaces (routes/chat*.ts, authMiddleware)
| Méthode | Path | RBAC | Notes |
|---|---|---|---|
| POST | /workspaces/:id/chat | requireWorkspaceAccess | Non-streaming → { chat, message } |
| POST | /workspaces/:id/chat/stream | requireWorkspaceAccess | SSE |
| GET | /workspaces/:id/chats | requireWorkspaceAccess | Liste paginée (chatList.ts) |
| GET | /workspaces/:id/chats/:chatId/messages | requireWorkspaceAccess | Messages paginés |
| PUT | /workspaces/:id/chats/:chatId | requireWorkspaceAccess | Renommer (chatCrud.ts) |
| PATCH | /workspaces/:id/chats/:chatId/model | requireWorkspaceAccess | Modèle par chat { providerId?, model? } |
| PATCH | /workspaces/:id/chats/:chatId/folder | requireWorkspaceAccess | Déplacer vers un dossier |
| DELETE | /workspaces/:id/chats/:chatId | requireWorkspaceAccess | |
| PUT | /workspaces/:id/chats/:chatId/move | requireWorkspaceAccess | Réordonner |
| POST/DELETE | /workspaces/:id/chats/:chatId/pin | requireWorkspaceAccess | Épingler un chat |
| DELETE/PUT | /workspaces/:id/chats/:chatId/messages/:messageId | requireWorkspaceAccess | Supprimer/modifier un message |
| GET | /workspaces/:id/agent-config | requireWorkspaceAccess | Config d'agent du 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 | Aperçu d'import (chatImport.ts) |
| POST | /workspaces/:id/chats/import/confirm | requireWorkspaceAccess | Confirmer l'import |
| GET | /workspaces/:id/chats/:chatId/tokens | requireWorkspaceAccess | Tokens utilisés (chatTokens.ts) |
| GET | /workspaces/:id/tokens/today | requireWorkspaceAccess |
SSE - /workspaces/:id/chat/stream
Événements : token, status, citations ({ sources }), done ({ chatId, messageId, modelUsed, providerUsed, mcpSources }), error ({ error }), plus plan et wiki_edit.
Documents & uploads (routes/documents.ts, routes/uploads.ts)
| Méthode | Path | RBAC | Notes |
|---|---|---|---|
| GET | /documents | JWT | Liste |
| GET | /documents/:id | JWT | Détail |
| GET | /documents/:id/text | JWT | Texte extrait |
| POST | /documents/upload | document:write | Upload multipart |
| PUT | /documents/:id/status | (pré-middleware) | Callback collector |
| DELETE | /documents/:id | document:delete | Suppression douce |
| POST | /uploads | document:write | Staging brouillon (uploads.ts) |
| POST | /uploads/:id/assign | document:write | Assigner un brouillon à un workspace |
| GET | /uploads/pending | document:write | Brouillons en attente |
| DELETE/PATCH | /uploads/:id | document:write |
Clés API - /api/api-keys (routes/apiKeys.ts, authMiddleware)
GET liste vos propres clés, POST en crée une nouvelle (la clé brute sk-... n'est affichée qu'une seule fois), DELETE /:keyId révoque.
Depuis la v0.20.1 les clés API sont HMAC-SHA256 : la clé sk- n'est plus hachée avec bcrypt mais avec un digest HMAC-SHA256 dédié (API_KEY_HMAC_SECRET, une env var dédiée découplée de la rotation des clés JWT/chiffrement) et la vérification est une recherche indexée O(1) sur api_keys.key_hash (index unique Postgres), pas une comparaison en boucle bcrypt. Changement cassant dans v0.20.1 : les opérateurs doivent ré-émettre les clés widget/collector (voir docs/API_KEY_MIGRATION.md). Depuis la v0.22.0 les comparaisons de secrets (X-Api-Key cache-bust, X-Collector-Secret) sont timing-safe (crypto.timingSafeEqual avec garde de longueur). Clé manquante/invalide → 401 ; mauvaise configuration HMAC côté serveur → 500 (échec bruyant).
Agent Skills - /api/agent (routes/skills.ts)
GET /api/agent/skills → compétences intégrées (rag_search, workspace_memory, document_temp_process).
Connexions MCP - /api/mcp-connections (routes/mcp.ts, authMiddleware + requireAdmin)
GET liste, GET /statuses (runtime live), POST crée, PUT /:id (auto-déconnexion/reconnexion quand activé), DELETE /:id, POST /:id/toggle, POST /:id/test (timeout 10 s, toolCount).
MCP Pins - /api/chats/:chatId/pins (routes/mcpPins.ts)
GET, POST (mcpPinCreateSchema), DELETE /:pinId.
Entrée MCP Server (pour IDE) - agent/mcpServer.ts
GET /api/mcp/sse (transport SSE), POST /api/mcp/message (JSON-RPC).
Marketplace - /api/mcp-marketplace (routes/marketplace.ts, authMiddleware + requireAdmin)
GET liste (query ?search, ?category, ?workspaceId pour isInstalled), GET /:entryId, POST crée une entrée, POST /:entryId/install, POST /:entryId/uninstall. Voir 07 - MCP Marketplace.
Providers / Modèles - /api/providers (routes/providers.ts, authMiddleware)
GET /models/available (sélecteur frontend), GET liste, GET/:id, POST crée, PUT/:id, DELETE/:id, PUT /:id/set-default, GET /:id/models, POST /:id/models/refresh (découverte), POST /:providerId/models/pull, PUT/DELETE /:providerId/models/:modelId, PUT /:providerId/models/:modelId/set-default.
Presets Provider - /api/provider-presets (routes/providerPresets.ts)
GET liste, GET /:presetId, POST /:presetId/install.
Widget (admin) - /api/widgets (routes/widgets.ts, authMiddleware + requireAdmin)
GET liste, POST (licence widget_enabled + max_widgets), GET/PUT/DELETE /:id, PUT /:id/workspaces (whitelist), GET /:id/workspaces, GET /:id/leads (paginé), GET /:id/leads/export (CSV, licence lead_export), GET /:id/leads/:leadId. Analytics : GET /analytics/daily, /analytics/topics, /analytics/summary.
Widget interne (embarquement) - /api/internal/widget (routes/internalWidget.ts, apiKeyMiddleware + widgetCors)
Authentification via clé API (X-Api-Key). POST /search (RAG, sûr contre l'IDOR via widgetId), POST /lead, GET /:id/config, GET /session/:token, POST /session, PATCH /session/:token/increment, PATCH /session/:token/chat/archive. Voir 06 - Widget Integration.
Backup (routes/backups.ts, backupDestinations.ts, backupJobs.ts, restore.ts)
| Groupe | Path | Permissions | Licence |
|---|---|---|---|
| Logs | /api/system/backups | backup:log:read | — |
| Destinations | /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 (déclenchement manuel), POST /backup-destinations/:id/test.
Webhooks - /api/webhooks (routes/webhooks.ts, authMiddleware + requireAdmin + requireFeature("webhooks"))
CRUD + POST /:id/test. HMAC-SHA256, retry à backoff exponentiel (5 tentatives), auto-désactivation après 5 échecs.
Push - /api/system/push (routes/push.ts)
GET /vapid-key (clé publique), POST/DELETE /subscribe (licence push_notifications), POST /test (admin).
Licence - /api/license (routes/license.ts)
GET /license/info (public) → { 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 liste, GET /:id, POST crée, PUT/DELETE /:id (requireAdmin). Interpolation {{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 (licence white_label). Voir 03 - Configuration.
Système - /api/system (routes/system.ts)
GET /is-initialized (public), POST /initialize (assistant de configuration, uniquement quand non initialisé), POST /reset-db (admin), POST /reindex-documents (admin, réindexation RAG), POST /ocr/prewarm (admin).
Audit / journal d'événements - /api/event-logs (routes/eventLogs.ts, authMiddleware + requireAdmin + requireFeature("audit_log_immutable"))
GET avec filtres (type/utilisateur/workspace/date/action), pagination par curseur.
Analytics - /api/system/analytics (routes/analytics.ts, authMiddleware + requireAdmin)
GET /tokens, /models, /top-users.
Archives - /api/archives (routes/archives.ts + archivePages.ts, archiveConfig.ts, archiveSearch.ts, archiveGraph.ts, archiveExport.ts, archiveIndex.ts, archiveImport.ts, archiveSchemaTemplates.ts)
GET liste, POST (archive:write), GET/PUT/DELETE /:archiveId (archive:delete pour la suppression), POST /from-template, POST /:archiveId/reindex. Pages : GET/POST /:archiveId/pages, GET/PUT/DELETE /:archiveId/pages/:slug. Config, recherche (RRF hybride), graphe, export, index, import (copy-from-doc, import/:jobId, import/:jobId/callback), modèles de schéma.
OCR - /api/ocr + /api/archives/:id/jobs (routes/ocr.ts, authMiddleware)
Catalogue OCR sur /api/ocr. Jobs d'archive : GET /archives/:id/jobs, GET /:jobId, POST /:jobId/approve, POST /:jobId/reject, DELETE /:jobId, GET /:jobId/pages/:pageNumber/image (auth par token de requête).
Synthesis - /api/synthesis (routes/synthesis.ts, authMiddleware)
GET /status, GET /pending/count, POST /trigger (archive:write + limite de fonctionnalité), 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. Liens : POST /wikilinks/resolve, GET /wikilinks/:archiveId[/:pageSlug], maintenance GET/POST /wikilinks/maintenance/:archiveId[/merge].
Rétention des chats - /api/system/chat-retention (routes/chatRetention.ts)
PUT (system:write, confirmDataLoss: true, audité). Voir 03 - Configuration.
Health - / (routes/health.ts)
GET / (public, { uptime }), GET /api/health (public, { status, checks: { database, collector, disk } }), GET /api/health/rag.
Widget Service - port 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 (session anonyme), POST /api/chat/:id/stream (SSE, x-session-token), POST /api/lead/:id (capture de lead).
Collector Service - port 3210 (packages/collector)
GET /api/health, GET /api/ingest/chunks/:documentId, POST /api/ingest (X-Collector-Secret, multipart), POST /api/ingest/query (recherche vectorielle), 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
- Détail Auth/RBAC : 08 - Administration
- Comment intégrer le widget : 06 - Widget Integration
- Cycle de vie MCP : 07 - MCP Marketplace