Справочник API

Полный справочник REST API AegisAI v1. Базовый URL: http://localhost:8000/api/v1.

Интерактивная документация: http://localhost:8000/docs

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

Заголовок	Назначение
X-API-Key	API-ключ арендатора (агенты, SDK)
X-Admin-Key	Ключ администратора (управление tenants)
Authorization: Bearer <jwt>	JWT-сессия пользователя

Health & Status

Метод	Путь	Auth	Описание
GET	/health	—	Liveness check
GET	/health/ready	—	Readiness (DB, Redis, OPA)
GET	/status	API Key	Статус платформы
GET	/stats	API Key	Статистика для панели

Prompt Guard

Метод	Путь	Auth	Описание
GET	/guard/health	—	Health и конфиг Guard
POST	/guard/validate	API Key	Проверка промпта (injection / jailbreak / leakage)
GET	/guard/stats	API Key	Метрики Guard
GET	/guard/detector/status	API Key	Статус детектора
GET	/guard/detector/metrics	API Key	Метрики precision/recall
GET	/guard/detector/versions	API Key	История версий модели
POST	/guard/detector/train	API Key + guard:manage	Запуск обучения
GET	/guard/detector/training/status	—	Прогресс обучения (task_id)
POST	/guard/detector/rollback/{version}	API Key + guard:manage	Откат версии
DELETE	/guard/detector/cancel	API Key + guard:manage	Отмена обучения
POST	/guard/detector/feedback	API Key + guard:manage	Ручная разметка (FP / атака)

Подробнее: Prompt Guard.

Аутентификация пользователей

Метод	Путь	Auth	Описание
POST	/auth/login	—	Вход (email + password)
POST	/auth/logout	JWT	Выход
GET	/auth/me	JWT	Текущий пользователь
GET	/auth/sso/providers	—	Список SSO-провайдеров
GET	/auth/sso/login	—	Начало OIDC (redirect)
POST	/auth/sso/exchange	—	Обмен SSO code на JWT

POST /auth/login

// Request
{"email": "admin@aegisai.com", "password": "admin123"}

// Response
{
  "access_token": "eyJ...",
  "expires_in": 86400,
  "api_key": "aegis_...",
  "user": {"id": "...", "email": "...", "role": "admin"}
}

Агенты

Метод	Путь	Auth	Описание
POST	/agents/register	API Key	Регистрация агента
GET	/agents	API Key	Список (с predicted_type / risk)
GET	/agents/search	API Key	Семантический поиск ?q=
GET	/agents/{id}	API Key	Агент по ID
GET	/agents/{id}/details	API Key	Детали + embedding summary
PUT	/agents/{id}	API Key	Обновление
DELETE	/agents/{id}	API Key	Удаление
POST	/agents/{id}/heartbeat	API Key	Heartbeat (+ refresh embeddings)

POST /agents/register

{
  "name": "Sales Bot",
  "type": "llm",
  "capabilities": ["observe", "track"],
  "permissions": {}
}

Discovery (Shadow AI)

Метод	Путь	Auth	Описание
GET	/discovery/candidates	API Key	Список кандидатов
POST	/discovery/ingest	API Key	Ingest события
POST	/discovery/ingest/batch	API Key	Batch ingest
POST	/discovery/cluster	API Key	Async clustering
POST	/discovery/candidates/{id}/confirm	API Key	Confirm → register
POST	/discovery/candidates/{id}/dismiss	API Key	Dismiss

Политики

Метод	Путь	Auth	Описание
POST	/policies	JWT (Admin)	Создать политику
GET	/policies	API Key / JWT	Список политик
GET	/policies/templates	API Key	Rego-шаблоны
POST	/policies/check	API Key	Проверка политики
GET	/policies/{id}	API Key	Политика по ID
PUT	/policies/{id}	JWT (Admin)	Обновление
DELETE	/policies/{id}	JWT (Admin)	Удаление

POST /policies/check

// Request
{
  "agent_id": "uuid",
  "action": "read_data",
  "resource": "customer_pii",
  "context": {"consent": true}
}

// Response
{
  "allowed": true,
  "required_approval": false,
  "risk_score": 0.15,
  "risk": "low",
  "anomaly": false,
  "reason": "Access granted"
}

Аудит

Метод	Путь	Auth	Описание
POST	/audit/log	API Key	Запись в журнал
GET	/audit	API Key / JWT	Список (пагинация)
GET	/audit/{id}	API Key	Запись по ID
GET	/audit/export	API Key	Экспорт JSONL
GET	/audit/export/json	API Key	Экспорт JSON
GET	/audit/export/csv	API Key	Экспорт CSV
POST	/audit/export/async	API Key	Асинхронный экспорт
GET	/audit/export/status/{id}	API Key	Статус экспорта
GET	/audit/export/download/{id}	API Key	Скачать экспорт

Аномалии

Метод	Путь	Auth	Описание
GET	/anomalies	API Key / JWT	Список отчётов
GET	/anomalies/stats	API Key	Статистика
POST	/anomalies/report	API Key	Создать отчёт
GET	/anomalies/detector/status	API Key	Статус детектора
GET	/anomalies/detector/metrics	API Key	Метрики
POST	/anomalies/detector/train	JWT (Admin)	Обучить модель
POST	/anomalies/detector/rollback/{v}	JWT (Admin)	Откат версии

HITL

Метод	Путь	Auth	Описание
POST	/hitl/request	API Key	Запрос согласования
POST	/hitl/approve/{id}	JWT (Analyst+)	Согласовать
POST	/hitl/reject/{id}	JWT (Analyst+)	Отклонить
GET	/hitl/status/{id}	API Key	Статус запроса
GET	/hitl/pending	JWT (Analyst+)	Очередь

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

Метод	Путь	Auth	Описание
GET	/users/me	JWT	Мой профиль
PUT	/users/me	JWT	Обновить профиль
POST	/users/me/change-password	JWT	Сменить пароль
POST	/users	JWT (Admin)	Создать пользователя
GET	/users	JWT (Admin)	Список
GET	/users/{id}	JWT (Admin)	По ID
PUT	/users/{id}	JWT (Admin)	Обновить
PUT	/users/{id}/role	JWT (Admin)	Сменить роль
POST	/users/{id}/block	JWT (Admin)	Заблокировать
POST	/users/{id}/unblock	JWT (Admin)	Разблокировать
DELETE	/users/{id}	JWT (Admin)	Удалить

API-ключи

Метод	Путь	Auth	Описание
POST	/api-keys	JWT	Создать ключ
GET	/api-keys	JWT	Список ключей
DELETE	/api-keys/{id}	JWT	Отозвать

Арендаторы

Метод	Путь	Auth	Описание
POST	/tenants	Admin Key	Создать арендатора
GET	/tenants	Admin Key	Список

SIEM (Admin)

Требуется JWT Super Admin или X-Admin-Key. См. SIEM.

Метод	Путь	Описание
GET	/siem/status	Конфигурация SIEM
POST	/siem/test	Тестовое событие

WebSocket

Протокол	Путь	Auth	Описание
WS	/ws?token=<jwt>	JWT (query)	Real-time события

Webhooks (вне /api/v1)

Метод	Путь	Auth	Описание
POST	/webhooks/agent	API Key + Signature	События агента

Коды ответов

Код	Описание
200	Успех
201	Создано
202	Принято (async)
204	Успех без тела
400	Неверный запрос
401	Не авторизован
403	Доступ запрещён
404	Не найдено
422	Ошибка валидации
500	Внутренняя ошибка

OpenAPI

Полная спецификация доступна в Swagger UI: http://localhost:8000/docs