API-Referenz
REST-API des Express-Servers (Port 3000, Präfix /api), mit interaktiver Swagger-UI und einer OpenAPI-Spec, die vom Server selbst ausgeliefert wird, hier nach Domäne dokumentiert mit ihren Authentifizierungsmechanismen, Rate-Limits und Antwortkonventionen.
REST-API des Express-Servers (Port 3000, Präfix /api), mit interaktiver Swagger-UI und einer OpenAPI-Spec, die vom Server selbst ausgeliefert wird, hier nach Domäne dokumentiert mit ihren Authentifizierungsmechanismen, Rate-Limits und Antwortkonventionen.
Authentifizierung
| Methode | Header | Verwendung |
|---|---|---|
| JWT | Authorization: Bearer <token> | Interne Benutzer (Frontend, Tauri) |
| API-Key | X-Api-Key: sk-... | Widget-Embed, programmatische Integrationen |
| Collector-Secret | X-Collector-Secret | Server↔collector (Vergleich in konstanter Zeit) |
| Query-Token | ?token= | OCR-Bildzugriff |
Middlewares (packages/server/src/middleware/): auth.ts, rbac.ts, license.ts, rateLimit.ts, widgetCors.ts.
Rate-Limit
| Limiter | Limit (prod/dev) | Bereich |
|---|---|---|
| general | 200 / 2000 req/min | IP |
| auth | 10 / 100 req/min | IP |
| probe | 10 / 100 req/min | IP |
| Widget-Chat | 30 / 200 req/min (pro-Widget-Override) | widgetId |
| Widget täglich | 5 / 50 Nachrichten pro Tag | widgetId + IP |
| Widget-Session | 50 / 500 Erstellungen pro Tag | IP |
| Widget-Lead | 3 / 30 pro Stunde | IP |
Es gibt keinen dedizierten Chat-Rate-Limiter: Der ReAct-Agent setzt seine eigenen Limits intern durch (Concurrency pro Benutzer, Token-Budgets, Wallclock-Timeouts - agentBudgetService.ts); der globale 200/min-Limiter bleibt das Sicherheitsnetz. Anfragen mit einem X-Widget-Id-Header umgehen den globalen Limiter (der Widget-Dienst drosselt sie vorgelagert); Widgets verwenden rateLimitPerMinute / sessionLimitPerDay als Pro-Widget-Overrides.
Antwortkonventionen
- Erfolg: JSON-Entität oder
{ ok: true }. - Fehler:
{ error: string }(+detailsfür Zod-Validierungsfehler). - Lizenz-Gating:
402 { error, feature, tier, limit?, current? }. - RBAC:
401(keine Authentifizierung),403(unzureichende Berechtigungen). - SSE:
event: <type>\ndata: <json>\n\n.
Auth - /api/auth (routes/auth.ts)
| Methode | Path | Auth | RBAC | Notizen |
|---|---|---|---|---|
| POST | /auth/register | public | — | Nur wenn ALLOW_REGISTRATION=true; Body registerSchema |
| POST | /auth/admin-register | JWT | requireAdmin | Body adminRegisterSchema |
| POST | /auth/login | public | — | Body loginSchema (safeParse → 400 bei ungültig) → { user, token } |
| GET | /auth/me | JWT | — | Aktuelles Profil |
| GET | /auth/users | JWT | requireAdmin | Benutzerliste |
| POST | /auth/change-password | JWT | — | changePasswordSchema |
| POST | /auth/set-initial-password | JWT | — | Erste Anmeldung (mustChangePassword) |
| POST | /auth/admin-reset-password | JWT | requireAdmin | Passwort eines Benutzers zurücksetzen |
Benutzer - /api/users (routes/users.ts, authMiddleware)
| Methode | Path | RBAC | Notizen |
|---|---|---|---|
| GET | /users | requireAdmin | Paginierte Liste |
| GET | /users/:id | self/admin | |
| PUT/PATCH | /users/:id | self/admin | updateUserSchema |
| DELETE | /users/:id | requireAdmin | |
| POST/DELETE | /users/:id/avatar | JWT | Avatar-Upload/-Entfernung (multipart) |
Rollen - /api/roles (routes/roles.ts, authMiddleware)
| Methode | Path | RBAC | Notizen |
|---|---|---|---|
| GET | /roles/me/menu-sections | JWT | Sichtbare Sidebar-Abschnitte |
| GET | /roles | requireAdmin | Rollenliste |
| GET | /roles/:roleId | requireAdmin | Detail (UUID) |
| POST | /roles | requireAdmin | Rolle erstellen (createRoleSchema, isDefault=false) |
| PUT | /roles/:roleId | requireAdmin | Update (atomarer Berechtigungsersatz) |
| PUT | /roles/:roleId/menu-sections | requireAdmin | Menüabschnitte |
| DELETE | /roles/:roleId | requireAdmin | |
| POST | /roles/assign | requireAdmin | Rolle einem Benutzer zuweisen |
| POST | /roles/revoke | requireAdmin | Rolle entziehen |
Projekte - /api/projects (routes/projects.ts, authMiddleware)
| Methode | Path | RBAC | Lizenz | Notizen |
|---|---|---|---|---|
| GET | /projects | JWT | — | Paginierte Liste |
| POST | /projects | project:create | max_projects | Erstellung |
| GET | /projects/:projectId | requireProjectAccess | — | |
| GET | /projects/:projectId/usage | requireProjectAccess | — | Nutzungsstatistiken |
| GET | /projects/:projectId/export | requireProjectAccess | — | Archiv-Stream |
| PUT | /projects/:projectId | requireProjectAccess | — | |
| DELETE | /projects/:projectId | requireProjectAccess | — | Soft Delete |
| POST/DELETE | /projects/:projectId/access | requireProjectAccess | — | ProjectAccess-Verwaltung |
Workspaces - /api/workspaces (routes/workspaces.ts, authMiddleware)
| Methode | Path | RBAC | Lizenz | Notizen |
|---|---|---|---|---|
| GET | /workspaces | JWT | — | Liste |
| POST | /workspaces | workspace:create | max_workspaces | Erstellung |
| GET/PUT/DELETE | /workspaces/:workspaceId | requireWorkspaceAccess | — | Soft Delete |
| PUT | /workspaces/:workspaceId/restore | requireWorkspaceAccess | — | Soft-Gelöschtes wiederherstellen |
| POST | /workspaces/:workspaceId/access | requireWorkspaceAccess | — | WorkspaceAccess |
| GET/POST/PUT/DELETE | /workspaces/:workspaceId/folders[/:folderId] | requireWorkspaceAccess | — | Chat-Ordner |
| PUT | /workspaces/:workspaceId/folders/:folderId/restore | requireWorkspaceAccess | — |
Chat - unter /api/workspaces gemountet (routes/chat*.ts, authMiddleware)
| Methode | Path | RBAC | Notizen |
|---|---|---|---|
| POST | /workspaces/:id/chat | requireWorkspaceAccess | Nicht-Streaming → { chat, message } |
| POST | /workspaces/:id/chat/stream | requireWorkspaceAccess | SSE |
| GET | /workspaces/:id/chats | requireWorkspaceAccess | Paginierte Liste (chatList.ts) |
| GET | /workspaces/:id/chats/:chatId/messages | requireWorkspaceAccess | Paginierte Nachrichten |
| PUT | /workspaces/:id/chats/:chatId | requireWorkspaceAccess | Umbenennen (chatCrud.ts) |
| PATCH | /workspaces/:id/chats/:chatId/model | requireWorkspaceAccess | Modell pro Chat { providerId?, model? } |
| PATCH | /workspaces/:id/chats/:chatId/folder | requireWorkspaceAccess | In Ordner verschieben |
| DELETE | /workspaces/:id/chats/:chatId | requireWorkspaceAccess | |
| PUT | /workspaces/:id/chats/:chatId/move | requireWorkspaceAccess | Neu sortieren |
| POST/DELETE | /workspaces/:id/chats/:chatId/pin | requireWorkspaceAccess | Chat anpinnen |
| DELETE/PUT | /workspaces/:id/chats/:chatId/messages/:messageId | requireWorkspaceAccess | Nachricht löschen/bearbeiten |
| GET | /workspaces/:id/agent-config | requireWorkspaceAccess | Agent-Config des 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 | Import-Vorschau (chatImport.ts) |
| POST | /workspaces/:id/chats/import/confirm | requireWorkspaceAccess | Import bestätigen |
| GET | /workspaces/:id/chats/:chatId/tokens | requireWorkspaceAccess | Verwendete Tokens (chatTokens.ts) |
| GET | /workspaces/:id/tokens/today | requireWorkspaceAccess |
SSE - /workspaces/:id/chat/stream
Ereignisse: token, status, citations ({ sources }), done ({ chatId, messageId, modelUsed, providerUsed, mcpSources }), error ({ error }), plus plan und wiki_edit.
Dokumente & Uploads (routes/documents.ts, routes/uploads.ts)
| Methode | Path | RBAC | Notizen |
|---|---|---|---|
| GET | /documents | JWT | Liste |
| GET | /documents/:id | JWT | Detail |
| GET | /documents/:id/text | JWT | Extrahierter Text |
| POST | /documents/upload | document:write | Multipart-Upload |
| PUT | /documents/:id/status | (Pre-Middleware) | Collector-Callback |
| DELETE | /documents/:id | document:delete | Soft Delete |
| POST | /uploads | document:write | Entwurfs-Staging (uploads.ts) |
| POST | /uploads/:id/assign | document:write | Entwurf einem Workspace zuweisen |
| GET | /uploads/pending | document:write | Ausstehende Entwürfe |
| DELETE/PATCH | /uploads/:id | document:write |
API-Keys - /api/api-keys (routes/apiKeys.ts, authMiddleware)
GET listet Ihre eigenen Keys, POST erstellt einen neuen (der rohe sk-...-Key wird nur einmal angezeigt), DELETE /:keyId widerruft.
Seit v0.20.1 sind API-Keys HMAC-SHA256: Der sk--Key wird nicht mehr bcrypt-gehasht, sondern mit einem dedizierten HMAC-SHA256-Digest (API_KEY_HMAC_SECRET, eine dedizierte Env-Var, entkoppelt von der JWT-/Verschlüsselungs-Schlüsselrotation) und die Verifikation ist eine indizierte O(1)-Lookup auf api_keys.key_hash (Postgres-Unique-Index), kein bcrypt-Loop-Vergleich. Breaking Change in v0.20.1: Betreiber müssen Widget-/Collector-Keys neu ausstellen (siehe docs/API_KEY_MIGRATION.md). Seit v0.22.0 sind Geheimnis-Vergleiche (X-Api-Key-Cache-Bust, X-Collector-Secret) timing-safe (crypto.timingSafeEqual mit Längenguard). Fehlender/ungültiger Key → 401; serverseitige HMAC-Fehlkonfiguration → 500 (lautes Scheitern).
Agent Skills - /api/agent (routes/skills.ts)
GET /api/agent/skills → eingebaute Skills (rag_search, workspace_memory, document_temp_process).
MCP-Verbindungen - /api/mcp-connections (routes/mcp.ts, authMiddleware + requireAdmin)
GET Liste, GET /statuses (Live-Runtime), POST erstellen, PUT /:id (Auto-Disconnect/Reconnect bei Aktivierung), DELETE /:id, POST /:id/toggle, POST /:id/test (10s-Timeout, toolCount).
MCP Pins - /api/chats/:chatId/pins (routes/mcpPins.ts)
GET, POST (mcpPinCreateSchema), DELETE /:pinId.
MCP-Server-Eingang (für IDEs) - agent/mcpServer.ts
GET /api/mcp/sse (SSE-Transport), POST /api/mcp/message (JSON-RPC).
Marketplace - /api/mcp-marketplace (routes/marketplace.ts, authMiddleware + requireAdmin)
GET Liste (Query ?search, ?category, ?workspaceId für isInstalled), GET /:entryId, POST Eintrag erstellen, POST /:entryId/install, POST /:entryId/uninstall. Siehe 07 - MCP Marketplace.
Provider / Modelle - /api/providers (routes/providers.ts, authMiddleware)
GET /models/available (Frontend-Auswahl), GET Liste, GET/:id, POST erstellen, PUT/:id, DELETE/:id, PUT /:id/set-default, GET /:id/models, POST /:id/models/refresh (Discovery), POST /:providerId/models/pull, PUT/DELETE /:providerId/models/:modelId, PUT /:providerId/models/:modelId/set-default.
Provider-Presets - /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 (Lizenz widget_enabled + max_widgets), GET/PUT/DELETE /:id, PUT /:id/workspaces (Whitelist), GET /:id/workspaces, GET /:id/leads (paginiert), GET /:id/leads/export (CSV, Lizenz lead_export), GET /:id/leads/:leadId. Analytics: GET /analytics/daily, /analytics/topics, /analytics/summary.
Internes Widget (Embed) - /api/internal/widget (routes/internalWidget.ts, apiKeyMiddleware + widgetCors)
Authentifizierung über API-Key (X-Api-Key). POST /search (RAG, IDOR-sicher via widgetId), POST /lead, GET /:id/config, GET /session/:token, POST /session, PATCH /session/:token/increment, PATCH /session/:token/chat/archive. Siehe 06 - Widget Integration.
Backup (routes/backups.ts, backupDestinations.ts, backupJobs.ts, restore.ts)
| Gruppe | Path | Berechtigungen | Lizenz |
|---|---|---|---|
| Logs | /api/system/backups | backup:log:read | — |
| Ziele | /api/backup-destinations | backup:destination:read/write | max_backup_destinations |
| Jobs | /api/backup-jobs | backup:job:read/write | — |
| Wiederherstellung | /api/backups, /api/backups/restore/:logId[/dry-run] | backup:log:read / backup:restore:write | — |
POST /backup-jobs/:id/run (manueller Trigger), POST /backup-destinations/:id/test.
Webhooks - /api/webhooks (routes/webhooks.ts, authMiddleware + requireAdmin + requireFeature("webhooks"))
CRUD + POST /:id/test. HMAC-SHA256, exponentieller Backoff-Retry (5 Versuche), Auto-Deaktivierung nach 5 Fehlern.
Push - /api/system/push (routes/push.ts)
GET /vapid-key (öffentlicher Schlüssel), POST/DELETE /subscribe (Lizenz push_notifications), POST /test (Admin).
Lizenz - /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 erstellen, PUT/DELETE /:id (requireAdmin). {{var}}-Interpolation.
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 (Lizenz white_label). Siehe 03 - Configuration.
System - /api/system (routes/system.ts)
GET /is-initialized (public), POST /initialize (Setup-Assistent, nur wenn nicht initialisiert), POST /reset-db (Admin), POST /reindex-documents (Admin, RAG-Reindex), POST /ocr/prewarm (Admin).
Audit / Ereignisprotokoll - /api/event-logs (routes/eventLogs.ts, authMiddleware + requireAdmin + requireFeature("audit_log_immutable"))
GET mit Filtern (Typ/Benutzer/Workspace/Datum/Aktion), Cursor-Pagination.
Analytics - /api/system/analytics (routes/analytics.ts, authMiddleware + requireAdmin)
GET /tokens, /models, /top-users.
Archive - /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 für Löschung), POST /from-template, POST /:archiveId/reindex. Seiten: GET/POST /:archiveId/pages, GET/PUT/DELETE /:archiveId/pages/:slug. Config, Suche (hybrides RRF), Graph, Export, Index, Import (copy-from-doc, import/:jobId, import/:jobId/callback), Schema-Templates.
OCR - /api/ocr + /api/archives/:id/jobs (routes/ocr.ts, authMiddleware)
OCR-Katalog auf /api/ocr. Archiv-Jobs: GET /archives/:id/jobs, GET /:jobId, POST /:jobId/approve, POST /:jobId/reject, DELETE /:jobId, GET /:jobId/pages/:pageNumber/image (Query-Token-Auth).
Synthesis - /api/synthesis (routes/synthesis.ts, authMiddleware)
GET /status, GET /pending/count, POST /trigger (archive:write + Feature-Limit), 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], Wartung GET/POST /wikilinks/maintenance/:archiveId[/merge].
Chat-Aufbewahrung - /api/system/chat-retention (routes/chatRetention.ts)
PUT (system:write, confirmDataLoss: true, auditiert). Siehe 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 (HTML-iframe), GET /api/config/:id (branding+trigger+lead), POST /api/config/:id/cache-bust, POST /api/sessions (anonyme Session), POST /api/chat/:id/stream (SSE, x-session-token), POST /api/lead/:id (Lead-Erfassung).
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 (Vektorsuche), 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
- Auth/RBAC-Details: 08 - Administration
- Widget-Embed-Anleitung: 06 - Widget Integration
- MCP-Lebenszyklus: 07 - MCP Marketplace