HTTP API и OpenAPI / Swagger

Назначение

Клавдий предоставляет HTTP API для программного управления архивом и интеграции со сторонними системами: CRM, службами поддержки, ИИ-агентами, средствами автоматизации и аналитики.

Спецификация публикуется в формате OpenAPI 3.0.3 и доступна через Swagger UI.

Где открыть спецификацию

Swagger UI встроен в веб-интерфейс и доступен по адресу:

https://<адрес-узла>:<порт-WUI>/swagger/index.html

Ссылка [Документация к API] также доступна на главной странице веб-интерфейса.

Файл openapi.yaml является источником истины для маршрутов, параметров и схем запросов и ответов. Его можно использовать с openapi-generator или swagger-codegen для генерации клиентского SDK.

Доступные API

API	Адрес	Назначение	Аутентификация
WUI API	`/api/...`, порт `8001`	поиск и просмотр архива, источники, задачи, настройки, кластер, пользователи	JWT в HttpOnly-cookie `access_token`

Для интеграций используйте HTTP API веб-интерфейса. Доступные маршруты, поля и форматы ответов проверяйте в Swagger установленной версии.

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

Выполните POST /api/login и передайте username и password.
Сервер вернёт JWT в HttpOnly-cookie access_token.
В браузере cookie передаётся автоматически. Другой клиент может передать его вручную заголовком Cookie: access_token=<jwt>.

Права запроса определяются учётной записью:

администратор имеет полный доступ;
обычный пользователь работает со своими данными и письмами;
дополнительные ограничения задаются правилами доступа к разделам, данным и действиям. Для интеграции выдавайте учётной записи только необходимые права.

См. {{ССЫЛКА:install.rbac|Правила доступа и RBAC}}.

Работа с длительной сессией

POST /api/login принимает username и password в JSON. Клиент должен сохранять cookie из ответа и учитывать её обновление сервером при продлении сессии. Маршрут обновления сессии и его параметры проверьте в Swagger установленной версии.

При ответе 401 выполните повторный вход; при 403 проверьте права. Для длительной интеграции не используйте постоянное значение токена, скопированное из браузера. Пример регулярного опроса с получением новой сессии: {{ССЫЛКА:install.integration-zabbix|Мониторинг через Zabbix}}.

Основные группы маршрутов

В спецификации OpenAPI маршруты сгруппированы по тегам. Имена тегов приводятся в точном виде:

Auth — вход и выход;
Dashboard — состояние, метрики и самопроверка;
Archive — поиск, просмотр писем и вложений, API-импорт PST/EML/MSG;
Sources — создание и проверка источников EWS/IMAP/SMTP, запуск сбора;
Tasks — очередь задач, отмена и возобновление;
Schedules — расписания задач;
Settings — общие настройки, поиск, оповещения, SMTP- и IMAP-серверы;
Cluster — узлы и группы кластера;
Users, Groups, Rights — пользователи, группы и правила доступа;
Storages, StorageGroups, StorageRules — хранилища, группы и правила хранения;
LDAP — LDAP/AD;
TLS, License, Solr — сертификаты, лицензия и экземпляры поиска.

Большинство маршрутов WUI API используют схему GET/POST /api/{domain}/{action}. Отдельно определены /api/login, /api/logout, /api/archive/messages/{id}/attachments/{aid}/download и /api/archive/ingest.

Пример: войти и выполнить поиск

# 1. Вход; cookie сохраняется в файл
curl --silent --show-error --fail-with-body \
  --cookie-jar cookies.txt \
  --header 'Content-Type: application/json' \
  --data '{"username":"<логин>","password":"<пароль>"}' \
  'https://klvd.example.ru:8001/api/login'

# 2. Поиск после завершённого входа
curl --silent --show-error --fail-with-body \
  --cookie cookies.txt --cookie-jar cookies.txt \
  --get --data-urlencode 'q=договор' --data 'page=1' \
  'https://klvd.example.ru:8001/api/archive/search'

Замените адрес, логин и пароль своими значениями. При внутреннем центре сертификации передайте доверенный CA через --cacert. Если ответ входа требует дополнительного кода, сначала завершите второй шаг; порядок входа с RADIUS описан в {{ССЫЛКА:reference.api|справочнике API}}. Используйте один и тот же адрес при входе и последующих запросах, чтобы сохранённая cookie подходила серверу.

Установка лицензии

POST /api/license/upload устанавливает лицензию платной редакции. Требуется право изменять настройки. Пользовательская инструкция: {{ССЫЛКА:install.licensing|Лицензирование и редакции}}.

Перед вызовом выполните вход, как показано выше, и сохраните cookie в cookies.txt. В примерах ниже используется https://klvd.example.ru:8001; замените его адресом своей установки. Для внутреннего центра сертификации укажите доверенный CA через --cacert.

Основной способ — загрузить исходный .lic как multipart/form-data (!) в поле license_file:

curl --silent --show-error --fail-with-body \
  --cookie cookies.txt --cookie-jar cookies.txt \
  --form 'license_file=@klavdii.lic' \
  'https://klvd.example.ru:8001/api/license/upload'

Альтернатива — передать содержимое файла в base64 в JSON-поле license_data_b64. Переносы строк внутри base64 допускаются. Для GNU/Linux пример без переносов:

base64 -w0 klavdii.lic > license.b64
python3 -c 'import json; from pathlib import Path; print(json.dumps({"license_data_b64": Path("license.b64").read_text()}))' > license-request.json
curl --silent --show-error --fail-with-body \
  --cookie cookies.txt --cookie-jar cookies.txt \
  --header 'Content-Type: application/json' \
  --data-binary @license-request.json \
  'https://klvd.example.ru:8001/api/license/upload'

Файлы license.b64 и license-request.json содержат ту же лицензию. После запроса удалите временные копии, если они больше не нужны.

Проверяйте не только HTTP-статус, но и тело ответа. Недействительная лицензия возвращает "ok": false и причину отказа; ранее установленная не заменяется. После успешной установки проверьте строку [Текущая лицензия] в веб-интерфейсе.

Собственный профиль пользователя

Эти вызовы относятся только к текущей учётной записи и доступны любому вошедшему пользователю. Они не дают права изменять чужие профили.

Вызов	Параметры	Назначение
`GET /api/user/profile`	—	логин, отображаемое имя, источник, группы, адреса почты и состояние двухфакторной аутентификации
`POST /api/user/save-profile`	`display_name`	изменить отображаемое имя локальной учётной записи
`POST /api/user/save-notification`	`notification_email`	указать адрес для оповещений
`GET /api/auth/mfa-setup`	—	получить `secret_base32`, ссылку `otpauth_uri` для приложения и срок настройки `expires_in` в секундах; настройка действует 10 минут
`POST /api/auth/mfa-enable`	`code`; для локальной учётной записи также `password`	включить TOTP
`POST /api/auth/mfa-disable`	`password` для локальной учётной записи или `code` для внешней	выключить TOTP

После изменения профиля повторно вызовите GET /api/user/profile и проверьте сохранённые значения. Порядок действий в интерфейсе: {{ССЫЛКА:user.profile|Просмотр и изменение профиля}} и {{ССЫЛКА:user.mfa|Включение и смена двухфакторной аутентификации}}.

Вход с кодом RADIUS

Дополнительный запрос кода после пароля RADIUS

Если RADIUS запросил код, POST /api/login возвращает:

{"ok": false, "radius_challenge": "<токен>", "message": "<сообщение сервера RADIUS>"}

Повторите POST /api/login с тем же username, кодом в поле password и полученным токеном в radius_challenge. Токен действует 5 минут. Покажите пользователю текст message, чтобы он понимал, какой код требуется.

RADIUS как второй фактор после пароля домена

После верного пароля домена POST /api/login возвращает:

{"ok": true, "mfa_required": true, "mfa_method": "radius"}

Продолжите вход вызовом POST /api/auth/mfa-verify, передав код в поле code. Если сервер запросил ещё один код, ответ содержит "error": "radius_challenge" и текст в message. Повторите проверку со следующим кодом и сохранённой сессией.

Проверьте окончательный результат входа и доступ к разрешённому API. Ответ mfa_required — промежуточный шаг, даже если в нём указано "ok": true.

Настройка режима RADIUS

Для POST /api/radius/options требуется право изменять настройки.

Параметр	Значения	Назначение
`mode`	`password`, `second_factor`	альтернативный пароль или второй фактор после пароля домена
`auto_create`	`true`, `false`	создавать учётную запись при первом входе через RADIUS; применяется в режиме `password`

Текущие настройки возвращает GET /api/radius/config в поле options. После изменения прочитайте их повторно и проверьте выбранную схему входа. Порядок настройки через интерфейс: {{ССЫЛКА:install.radius|RADIUS}}.

Примеры интеграций

CRM может находить связанную переписку по адресу или теме и получать вложения.
ИИ-агент может читать письма и вложения через поиск или API-импорт и использовать их для классификации и ответов на запросы.
Средства автоматизации могут запускать сбор, отслеживать задачи и передавать метрики в систему мониторинга.
BI-система может получать объёмы по ящикам через /api/dashboard/mailbox-volumes, времена обработки и состояние кластера.

Для программной интеграции создавайте отдельную учётную запись с минимально необходимыми правами вместо использования администратора.

Проверьте файл OpenAPI

python3 -c "import yaml; yaml.safe_load(open('openapi.yaml'))"

Связанные материалы

{{ССЫЛКА:install.rbac|Правила доступа и RBAC}}
{{ССЫЛКА:install.source-choose|Как выбрать способ сбора почты}}
{{ССЫЛКА:install.communigate|SMTP-форвардинг из CommuniGate Pro}}
{{ССЫЛКА:reference.errors-index|Коды ошибок}}

Навигация по книге

Следующая статья: {{ССЫЛКА:reference.network-ports|Порты и сетевые соединения}}