API

Базовый префикс: /api/v1. Интерактивная схема (только local/debug): http://localhost:8000/docs
В production (DEBUG=false) /docs и /openapi.json отключены.

Health и version

```bash curl -s http://localhost:8000/api/v1/health

{"status":"ok","service":"AgentBI","version":""}

curl -s http://localhost:8000/api/v1/health/ready

{"status":"ok","service":"AgentBI","database":true,"redis":true,"version":""}

curl -s http://localhost:8000/api/v1/version

{"service":"AgentBI","version":"","sha":""}

```

version / sha берутся из APP_VERSION / GIT_SHA / файла VERSION (SHA деплоя).

Ingest событий агентов

bash curl -X POST http://localhost:8000/api/v1/ingest/events \ -H "X-API-Key: $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "agent_id": "support-triage", "event_type": "task_completed", "duration_ms": 1500, "input_tokens": 100, "output_tokens": 250, "cost_usd": 0.05, "business_value": 10.00, "time_saved_minutes": 15 }'

Альтернативы:

Метод	Путь
POST	/api/v1/ingest/events
POST	/api/v1/ingest/events/batch
POST	/api/v1/ingest/webhook
POST	/api/v1/metrics/ingest

Неизвестные значения agent_id регистрируются автоматически.

Метрики по всем агентам

bash curl "http://localhost:8000/api/v1/metrics/agents?period=week" \ -H "X-API-Key: $API_KEY"

Пример ответа:

json { "agents": [ { "agent_id": "support-triage", "agent_name": "Support Triage Agent", "total_cost": 12.5, "total_value": 350.0, "time_saved_hours": 42.0, "roi": 2700.0, "avg_duration_ms": 1200.0, "tasks_completed": 340 } ], "total_cost": 45.3, "total_value": 1250.0, "total_roi": 2659.0, "total_time_saved_hours": 156.0, "period": "week" }

period: day | week | month | quarter | year

Метрики по одному агенту

bash curl "http://localhost:8000/api/v1/metrics/agent/support-triage?period=week" \ -H "X-API-Key: $API_KEY"

Возвращает агрегаты, тренды value/cost и аномалии (падение эффективности, скачок стоимости, снижение ROI).

Executive dashboard

bash curl "http://localhost:8000/api/v1/dashboard/executive?period=week" \ -H "Authorization: Bearer $JWT"

ROI по одному агенту

bash curl "http://localhost:8000/api/v1/roi/agent/support-triage?period=month" \ -H "X-API-Key: $API_KEY"

ROI включает business_value + экономию труда (time_saved_hours × hourly_human_cost_usd).

Пример ответа:

json { "agent_id": "support-triage", "agent_name": "Support Triage Agent", "period": "month", "total_cost_usd": 45.8, "total_value_usd": 1250.0, "net_roi": 2629.0, "time_saved_hours": 87.0, "labor_cost_saved_usd": 3915.0, "payback_days": 1.1, "tasks_completed": 340, "interpretation": "Outstanding ROI. Generated 87.0 hours of employee time saved." }

Сравнение агентов

```bash

ROI compare

curl "http://localhost:8000/api/v1/roi/compare?agent_ids=support-triage&agent_ids=invoice-matcher&period=month" \ -H "X-API-Key: $API_KEY"

Side-by-side (metrics + winners)

curl "http://localhost:8000/api/v1/compare/agents?agent_ids=support-triage&agent_ids=lead-qualifier&period=month" \ -H "Authorization: Bearer $JWT" ```

Отчёты и экспорт

```bash

Create executive report

curl -X POST http://localhost:8000/api/v1/reports \ -H "Authorization: Bearer $JWT" \ -H "Content-Type: application/json" \ -d '{"report_type":"executive","period":"month"}'

PDF / Excel

curl -L "http://localhost:8000/api/v1/reports//export?format=pdf" \ -H "Authorization: Bearer $JWT" -o report.pdf

curl -L "http://localhost:8000/api/v1/reports//export?format=excel" \ -H "Authorization: Bearer $JWT" -o report.xlsx

Delete

curl -X DELETE "http://localhost:8000/api/v1/reports/" \ -H "Authorization: Bearer $JWT" ```

SDK

```python from agentbi import AgentBI # sdk/agentbi.py

client = AgentBI("http://localhost:8000", api_key="abi_...") client.track( agent_id="support-triage", event_type="task_completed", cost_usd=0.12, business_value=25.0, time_saved_minutes=15, ) ```

Billing

См. Monetization. Кратко:

Метод	Путь
GET	/api/v1/billing/status
GET	/api/v1/billing/subscription
POST	/api/v1/billing/checkout
POST	/api/v1/billing/create-portal-session
POST	/api/v1/billing/webhook

Custom domain tenant

Администраторы tenant (не платформенный PATCH /tenants):

Метод	Путь	Auth
GET	/api/v1/tenant/domain	JWT + tenant
POST	/api/v1/tenant/domain	admin+ — { "domain": "analytics.example.com" }
DELETE	/api/v1/tenant/domain	admin+ — снимает привязку

Уникально между tenant; неверный формат → 400; конфликт → 409. DNS/TLS не настраивает.

Обратная связь

Публичная форма (нужны согласие и email). Поле-honeypot website принимается без записи. Входящие — только super_admin.

Метод	Путь	Auth
POST	/api/v1/feedback	JWT необязателен
GET	/api/v1/feedback	super_admin
PATCH	/api/v1/feedback/{id}	super_admin
DELETE	/api/v1/feedback/{id}	super_admin
POST	/api/v1/feedback/bulk-delete	super_admin