# LeadPilot — AI Qualification REST API v1 Specification

**Document Version:** 1.0.0 (Phase 8 AI Qualification Lock)  
**Status:** Implemented & Verified via Automated Tests  
**Base URL:** `/api/v1`  
**Authentication:** `Authorization: Bearer <plain_api_key>`  

---

## 1. Endpoints Catalog

```
+--------+------------------------------------------+----------------------------------------------------------+
| METHOD | ROUTE                                    | RESPONSIBILITY                                           |
+--------+------------------------------------------+----------------------------------------------------------+
| POST   | `/api/v1/leads/{id}/qualification`       | Trigger AI qualification or re-analysis on a lead.       |
| GET    | `/api/v1/leads/{id}/qualification`       | Retrieve latest validated AI score and recommendations.  |
+--------+------------------------------------------+----------------------------------------------------------+
```

---

## 2. Example Response (`POST /api/v1/leads/{id}/qualification`)

```json
{
  "success": true,
  "data": {
    "id": "9d901a91-4c6e-4402-984c-3e6f98a28723",
    "lead_id": "9d901a88-29be-41d4-a716-446655440000",
    "score": 92,
    "temperature": "HOT",
    "urgency": "IMMEDIATE",
    "intent": "Custom SaaS Web App Development",
    "fit_summary": "High budget ($25,000) and clear requirements matching agency capabilities.",
    "reason": "Clear budget stated, established business domain, immediate project timeline.",
    "recommended_action": "Contact immediately within 15 minutes.",
    "provider": "mock-ai-provider",
    "created_at": "2026-08-30T01:15:00.000000Z"
  }
}
```