# LeadPilot — REST API v1 Overview & Specification

**Document Version:** 1.0.0 (Phase 25)

---

## 1. Authentication & Base URL

- **Base URL:** `https://your-domain.com/api/v1`
- **Authentication:** Bearer token passed in the `Authorization: Bearer <API_KEY>` header.
- **Idempotency:** Supported via `Idempotency-Key: <UUID_OR_STRING>` on creation endpoints.

---

## 2. API Endpoints Reference

- `GET /health` — Public health check.
- `GET /leads` — Paginated list of workspace leads.
- `POST /leads` — Ingest or create a lead.
- `GET /leads/{id}` — Retrieve full lead profile, activities, notes, and AI qualification.
- `PATCH /leads/{id}` — Update lead contact attributes.
- `PATCH /leads/{id}/stage` — Transition lead across pipeline stages.
- `POST /leads/{id}/notes` — Append a note to the lead record.
- `GET /dashboard/summary` — Retrieve executive operational numbers.
- `GET /dashboard/attention` — Retrieve attention items requiring human action.