Главная / Документация / APIAPI: администрированиеМаршруты администрирования volrix.pm: настройки, копии, журналы, лицензия, API-ключи, LDAP и OIDC, мониторинг, кластер и автотесты.Обновлено 16.10.2026Группа для администраторов и систем эксплуатации: почта и системные настройки, журналы аудита и ошибок, резервные копии, автотесты, очистка данных, расписание, хранилище файлов, LDAP, OIDC, HTTPS, лицензия, API-ключи, каталог прав, конструктор документов, оформление, мониторинг и состояние кластера.**Что принимает API-ключ.** Почти все маршруты группы - по скоупам из таблиц. Операции здесь меняют доступ и данные всей установки: восстановление из копии, очистка данных, смена хранилища. Давайте ключам этой группы только скоупы чтения, а изменения выполняйте в интерфейсе или на тестовом стенде.Базовый адрес, формат ответов и коды ошибок описаны в статье API: адрес, первый запрос и ответы, выпуск ключа и вход под пользователем - в статье API: вход, токен и API-ключи. В примерах ключ лежит в переменной окружения VOLRIX_API_KEY, токен пользователя - в VOLRIX_TOKEN.Типовой сценарий: мониторинг установки

Живость GET /api/v1/health без авторизации отвечает {"status": "ok"}, пока процесс работает.

Готовность GET /api/v1/ready без авторизации: 200 {"status": "ready"}, когда база доступна и ее схема соответствует версии приложения, иначе 503 {"status": "not_ready"}. Этого маршрута нет в Swagger.

Состояние компонентов GET /api/v1/monitoring/health (monitoring:read) - проверки по компонентам; хост и ряды метрик - /monitoring/host, /monitoring/series.

Кластер GET /api/v1/admin/cluster (dashboard:read) - снимок узлов, ролей и предупреждений; на одном сервере в ответе mode=standalone. Подробности - в разделе «Состояние кластера» ниже.

Метрики Prometheus GET /metrics (вне /api/v1). Если на сервере задан METRICS_TOKEN, передайте его в Authorization: Bearer, иначе 401.

Резервное копирование по расписанию настраивается в PUT /admin/backups/settings; ручной запуск - POST /admin/backups/run (backups:create), проверка копии - POST /admin/backups/{filename}/verify (backups:verify).Примеры запросовПроверка доступности для внешнего мониторинга:curl -sS -o /dev/null -w "%{http_code}\n" https://ваш-адрес/api/v1/readyВход пользователей за сутки из журнала аудита по ключу (скоуп audit_log:read). Ответ AuditLogList: items, total, page, page_size, pages:curl --fail-with-body -sS \ -H "X-Api-Key: $VOLRIX_API_KEY" \ "https://ваш-адрес/api/v1/admin/audit-log?action_type=login&date_from=2026-09-26&date_to=2026-09-26&page_size=200"МаршрутыКак читать колонку «Доступ»: **скоуп вида users:read** - маршрут принимает API-ключ, если в ключе есть этот скоуп, а у сотрудника, выпустившего ключ, есть такое же право в роли (users.read). Если скоупов несколько через «+», нужны все. **Только сессия** - нужен заголовок Authorization: Bearer, API-ключ получит 403. **Без авторизации** - заголовки не нужны. Доступ к конкретному объекту (участие в проекте, права на папку Диска) сервер проверяет дополнительно. Пути в таблицах указаны полностью, от корня сервера.Системные настройки

Метод и путь

Параметры и тело

Доступ (скоуп ключа)

Успешный ответ

GET /api/v1/system/settings/smtp

Нет

smtp:read

200: SmtpSettings

PUT /api/v1/system/settings/smtp

Нет | Тело: application/json: SmtpSettingsUpdate

smtp:update

200: SmtpSettings

POST /api/v1/system/smtp/test

Нет | Тело: application/json: SmtpTestRequest

smtp:test

200: SmtpTestResponse

GET /api/v1/system/settings/email-notifications

Нет

smtp:read

200: EmailCustomizationOut

PUT /api/v1/system/settings/email-notifications

Нет | Тело: application/json: EmailCustomizationIn

smtp:update

200: EmailCustomizationOut

GET /api/v1/system/settings/documentation-links

Нет

Только сессия

200: DocumentationLinksOut

PUT /api/v1/system/settings/documentation-links

Нет | Тело: application/json: DocumentationLinksIn

branding:update

200: DocumentationLinksOut

GET /api/v1/system/settings/overtime

Нет

Только сессия

200: OvertimeSettingsOut

PUT /api/v1/system/settings/overtime

Нет | Тело: application/json: OvertimeSettingsIn

rate_cards:update

200: OvertimeSettingsOut

GET /api/v1/system/settings/presentation-design

Нет

branding:read

200: PresentationDesignSettings

PUT /api/v1/system/settings/presentation-design

Нет | Тело: application/json: PresentationDesignSettings

branding:update

200: PresentationDesignSettings

GET /api/v1/system/settings/reports-visibility

Нет

branding:read

200: ReportsVisibilityOut

PUT /api/v1/system/settings/reports-visibility

Нет | Тело: application/json: ReportsVisibilityIn

branding:update

200: ReportsVisibilityOut

GET /api/v1/system/settings/telegram-bot

Нет

smtp:read

200: TelegramBotSettings

PUT /api/v1/system/settings/telegram-bot

Нет | Тело: application/json: TelegramBotSettingsUpdate

smtp:update

200: TelegramBotSettings

GET /api/v1/system/settings/mail-providers

Нет

smtp:read

200: array[MailProviderAppRead]

PUT /api/v1/system/settings/mail-providers

Нет | Тело: application/json: MailProviderAppIn

smtp:update

200: MailProviderAppRead

GET /api/v1/system/settings/shared-mailbox-access

Нет

mailbox:read_settings

200: object

POST /api/v1/system/settings/shared-mailbox-access

Нет | Тело: application/json: SharedMailboxAccessIn

mailbox:update_settings

201: object

DELETE /api/v1/system/settings/shared-mailbox-access/{person_id}

person_id [path обяз.]: string (uuid)

mailbox:update_settings

204

GET /api/v1/system/settings/mail-cache

Нет

Только сессия

200: object

PUT /api/v1/system/settings/mail-cache

Нет | Тело: application/json: MailCacheIn

mailbox:update_settings

200: object

Журнал аудита и состояние системы

Метод и путь

Параметры и тело

Доступ (скоуп ключа)

Успешный ответ

GET /api/v1/admin/audit-log

action_type [query]: string / null; user_id [query]: string (uuid) / null; module [query]: string / null; entity_type [query]: string / null; date_from [query]: string (date) / null; date_to [query]: string (date) / null; search [query]: string / null; page [query]: integer (default=1, min=1); page_size [query]: integer (default=50, min=1, max=200)

audit_log:read

200: AuditLogList

GET /api/v1/admin/dashboard

Нет

dashboard:read

200: DashboardResponse

GET /api/v1/admin/cluster

Нет

dashboard:read

200: object

**GET /admin/cluster.** Схема кластера для экрана «Администрирование» → «Наблюдение» → «Кластер»; право то же, что у состояния системы, ничего не меняется. Снимок собирает ведущий планировщик раз в 20 секунд и кладет в общее хранилище, поэтому ответ одинаков с любого узла и маршрут не опрашивает кластер на каждый запрос. Если свежего снимка еще нет, он собирается при обращении.

Поле ответа

Когда есть

Что значит

mode

всегда

standalone - установка на одном сервере; cluster - отказоустойчивый кластер

всегда

Время снимка (ISO 8601)

processes

всегда

Живые процессы backend: id, node (имя узла), pid, version, image, started_at, scheduler_leader (держит ли процесс планировщик), at (последняя отметка). Отметка обновляется каждые 15 секунд, пропавший процесс исчезает через 45

node

только standalone

Имя этого сервера

name, public_url

только cluster

Название кластера и адрес входа

vip

cluster, если задан виртуальный адрес

address, ok (отвечает ли адрес), holder (какой балансировщик его держит), ms (время ответа)

lb, app

только cluster

Балансировщики (порт 443) и узлы приложения (порт 8080): name, address, port, ok, ms, error

только cluster

Серверы PostgreSQL по данным Patroni: role (leader, sync_standby и т. д.), state, lag (отставание реплики в байтах), timeline, pending_restart, version, ok

etcd

только cluster

Узлы etcd: name, address, port, ok, ms

warnings

только cluster

Предупреждения для администратора: массив {level, text}, level - danger, warning или info

spec

всегда

Описание кластера из настроек: name, vip, public_url и nodes; null на одном сервере

Что превращается в предупреждение: меньше трех узлов, не отвечает виртуальный адрес (danger), нет основного сервера PostgreSQL или синхронной реплики (danger), отставание реплики больше 16 МБ, etcd без кворума (danger), разные версии приложения на узлах, нет ведущего планировщика (фоновые задачи не выполняются). Тот же список читайте на экране «Кластер».Резервные копии

Метод и путь

Параметры и тело

Доступ (скоуп ключа)

Успешный ответ

GET /api/v1/admin/backups

Нет

backups:read

200: object

GET /api/v1/admin/backups/scheduler

Нет

backups:read

200: object

GET /api/v1/admin/backups/settings

Нет

backups:read

200: object

PUT /api/v1/admin/backups/settings

Нет | Тело: application/json: BackupSettingsUpdate

backups:manage_schedule

200: object

POST /api/v1/admin/backups/run

Нет

backups:create

200: object

GET /api/v1/admin/backups/{filename}/download

filename [path обяз.]: string

backups:download

200: object

DELETE /api/v1/admin/backups/{filename}

filename [path обяз.]: string

backups:delete

200: object

POST /api/v1/admin/backups/{filename}/verify

filename [path обяз.]: string

backups:verify

200: object

POST /api/v1/admin/backups/{filename}/restore

filename [path обяз.]: string | Тело: application/json: RestoreRequest

backups:restore

200: object

Автотесты и диагностика

Метод и путь

Параметры и тело

Доступ (скоуп ключа)

Успешный ответ

GET /api/v1/admin/tests/selfcheck

Нет

tests:run

200: array[DiagnosticCheck]

GET /api/v1/admin/tests/api-coverage

Нет

tests:run

200: ApiCoverage

GET /api/v1/admin/tests/security

Нет

tests:run

200: array[DiagnosticCheck]

GET /api/v1/admin/tests/available

Нет

tests:run

200: object

POST /api/v1/admin/tests/run

Нет

tests:run

200: object

GET /api/v1/admin/tests/run/{run_id}

run_id [path обяз.]: string

tests:run

200: object

**GET /admin/tests/available.** Возвращает {"available": true | false}: есть ли в этой установке набор pytest. В комплект установки тесты не входят, поэтому на такой установке экран «Автотесты» вместо кнопки запуска объясняет, что тестов нет, а вкладки «Самодиагностика», «Безопасность» и «API и Swagger» (маршруты selfcheck, security и api-coverage) работают. Если вызвать POST /admin/tests/run при available=false, run_id вернется как обычно, но GET /admin/tests/run/{run_id} сразу отдаст status=done, ok=false и в error - причину: «Автотесты не входят в этот комплект установки». Перед запуском прогона из скрипта спросите этот маршрут.Очистка данных

Метод и путь

Параметры и тело

Доступ (скоуп ключа)

Успешный ответ

GET /api/v1/admin/purge/types

Нет

system:purge

200: object

GET /api/v1/admin/purge/{entity_type}/{entity_id}/preview

entity_type [path обяз.]: string; entity_id [path обяз.]: string (uuid)

system:purge

200: object

POST /api/v1/admin/purge/{entity_type}/{entity_id}

entity_type [path обяз.]: string; entity_id [path обяз.]: string (uuid); backup [query]: boolean (default=true)

system:purge

200: object

Журнал ошибок

Метод и путь

Параметры и тело

Доступ (скоуп ключа)

Успешный ответ

GET /api/v1/admin/errors

level [query]: ErrorLevel / null; module [query]: string / null; search [query]: string / null; days [query]: integer (default=30, min=1, max=365); limit [query]: integer (default=100, min=1, max=500); offset [query]: integer (default=0, min=0)

error_log:read

200: object

GET /api/v1/admin/errors/stats

days [query]: integer (default=7, min=1, max=90)

error_log:read

200: object

DELETE /api/v1/admin/errors/cleanup

keep_days [query]: integer / null

error_log:manage

200: object

Расписание задач

Метод и путь

Параметры и тело

Доступ (скоуп ключа)

Успешный ответ

GET /api/v1/admin/schedule

Нет

job_schedule:read

200: object

PUT /api/v1/admin/schedule

Нет | Тело: application/json: ScheduleUpdate

job_schedule:update

200: object

Пределы и пороги

Метод и путь

Параметры и тело

Доступ (скоуп ключа)

Успешный ответ

GET /api/v1/admin/tuning

Нет

tuning:read

200: object

PUT /api/v1/admin/tuning

Нет | Тело: application/json: TuningUpdate

tuning:update

200: object

Дорожная карта

Метод и путь

Параметры и тело

Доступ (скоуп ключа)

Успешный ответ

GET /api/v1/admin/roadmap

Нет

Только сессия

200: RoadmapResponse

Хранилище файлов

Метод и путь

Параметры и тело

Доступ (скоуп ключа)

Успешный ответ

GET /api/v1/storage/settings

Нет

storage:read

200: StorageSettingsRead

PUT /api/v1/storage/settings

Нет | Тело: application/json: StorageSettingsUpdate

storage:manage

200: StorageSettingsRead

POST /api/v1/storage/test-connection

type [query обяз.]: string

storage:manage

200: StorageActionResult

POST /api/v1/storage/connect

type [query обяз.]: string

storage:manage

200: StorageActionResult

POST /api/v1/storage/disconnect

Нет

storage:manage

200: StorageActionResult

GET /api/v1/storage/status

Нет

storage:read

200: StorageStatus

LDAP / AD

Метод и путь

Параметры и тело

Доступ (скоуп ключа)

Успешный ответ

GET /api/v1/admin/ldap

Нет

ldap:manage

200: LdapSettingsRead

PUT /api/v1/admin/ldap

Нет | Тело: application/json: LdapSettingsUpdate

ldap:manage

200: LdapSettingsRead

POST /api/v1/admin/ldap/test-connection

Нет | Тело: application/json: LdapTestConnectionRequest

ldap:manage

200: LdapTestResult

POST /api/v1/admin/ldap/test-auth

Нет | Тело: application/json: LdapTestAuthRequest

ldap:manage

200: LdapTestResult

OIDC

Метод и путь

Параметры и тело

Доступ (скоуп ключа)

Успешный ответ

GET /api/v1/admin/oidc

Нет

oidc:manage

200: OidcSettingsRead

PUT /api/v1/admin/oidc

Нет | Тело: application/json: OidcSettingsUpdate

oidc:manage

200: OidcSettingsRead

POST /api/v1/admin/oidc/test-discovery

Нет | Тело: application/json: OidcTestDiscoveryRequest

oidc:manage

200: OidcTestResult

HTTPS (TLS)

Метод и путь

Параметры и тело

Доступ (скоуп ключа)

Успешный ответ

GET /api/v1/tls/authorize

domain [query]: string (default=)

Без авторизации

200: object

GET /api/v1/tls/settings

Нет

tls:manage

200: TlsSettingsRead

PUT /api/v1/tls/settings

Нет | Тело: application/json: TlsSettingsUpdate

tls:manage

200: TlsSettingsRead

POST /api/v1/tls/refresh

Нет

tls:manage

200: TlsSettingsRead

GET /api/v1/tls/server-ip

Нет

tls:manage

200: object

Лицензия

Метод и путь

Параметры и тело

Доступ (скоуп ключа)

Успешный ответ

GET /api/v1/license

Нет

license:read

200: object

GET /api/v1/license/public

Нет

Без авторизации

200: object

POST /api/v1/license/upload

Нет | Тело: multipart/form-data: Body_upload_license_api_v1_license_upload_post

license:upload

200: object

GET /api/v1/license/org-requisites

Нет

license:read

200: object

PUT /api/v1/license/org-requisites

Нет | Тело: application/json: object

license:upload

200: object

Интеграции (API-ключи)

Метод и путь

Параметры и тело

Доступ (скоуп ключа)

Успешный ответ

GET /api/v1/integrations/api-keys

Нет

integrations:read

200: array[ApiKeyRead]

POST /api/v1/integrations/api-keys

Нет | Тело: application/json: ApiKeyCreate

integrations:manage

201: ApiKeyCreateResponse

POST /api/v1/integrations/api-keys/{key_id}/revoke

key_id [path обяз.]: string (uuid)

integrations:manage

200: ApiKeyRead

GET /api/v1/integrations/api-keys/{key_id}/usage

key_id [path обяз.]: string (uuid); days [query]: integer (default=30, min=1, max=365)

integrations:read

200: array[ApiKeyUsagePoint]

Каталог прав

Метод и путь

Параметры и тело

Доступ (скоуп ключа)

Успешный ответ

GET /api/v1/admin/permission-catalog

Нет

roles:update

200: object

PUT /api/v1/admin/permission-catalog/collections/{code}

code [path обяз.]: string | Тело: application/json: CollectionUpdate

roles:update

200: object

PUT /api/v1/admin/permission-catalog/actions/{action_id}

action_id [path обяз.]: string (uuid) | Тело: application/json: ActionUpdate

roles:update

200: object

DELETE /api/v1/admin/permission-catalog/actions/{action_id}

action_id [path обяз.]: string (uuid)

roles:update

204

POST /api/v1/admin/permission-catalog/actions

Нет | Тело: application/json: ActionCreate

roles:update

201: object

Конструктор документов

Метод и путь

Параметры и тело

Доступ (скоуп ключа)

Успешный ответ

GET /api/v1/document-registry/sets

Нет