API

Base prefix: /api/v1. Interactive schema (local/debug only): http://localhost:8000/docs
In production (DEBUG=false) /docs and /openapi.json are disabled.

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 come from APP_VERSION / GIT_SHA / VERSION file (deploy SHA).

Ingest agent events

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 }'

Alternatives:

Method	Path
POST	/api/v1/ingest/events
POST	/api/v1/ingest/events/batch
POST	/api/v1/ingest/webhook
POST	/api/v1/metrics/ingest

Unknown agent_id values are auto-registered.

Metrics for all agents

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

Example response:

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

Metrics for one agent

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

Returns aggregates, value/cost trends, and business anomalies (efficiency drop, cost spike, ROI decline).

Executive dashboard

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

ROI for one agent

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

ROI includes business_value + labor savings (time_saved_hours × hourly_human_cost_usd).

Example response:

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." }

Compare agents

```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" ```

Reports and export

```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

See Monetization. Summary:

Method	Path
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

Tenant custom domain

Tenant admins (not platform PATCH /tenants):

Method	Path	Auth
GET	/api/v1/tenant/domain	JWT + tenant
POST	/api/v1/tenant/domain	admin+ — { "domain": "analytics.example.com" }
DELETE	/api/v1/tenant/domain	admin+ — clears binding

Unique across tenants; invalid format → 400; conflict → 409. Does not provision DNS/TLS.