Справочник API
REST API сервера Express (порт 3000, префикс /api) с интерактивным Swagger UI и OpenAPI-спецификацией, отдаваемой самим сервером, документированная здесь по доменам с её механизмами аутентификации, ограничениями скорости и соглашениями о ответах.
REST API сервера Express (порт 3000, префикс /api) с интерактивным Swagger UI и OpenAPI-спецификацией, отдаваемой самим сервером, документированная здесь по доменам с её механизмами аутентификации, ограничениями скорости и соглашениями о ответах.
Аутентификация
| Метод | Header | Использование |
|---|---|---|
| JWT | Authorization: Bearer <token> | Внутренние пользователи (frontend, Tauri) |
| API-ключ | X-Api-Key: sk-... | Встраивание виджета, программные интеграции |
| Secret коллектора | X-Collector-Secret | Server↔collector (сравнение за постоянное время) |
| Токен запроса | ?token= | Доступ к изображениям OCR |
Промежуточные обработчики (packages/server/src/middleware/): auth.ts, rbac.ts, license.ts, rateLimit.ts, widgetCors.ts.
Ограничение скорости
| Лимитер | Лимит (prod/dev) | Область |
|---|---|---|
| general | 200 / 2000 req/min | IP |
| auth | 10 / 100 req/min | IP |
| probe | 10 / 100 req/min | IP |
| чат виджета | 30 / 200 req/min (override на виджет) | widgetId |
| виджет в день | 5 / 50 сообщений в день | widgetId+IP |
| сессия виджета | 50 / 500 созданий в день | IP |
| лиды виджета | 3 / 30 в час | IP |
Отдельного лимитера для чата нет: ReAct-агент применяет собственные лимиты внутри (конкурентность на пользователя, токен-бюджеты, wallclock-таймауты - agentBudgetService.ts); глобальный лимитер 200/мин остаётся страховочной сетью. Запросы с заголовком X-Widget-Id пропускают глобальный лимитер (сервис виджета троттлит их выше по течению); виджеты используют rateLimitPerMinute / sessionLimitPerDay как override на виджет.
Соглашения об ответах
- Успех: JSON-сущность или
{ ok: true }. - Ошибка:
{ error: string }(+detailsдля ошибок валидации Zod). - Гейтинг лицензии:
402 { error, feature, tier, limit?, current? }. - RBAC:
401(нет аутентификации),403(недостаточно прав). - SSE:
event: <type>\ndata: <json>\n\n.
Auth - /api/auth (routes/auth.ts)
| Метод | Path | Auth | RBAC | Заметки |
|---|---|---|---|---|
| POST | /auth/register | public | — | Только если ALLOW_REGISTRATION=true; body registerSchema |
| POST | /auth/admin-register | JWT | requireAdmin | body adminRegisterSchema |
| POST | /auth/login | public | — | body loginSchema (safeParse → 400 при невалидности) → { user, token } |
| GET | /auth/me | JWT | — | Текущий профиль |
| GET | /auth/users | JWT | requireAdmin | Список пользователей |
| POST | /auth/change-password | JWT | — | changePasswordSchema |
| POST | /auth/set-initial-password | JWT | — | Первый вход (mustChangePassword) |
| POST | /auth/admin-reset-password | JWT | requireAdmin | Сброс пароля пользователя |
Пользователи - /api/users (routes/users.ts, authMiddleware)
| Метод | Path | RBAC | Заметки |
|---|---|---|---|
| GET | /users | requireAdmin | Список с пагинацией |
| GET | /users/:id | self/admin | |
| PUT/PATCH | /users/:id | self/admin | updateUserSchema |
| DELETE | /users/:id | requireAdmin | |
| POST/DELETE | /users/:id/avatar | JWT | Загрузка/удаление аватара (multipart) |
Роли - /api/roles (routes/roles.ts, authMiddleware)
| Метод | Path | RBAC | Заметки |
|---|---|---|---|
| GET | /roles/me/menu-sections | JWT | Видимые разделы сайдбара |
| GET | /roles | requireAdmin | Список ролей |
| GET | /roles/:roleId | requireAdmin | Детали (UUID) |
| POST | /roles | requireAdmin | Создать роль (createRoleSchema, isDefault=false) |
| PUT | /roles/:roleId | requireAdmin | Обновление (атомарная замена прав) |
| PUT | /roles/:roleId/menu-sections | requireAdmin | Разделы меню |
| DELETE | /roles/:roleId | requireAdmin | |
| POST | /roles/assign | requireAdmin | Назначить роль пользователю |
| POST | /roles/revoke | requireAdmin | Снять роль |
Проекты - /api/projects (routes/projects.ts, authMiddleware)
| Метод | Path | RBAC | Лицензия | Заметки |
|---|---|---|---|---|
| GET | /projects | JWT | — | Список с пагинацией |
| POST | /projects | project:create | max_projects | Создание |
| GET | /projects/:projectId | requireProjectAccess | — | |
| GET | /projects/:projectId/usage | requireProjectAccess | — | Статистика использования |
| GET | /projects/:projectId/export | requireProjectAccess | — | Поток архива |
| PUT | /projects/:projectId | requireProjectAccess | — | |
| DELETE | /projects/:projectId | requireProjectAccess | — | Мягкое удаление |
| POST/DELETE | /projects/:projectId/access | requireProjectAccess | — | Управление ProjectAccess |
Рабочие пространства - /api/workspaces (routes/workspaces.ts, authMiddleware)
| Метод | Path | RBAC | Лицензия | Заметки |
|---|---|---|---|---|
| GET | /workspaces | JWT | — | Список |
| POST | /workspaces | workspace:create | max_workspaces | Создание |
| GET/PUT/DELETE | /workspaces/:workspaceId | requireWorkspaceAccess | — | Мягкое удаление |
| PUT | /workspaces/:workspaceId/restore | requireWorkspaceAccess | — | Восстановить удалённое |
| POST | /workspaces/:workspaceId/access | requireWorkspaceAccess | — | WorkspaceAccess |
| GET/POST/PUT/DELETE | /workspaces/:workspaceId/folders[/:folderId] | requireWorkspaceAccess | — | Папки чатов |
| PUT | /workspaces/:workspaceId/folders/:folderId/restore | requireWorkspaceAccess | — |
Чат - смонтирован под /api/workspaces (routes/chat*.ts, authMiddleware)
| Метод | Path | RBAC | Заметки |
|---|---|---|---|
| POST | /workspaces/:id/chat | requireWorkspaceAccess | Без стриминга → { chat, message } |
| POST | /workspaces/:id/chat/stream | requireWorkspaceAccess | SSE |
| GET | /workspaces/:id/chats | requireWorkspaceAccess | Список с пагинацией (chatList.ts) |
| GET | /workspaces/:id/chats/:chatId/messages | requireWorkspaceAccess | Сообщения с пагинацией |
| PUT | /workspaces/:id/chats/:chatId | requireWorkspaceAccess | Переименовать (chatCrud.ts) |
| PATCH | /workspaces/:id/chats/:chatId/model | requireWorkspaceAccess | Модель на чат { providerId?, model? } |
| PATCH | /workspaces/:id/chats/:chatId/folder | requireWorkspaceAccess | Переместить в папку |
| DELETE | /workspaces/:id/chats/:chatId | requireWorkspaceAccess | |
| PUT | /workspaces/:id/chats/:chatId/move | requireWorkspaceAccess | Переупорядочить |
| POST/DELETE | /workspaces/:id/chats/:chatId/pin | requireWorkspaceAccess | Закрепить чат |
| DELETE/PUT | /workspaces/:id/chats/:chatId/messages/:messageId | requireWorkspaceAccess | Удалить/изменить сообщение |
| GET | /workspaces/:id/agent-config | requireWorkspaceAccess | Конфиг агента пространства (chatAgentConfig.ts) |
| PUT | /workspaces/:id/agent-config | requireWorkspaceAccess | |
| GET | /workspaces/:id/chats/export | requireWorkspaceAccess | Экспорт (json/md/pdf) (chatExport.ts) |
| GET | /workspaces/:id/chats/:chatId/export | requireWorkspaceAccess | |
| POST | /workspaces/:id/chats/import/preview | requireWorkspaceAccess | Предпросмотр импорта (chatImport.ts) |
| POST | /workspaces/:id/chats/import/confirm | requireWorkspaceAccess | Подтвердить импорт |
| GET | /workspaces/:id/chats/:chatId/tokens | requireWorkspaceAccess | Использованные токены (chatTokens.ts) |
| GET | /workspaces/:id/tokens/today | requireWorkspaceAccess |
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)
| Метод | Path | RBAC | Заметки |
|---|---|---|---|
| GET | /documents | JWT | Список |
| GET | /documents/:id | JWT | Детали |
| GET | /documents/:id/text | JWT | Извлечённый текст |
| POST | /documents/upload | document:write | Загрузка multipart |
| PUT | /documents/:id/status | (pre-middleware) | Callback коллектора |
| DELETE | /documents/:id | document:delete | Мягкое удаление |
| POST | /uploads | document:write | Стадирование черновиков (uploads.ts) |
| POST | /uploads/:id/assign | document:write | Назначить черновик пространству |
| GET | /uploads/pending | document:write | Ожидающие черновики |
| DELETE/PATCH | /uploads/:id | document: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, выделенная env-переменная, отвязанная от ротации ключей JWT/шифрования), и проверка — это индексированный O(1)-поиск по api_keys.key_hash (уникальный индекс Postgres), а не сравнение в цикле bcrypt. Ломающее изменение в v0.20.1: операторы должны перевыпустить ключи виджета/коллектора (см. docs/API_KEY_MIGRATION.md). С v0.22.0 сравнения секретов (X-Api-Key cache-bust, X-Collector-Secret) timing-safe (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 (живой runtime), 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).
Marketplace - /api/mcp-marketplace (routes/marketplace.ts, authMiddleware + requireAdmin)
GET список (query ?search, ?category, ?workspaceId для isInstalled), GET /:entryId, POST создать запись, POST /:entryId/install, POST /:entryId/uninstall. См. 07 - MCP Marketplace.
Провайдеры / Модели - /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.
Пресеты провайдеров - /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 (whitelist), GET /:id/workspaces, GET /:id/leads (с пагинацией), GET /:id/leads/export (CSV, лицензия lead_export), GET /:id/leads/:leadId. Аналитика: GET /analytics/daily, /analytics/topics, /analytics/summary.
Внутренний виджет (встраивание) - /api/internal/widget (routes/internalWidget.ts, apiKeyMiddleware + widgetCors)
Аутентификация через API-ключ (X-Api-Key). POST /search (RAG, IDOR-безопасно через widgetId), 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)
| Группа | Path | Разрешения | Лицензия |
|---|---|---|---|
| Логи | /api/system/backups | backup:log:read | — |
| Назначения | /api/backup-destinations | backup:destination:read/write | max_backup_destinations |
| Задания | /api/backup-jobs | backup: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 сбоев.
Push - /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), шаблоны схем.
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 (аутентификация токеном запроса).
Synthesis - /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.
Health - / (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.
Cross-link
- Детали Auth/RBAC: 08 - Administration
- Как встроить виджет: 06 - Widget Integration
- Жизненный цикл MCP: 07 - MCP Marketplace