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`
Storage API (!)	`/put`, `/get`, `/check`, `/get-bulk`, порт `8444`	внутренний обмен содержимым писем между узлами	JWT `auth_token` с полем (`claim` (!)) `purpose`

Для внешних интеграций используйте WUI API. Storage API предназначен для внутренних соединений между узлами Клавдия.

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

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

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

администратор имеет полный доступ;
обычный пользователь работает со своими данными и письмами;
дополнительные ограничения задаются RBAC (!) через секции, например SECTION_ARCHIVE_MESSAGES и SECTION_SETTINGS, и действия can_list, can_view, can_edit_details, can_create, can_delete_entity, can_action_*.

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

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

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

При ответе 401 выполните повторный вход; при 403 проверьте права. Для длительной интеграции не используйте постоянное значение токена, скопированное из браузера. Пример регулярного опроса с получением новой сессии: ~~{{ССЫЛКА:install.integration-zabbix|~~Мониторинг через ~~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 -k -c cookies.txt -X POST https://127.0.0.1:8001/api/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"<пароль>"}'

# 2. Поиск по архиву с сохранённой cookie
curl -k -b cookies.txt 'https://127.0.0.1:8001/api/archive/search?q=договор&page=1'

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

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

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

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

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

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

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

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

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