АРХИВА 26 Help

Программный интерфейс API

АРХИВА предоставляет REST API версии 3 — единый программный интерфейс для интеграций: SIEM-системы, HelpDesk, GRC, автоматизации ввода-вывода и собственных сценариев. Через API доступны те же операции, что и через интерфейс: поиск, действия над выборкой, экспорт, импорт, конфигурация, состояние, аудит, аналитика и граф переписки.

Открытая спецификация

Полная и актуальная для вашей установки спецификация доступна на самом сервере:

https://<сервер-архива>/api-docs/

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

Базовый адрес и группы

Единый префикс: https://<сервер-архива>/api/v3.

Группа

Назначение

/auth

Вход, выход, состояние сессии, двухфакторная регистрация

/setup

Мастер первичной настройки (только до первого входа)

/config

Разделы конфигурации: домены, тома, подключения, правила, роли, настройки поиска и т.д.

/status

Состояние системы, тома, процессы

/search

Поиск, сессии поиска, заморозка выборки, массовые действия (удержание, удаление, экспорт, пересылка, метки)

/blob

Чтение сообщений и вложений

/audit

Поиск по журналу аудита

/analytics

Аналитика

/analytics/graph/social

Построение социального графа переписки

/tag

Метки

/user

Пользовательские настройки

/imports

Импорт: возобновляемая закачка, каталог, подключения

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

API работает поверх сессии АРХИВА: клиент выполняет вход через группу /auth (логин/пароль, поддерживаются все настроенные способы входа), и последующие запросы выполняются с cookie сессии. На каждую операцию сервер проверяет право доступа роли — независимо от того, что интерфейс скрыл недоступные элементы. Роль без права получает 403.

Соглашения

Коды ответов предсказуемы — интеграция может принимать решения по коду, не разбирая тело:

Код

Значение

200

Выполнено, результат в теле

201

Создано (например, замороженная выборка)

202

Принято как фоновая задача — дальше наблюдайте по /status процессам

204

Выполнено без тела (синхронные операции с томами)

400

Некорректный запрос

401

Не аутентифицирован

403

Нет права (в том числе чужая выборка, отсутствие лицензии)

404

Ресурс не найден — в том числе любой запрос, не совпавший ни с одной операцией API

409

Состояние изменилось (выборка «уехала», число совпадений не совпало с подтверждённым)

422

Превышен лимит (например, выборка больше допустимого размера)

503

Служба временно недоступна (внешнее хранилище отвечает Retry-After)

507

Не хватает места в хранилище

Массовые операции (удержание, удаление, экспорт, пересылка, метки) над большой выборкой отвечают 202 с идентификатором задачи; прогресс и счётчики читаются по процессам. Порог «сразу или фоном» определяет сервер.

Защита от повторной отправки. Необратимые массовые операции поддерживают заголовок Idempotency-Key: повторный запрос с тем же ключом не выполняет действие повторно, а возвращает результат первого выполнения. Используйте ключ при любых запросах, которые могут быть отправлены повторно из-за сбоя сети.

Сессии поиска. Поиск возвращает токен сессии; по нему читаются страницы результатов, замораживается выборка (POST /search/{token}/freeze) и выполняются действия. Токен даёт доступ только к собственному поиску: чужой, истёкший или освобождённый токен отвечает 404. Глубокие страницы результатов открываются без замедлений: переход вглубь выдачи стоит столько же, сколько вторая страница.

Пример: поиск и заморозка выборки

POST /api/v3/search — запрос; ответ содержит токен сессии и первую страницу GET /api/v3/search/{token}/results — страницы результатов POST /api/v3/search/{token}/freeze — заморозка всего совпадения; ответ: 201 + id выборки POST /api/v3/search/actions/hold — удержание по selectionId (Idempotency-Key — от повторной отправки)

Точные схемы запросов — в открытой спецификации /api-docs/.

Связанные темы

17 November 2026