# Analytics & Reporting REST API

**Document Version:** 2.0.0 (Phase 17)

---

## 1. Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/v1/analytics/overview` | Executive KPI summary with prior period comparisons |
| `GET` | `/api/v1/analytics/sources` | First-touch lead source performance & attributed revenue |
| `GET` | `/api/v1/analytics/pipeline` | Pipeline stage funnel and progression rates |
| `GET` | `/api/v1/analytics/followups` | Follow-up execution reliability and task completion |
| `GET` | `/api/v1/analytics/recovery` | Recovered leads, recovery revenue, and breakdown by source |
| `GET` | `/api/v1/analytics/team` | Team operational metrics and average response times |
| `GET` | `/api/v1/analytics/ai` | Conversion rates broken down by AI score band |
| `GET` | `/api/v1/analytics/export` | Secure CSV export (`type=leads\|sources\|pipeline\|team`) |

---

## 2. Authentication & Filtering

All requests require Bearer token authentication (`Authorization: Bearer <api_key>`).

**Supported Query Parameters:**
- `period`: `today`, `yesterday`, `7days`, `30days`, `90days`, `this_month`, `previous_month`, `year`
- `from`, `to`: ISO8601 date strings for custom ranges
- `source_id`: UUID of `lead_sources`
- `pipeline_id`: UUID of `pipelines`
- `stage_id`: UUID of `pipeline_stages`
- `assigned_user_id`: UUID of `users`
- `temperature`: `HOT`, `WARM`, `COLD`