Справочник API

Все эндпоинты имеют префикс /api/v1, если не указано иное. Аутентификация — JWT Bearer-токен.

Интерактивная документация доступна на /docs (Swagger UI), пока сервер запущен. Swagger генерируется из route schemas Fastify, зарегистрированных в src/app.ts, OpenAPI server URL — /api/v1. Сгенерированная спецификация поддерживает английский, русский и украинский через /docs/json?lang=en|ru|uk.

Ошибки

Ответы с ошибкой используют единый конверт:

{
  "error": "ValidationError",
  "message": "Request validation failed",
  "statusCode": 422,
  "details": {}
}

details необязательное, появляется только когда маршрут или middleware отдают структурированную диагностику.

Аутентификация

Регистрация

POST /api/v1/auth/register

Тело: { "email": string, "password": string, "name": string, "departmentId": string } Ответ: { "token": string, "user": { id, email, name, role, departmentId } } Новые регистрации всегда создают роль employee. role от клиента не принимается.

Логин

POST /api/v1/auth/login

Тело: { "email": string, "password": string } Ответ: { "token": string, "user": { id, email, name, role, departmentId } }

Обновление токена

POST /api/v1/auth/refresh

Header: Authorization: Bearer <token> Ответ: { "token": string }

Forgot password

POST /api/v1/auth/forgot-password

Тело: { "email": string } Ответ всегда { "ok": true } — это защита от enumeration аккаунтов. Текущая реализация логирует reset-токен, доставка письма остаётся точкой интеграции с mailer.

Reset password

POST /api/v1/auth/reset-password

Тело: { "token": string, "newPassword": string } newPassword — минимум 8 символов, хотя бы одна буква и одна цифра. Ответ: { "ok": true }

Управление базой знаний

Список баз знаний

GET /api/v1/knowledge/bases

Query: ?departmentId=<id> (опционально; разрешён только в рамках эффективного отдела вызывающего). Доступ: любой аутентифицированный пользователь.

Получить базу знаний

GET /api/v1/knowledge/bases/:id

Доступ: любой аутентифицированный пользователь с доступом к отделу.

Создать базу знаний

POST /api/v1/knowledge/bases

Тело: { "name": string, "departmentId": string, "description"?: string } Доступ: любой аутентифицированный пользователь с доступом к отделу.

Обновить базу знаний

PATCH /api/v1/knowledge/bases/:id

Тело: { "name"?: string, "description"?: string|null } Доступ: любой аутентифицированный пользователь с доступом к отделу.

Обновить RAG-конфигурацию базы знаний

PATCH /api/v1/knowledge/bases/:id/config

Тело: { "ragWeights": { "vector": number, "keyword": number } } Доступ: право canUploadDocuments.

Удалить базу знаний

DELETE /api/v1/knowledge/bases/:id

Доступ: право canDeleteDocuments.

Список документов

GET /api/v1/knowledge/documents

Query: ?knowledgeBaseId=<id>&status=<status>&type=<type> Доступ: любой аутентифицированный пользователь.

Загрузить документ (файл)

POST /api/v1/knowledge/upload

Content-type: multipart/form-data Поля: file (binary), knowledgeBaseId (string), title (string). Доступ: любой аутентифицированный пользователь с доступом к отделу.

Принимаемые форматы: PDF, DOCX, TXT, изображения (PNG, JPG).

Создать документ (URL)

POST /api/v1/knowledge/documents

Тело: { "knowledgeBaseId": string, "title": string, "type": "url", "originalUrl": string } Доступ: любой аутентифицированный пользователь с доступом к отделу.

Обновить документ

PATCH /api/v1/knowledge/documents/:id

Тело: { "title"?: string, "originalUrl"?: string|null, "metadata"?: object } Доступ: любой аутентифицированный пользователь с доступом к отделу.

Получить документ

GET /api/v1/knowledge/documents/:id

Ответ включает метаданные документа и чанки, если они доступны. Доступ: любой аутентифицированный пользователь с доступом к отделу.

Переобработать документ

POST /api/v1/knowledge/documents/:id/reprocess

Отправляет документ на повторную ingestion. Доступ: любой аутентифицированный пользователь с доступом к отделу.

Удалить документ

DELETE /api/v1/knowledge/documents/:id

Доступ: право canDeleteDocuments.

Approvals (HITL)

Список pending-approvals

GET /api/v1/approvals

Query: ?departmentId=<id>&limit=<n>&offset=<n> Доступ: право canApprove (ограничение по отделу для не-глобальных пользователей).

Получить approval

GET /api/v1/approvals/:id

Ответ включает RAG-источники, использованные для ответа. Доступ: право canApprove.

Утвердить сообщение

POST /api/v1/approvals/:id/approve

Тело: { "editedContent"?: string } (опциональная правка перед утверждением). Доступ: право canApprove.

Отклонить сообщение

POST /api/v1/approvals/:id/reject

Тело: { "reason"?: string } Доступ: право canApprove.

Пакетное утверждение/отклонение

POST /api/v1/approvals/batch

Тело: { "decisions": [{ "approvalId": string, "action": "approve"|"reject", "editedContent"?: string, "reason"?: string }] } Максимум 50 решений на запрос. Доступ: право canApprove.

Эскалация

POST /api/v1/approvals/:id/escalate

Тело: { "escalatedToId": string, "reason"?: string } Доступ: право canEscalate.

Разговоры

Список разговоров

GET /api/v1/conversations

Query: ?departmentId=<id>&channel=<channel>&status=<status>&limit=<n>&offset=<n> Доступ: право canApprove (для не-глобальных пользователей ограничено отделом).

Получить сообщения

GET /api/v1/conversations/:id/messages

Query: ?cursor=<message-id>&limit=<n> Доступ: право canApprove (для не-глобальных пользователей ограничено отделом).

Профили сотрудников

Список профилей

GET /api/v1/employee-profiles

Доступ: любой аутентифицированный пользователь. Результаты ограничены эффективным department scope вызывающего; глобальные пользователи могут фильтровать по departmentId.

Получить профиль

GET /api/v1/employees/:userId/profile

Доступ: свой профиль или профиль в рамках эффективного отдела вызывающего.

Обновить профиль

PATCH /api/v1/employees/:userId/profile

Тело: { "summary"?: string, "currentProjects"?: string[], "preferences"?: object, "frequentIntents"?: string[], "accessLevel"?: string, "metadata"?: object } Доступ: свой профиль можно обновлять; для других видимых профилей нужно право canManageEmployeeProfiles.

Namespaces

Список namespaces

GET /api/v1/namespaces

Доступ: любой аутентифицированный пользователь (в рамках отдела).

Получить namespace

GET /api/v1/namespaces/:id

Доступ: любой аутентифицированный пользователь (в рамках отдела).

Создать namespace

POST /api/v1/namespaces

Тело: { "name": string, "departmentId": string, "systemPrompt"?: string, "persona"?: object, "config"?: object } Опциональный config.agentRunner задаёт адаптер namespace. Доступ: право canManageNamespaces.

Обновить namespace

PATCH /api/v1/namespaces/:id

Тело: { "name"?: string, "systemPrompt"?: string|null, "persona"?: object, "config"?: object } Доступ: право canManageNamespaces.

Удалить namespace

DELETE /api/v1/namespaces/:id

Доступ: право canManageNamespaces.

Intents

Список intent-имён

GET /api/v1/intents

Query: ?namespaceId=<id>&limit=<n>&offset=<n> Доступ: любой аутентифицированный пользователь с доступом к отделу namespace.

Получить матрицу доверия

GET /api/v1/intents/trust

Query: ?namespaceId=<id> Доступ: право canManageNamespaces.

Добавить пример intent

POST /api/v1/intents/examples

Тело: { "namespaceId": string, "intentName": string, "exampleText": string } Доступ: право canManageNamespaces.

Классифицировать текст

POST /api/v1/intents/classify

Тело: { "text": string, "namespaceId": string } Доступ: любой аутентифицированный пользователь.

RAG-тестирование

Draft-запрос

POST /api/v1/rag/draft

Тело: { "departmentId": string, "text": string } Ответ: { "answer": string, "sources": array, "injectionDetected": boolean, "injectionReason"?: string } Доступ: право canViewKnowledge.

Отделы

Список отделов

GET /api/v1/departments

Query: ?search=<text>&includeArchived=<bool>&limit=<n>&offset=<n> Доступ: любой аутентифицированный пользователь; результаты ограничены эффективными отделами пользователя.

Получить отдел

GET /api/v1/departments/:id

Доступ: любой аутентифицированный пользователь с доступом к этому отделу.

Создать отдел

POST /api/v1/departments

Тело: { "name": string, "slug"?: string, "color"?: string, "description"?: string|null, "settings"?: object } Доступ: право canManageDepartments.

Обновить отдел

PATCH /api/v1/departments/:id

Тело: { "name"?: string, "color"?: string, "description"?: string|null, "settings"?: object } Доступ: право canManageDepartments.

Архивировать отдел

POST /api/v1/departments/:id/archive

Soft-архив отдела. Доступ: право canArchiveDepartments.

Пользователи

Список пользователей

GET /api/v1/users

Query: ?role=<role>&departmentId=<id>&search=<text>&limit=<n>&offset=<n> Доступ: право canViewAllUsers.

Создать пользователя

POST /api/v1/users

Тело: { "email": string, "password": string, "name": string, "phone"?: string|null, "role"?: Role, "departmentId": string } Доступ: право canCreateUsers.

Получить пользователя

GET /api/v1/users/:id

Доступ: свой профиль или право canViewAllUsers в рамках эффективного отдела.

Обновить пользователя

PATCH /api/v1/users/:id

Тело: { "name"?: string, "phone"?: string|null, "role"?: Role, "roleId"?: string, "departmentId"?: string, "isActive"?: boolean } Доступ: пользователи могут обновлять поля своего профиля; для смены роли, отдела или active-состояния нужно право canManageUsers.

Деактивировать пользователя

DELETE /api/v1/users/:id

Soft-деактивация пользователя и инвалидация сессий. Доступ: право canManageUsers.

Эффективный доступ

GET /api/v1/users/:id/effective-access

Возвращает объект роли, overrides и вычисленные эффективные разрешения/отделы. Доступ: свой аккаунт или право canViewAllUsers в рамках эффективного отдела.

Аудит по пользователю

GET /api/v1/users/:id/audit

Доступ: право canViewAudit.

Override разрешений

POST   /api/v1/users/:id/permissions/grant
POST   /api/v1/users/:id/permissions/revoke
DELETE /api/v1/users/:id/permissions/grant/:permission
DELETE /api/v1/users/:id/permissions/revoke/:permission

Grant/revoke принимает либо { "permission": string }, либо { "departmentId": string }. Доступ: право canManageUsers.

Роли и разрешения

Каталог разрешений

GET /api/v1/permissions

Возвращает сгруппированные метаданные разрешений для редакторов ролей. Доступ: любой аутентифицированный пользователь.

Список ролей

GET /api/v1/roles

Query: ?search=<text>&includeSystem=<bool>&limit=<n>&offset=<n> Доступ: право canViewRoles.

Создать роль

POST /api/v1/roles

Тело: { "name": string, "slug"?: string, "allDepartments"?: boolean, "departmentIds"?: string[], "permissions"?: string[] } Доступ: право canManageRoles.

Получить роль

GET /api/v1/roles/:id

Доступ: право canViewRoles.

Обновить роль

PATCH /api/v1/roles/:id

Тело: { "name"?: string, "slug"?: string, "allDepartments"?: boolean, "departmentIds"?: string[], "permissions"?: string[] } Доступ: право canManageRoles.

Удалить роль

DELETE /api/v1/roles/:id

Системные роли и роли, назначенные пользователям, удалить нельзя. Доступ: право canManageRoles.

Журналы аудита

Список записей аудита

GET /api/v1/audit

Query: ?action=<action>&entityType=<type>&userId=<id>&limit=<n>&offset=<n> Доступ: право canViewAudit.

Трейсы

Получить трейс

GET /api/v1/traces/:trace_id

Ответ: AgentRun с retrieval hits. Доступ: любой аутентифицированный пользователь (для не-глобальных пользователей ограничено отделом).

Аналитический дашборд

GET /api/v1/analytics/dashboard

Query: ?days=<1-90>&departmentId=<id>&from=<datetime>&to=<datetime> Доступ: любой аутентифицированный пользователь (для не-глобальных пользователей ограничено отделом).

Текущий пользователь

Получить текущего пользователя

GET /api/v1/me

Возвращает текущего пользователя, отдел, профиль summary, объект роли, эффективные разрешения/отделы и UI capability flags. Доступ: любой аутентифицированный пользователь.

Смена пароля

POST /api/v1/me/change-password

Тело: { "currentPassword": string, "newPassword": string } Возвращает новый JWT после инкремента tokenVersion. Доступ: любой аутентифицированный пользователь.

Logout из всех сессий

POST /api/v1/me/logout-all

Инвалидирует существующие токены и рвёт активные WebSocket-сессии. Доступ: любой аутентифицированный пользователь.

Аватар

POST   /api/v1/me/avatar
DELETE /api/v1/me/avatar

Upload принимает один multipart image-файл (PNG, JPG или WebP, максимум 2 МБ) и сохраняет в /static/avatars/<user-id>.<ext>. Доступ: любой аутентифицированный пользователь.

Health

Health check

GET /api/v1/health

Аутентификация не требуется.

Agent tasks

Список agent tasks

GET /api/v1/agent-tasks

Query: ?namespaceId=<id>&departmentId=<id>&status=<status>&adapterType=<type>&from=<datetime>&to=<datetime>&limit=<n>&offset=<n> Значения status: queued, running, done, failed, timeout. Ответ: { items: AgentTask[], total: number, limit: number, offset: number }. Доступ: любой аутентифицированный пользователь.

Деталь agent task

GET /api/v1/agent-tasks/:id

Ответ включает вложенный массив toolCalls со step-level трейсом (stepName, status, inputData, outputData, durationMs, errorMessage). Доступ: любой аутентифицированный пользователь.

Статистика agent tasks

GET /api/v1/agent-tasks/stats

Query: ?namespaceId=<id>&departmentId=<id>&adapterType=<type>&from=<datetime>&to=<datetime> Ответ: { stats: [{ adapterType, namespaceId, total, successRate, avgDurationMs, avgCostUsd, byStatus }] }. Доступ: любой аутентифицированный пользователь.

Integration plugins

Список доступных плагинов

GET /api/v1/plugins

Возвращает метаданные встроенных и зарегистрированных плагинов. Доступ: любой аутентифицированный пользователь.

Список плагинов namespace

GET /api/v1/namespaces/:id/plugins

Доступ: право canManagePlugins или canManageNamespaces.

Включить плагин namespace

POST /api/v1/namespaces/:id/plugins/:pluginId

Тело: { "config"?: object, "enabled"?: boolean } Конфиг валидируется по Zod-схеме плагина. Доступ: право canManagePlugins или canManageNamespaces.

Обновить плагин namespace

PATCH /api/v1/namespaces/:id/plugins/:pluginId

Тело: { "config"?: object, "enabled"?: boolean } Доступ: право canManagePlugins или canManageNamespaces.

Отключить плагин namespace

DELETE /api/v1/namespaces/:id/plugins/:pluginId

Помечает namespace-плагин как отключённый и удаляет его из runtime-кеша реестра. Доступ: право canManagePlugins или canManageNamespaces.

Шаблоны документов

Список шаблонов

GET /api/v1/document-templates

Query: ?category=<category>&departmentId=<id>&limit=<n>&offset=<n> Доступ: любой аутентифицированный пользователь в рамках отдела.

Создать шаблон

POST /api/v1/document-templates

Тело: { "namespaceId": string, "departmentId"?: string|null, "name": string, "description"?: string|null, "category"?: "contract"|"proposal"|"letter"|"invoice"|"custom", "templateBody": string, "variables"?: array, "outputFormat"?: "md"|"html"|"docx"|"pdf" } Доступ: право canManageTemplates.

Обновить шаблон

PATCH /api/v1/document-templates/:id

Тело принимает те же редактируемые поля, что и create, кроме namespaceId. Доступ: право canManageTemplates.

Удалить шаблон

DELETE /api/v1/document-templates/:id

Доступ: право canManageTemplates.

Сгенерировать документ

POST /api/v1/document-templates/:id/generate

Тело: { "input"?: object, "preview"?: boolean, "outputFormat"?: "md"|"html"|"docx"|"pdf", "saveToKnowledgeBaseId"?: string|null } Экспорт md, html и docx реализован. pdf зарезервирован и сейчас возвращает 501. Доступ: право canGenerateDocuments.

История генераций

GET /api/v1/document-generations
GET /api/v1/document-generations/:id

Query-фильтры: ?userId=<id>&templateId=<id>&limit=<n>&offset=<n>. Пользователи видят только свою историю генераций, если у них нет прав на управление шаблонами отдела.

Notifications

Список уведомлений

GET /api/v1/notifications

Query: ?unreadOnly=<bool>&limit=<n>&offset=<n> Ответ включает items, pagination и unreadCount. Доступ: любой аутентифицированный пользователь.

Отметить прочитанным

PATCH /api/v1/notifications/:id/read

Доступ: только владелец.

Отметить всё прочитанным

POST /api/v1/notifications/read-all

Доступ: любой аутентифицированный пользователь.

Удалить уведомление

DELETE /api/v1/notifications/:id

Доступ: только владелец.

WebSocket

Agent task events

ws://<host>/ws/agent-tasks

Realtime-подписка на события жизненного цикла agent tasks по namespace.

Аутентификация: первое сообщение должно быть JSON auth handshake:

{ "action": "auth", "token": "<jwt>" }

При успехе сервер отвечает { "event": "authenticated", "payload": {} }. Любые другие сообщения до аутентификации отклоняются, соединение закрывается.

Сообщения клиента (после аутентификации):

{ "action": "subscribe", "namespaceId": "<id>" } — подписаться на namespace;
{ "action": "unsubscribe", "namespaceId": "<id>" } — отписаться (опустить namespaceId, чтобы отписаться от всех).

События сервера:

Событие	Payload
`agent-task.created`	`{ taskId, jobId, namespaceId, adapterType, status: "queued" }`
`agent-task.started`	`{ taskId, jobId, namespaceId, adapterType, status: "running" }`
`agent-task.tool-call`	`{ taskId, ..., progress, toolCall: { id, stepName, status, inputData, outputData, durationMs } }`
`agent-task.completed`	`{ taskId, ..., status: "done", output, durationMs }`
`agent-task.failed`	`{ taskId, ..., status: "failed"

JWT-токен отправляется в first-message handshake (никогда не в query parameter).

Notification events

ws://<host>/ws/notifications

Использует тот же first-message JWT handshake, что и agent task events. Сервер шлёт только уведомления текущего пользователя.

Admin

Bullboard queue dashboard

GET /admin/queues

Админский UI мониторинга очередей. Показывает все BullMQ-очереди (agent tasks, wa-inbound, wa-outbound, tg-inbound, tg-outbound, knowledge-ingest, memory-extraction). Доступ: право canEditSettings.

Channel endpoints

GET  /api/v1/whatsapp/status     # Connection status
GET  /api/v1/whatsapp/webhook    # Meta verification (hub.challenge)
POST /api/v1/whatsapp/webhook    # Inbound messages from Meta

GET  /api/v1/telegram/status     # Bot status

Справочник API

Ошибки​

Аутентификация​

Регистрация​

Логин​

Обновление токена​

Forgot password​

Reset password​

Управление базой знаний​

Список баз знаний​

Получить базу знаний​

Создать базу знаний​

Обновить базу знаний​

Обновить RAG-конфигурацию базы знаний​

Удалить базу знаний​

Список документов​

Загрузить документ (файл)​

Создать документ (URL)​

Обновить документ​

Получить документ​

Переобработать документ​

Удалить документ​

Approvals (HITL)​

Список pending-approvals​

Получить approval​

Утвердить сообщение​

Отклонить сообщение​

Пакетное утверждение/отклонение​

Эскалация​

Разговоры​

Список разговоров​

Получить сообщения​

Профили сотрудников​

Список профилей​

Получить профиль​

Обновить профиль​

Namespaces​

Список namespaces​

Получить namespace​

Создать namespace​

Обновить namespace​

Удалить namespace​

Intents​

Список intent-имён​

Получить матрицу доверия​

Добавить пример intent​

Классифицировать текст​

RAG-тестирование​

Draft-запрос​

Отделы​

Список отделов​

Получить отдел​

Создать отдел​

Обновить отдел​

Архивировать отдел​

Пользователи​

Список пользователей​

Создать пользователя​

Получить пользователя​

Обновить пользователя​

Деактивировать пользователя​

Эффективный доступ​

Аудит по пользователю​

Override разрешений​

Роли и разрешения​

Каталог разрешений​

Список ролей​

Создать роль​

Получить роль​

Обновить роль​

Удалить роль​

Журналы аудита​

Список записей аудита​

Трейсы​

Получить трейс​

Аналитический дашборд​

Текущий пользователь​

Получить текущего пользователя​

Смена пароля​

Logout из всех сессий​