# Drift Quant API Reference (v2.0)

Drift Quant exposes a deterministic, typed REST API using FastAPI. It serves persisted research artifacts, historical market data queries from indexed SQLite caches, and deterministic simulation execution.

Start the local service:

```powershell
uv run uvicorn drift_quant.api.app:app --host 127.0.0.1 --port 8000
```

Interactive OpenAPI Swagger UI: `http://127.0.0.1:8000/docs`  
Interactive ReDoc documentation: `http://127.0.0.1:8000/redoc`

---

## Endpoint Catalog

### System & Health

| Method | Endpoint | Description |
| :--- | :--- | :--- |
| `GET` | `/health` | Service health status, artifact directory, SQLite cache status, cached bar count, and accounting currency (`INR`). |

---

### Dataset & Universe Explorer

| Method | Endpoint | Query Parameters | Description |
| :--- | :--- | :--- | :--- |
| `GET` | `/api/v1/dataset/summary` | None | Full audit summary of the 17.8M row historical archive (archive bytes, SHA256 checksum, observation count, symbol count, coverage dates, invalid OHLC, zero volume, intraday gaps). |
| `GET` | `/api/v1/dataset/audit` | None | Legacy dataset audit summary (backward compatibility). |
| `GET` | `/api/v1/dataset/symbols` | `search` (str), `sector` (str) | Searchable catalog of 488 symbols with sector classification, observation counts, date bounds, anomaly counts, and SQLite fast-cache status. |
| `GET` | `/api/v1/dataset/coverage-timeline` | None | Observation distribution across calendar years (2019–2025) and session days of the week. |

---

### Market Data Service

| Method | Endpoint | Query Parameters | Description |
| :--- | :--- | :--- | :--- |
| `GET` | `/api/v1/market/bars` | `symbol` (required)<br>`start` (ISO date)<br>`end` (ISO date)<br>`resolution` (`15m`, `1h`, `1d`)<br>`limit` (1–5000, default 1500) | Fast historical OHLCV price bars queried directly from SQLite index. Sub-10ms query latency. Automatically resamples 15m raw bars to hourly or daily candles. |

---

### Quantitative Strategies & Backtesting

| Method | Endpoint | Request Body | Description |
| :--- | :--- | :--- | :--- |
| `GET` | `/api/v1/strategies` | None | Catalog of registered quantitative strategies (`SectorPairsReversionStrategy`, `SectorCrossMomentumStrategy`, etc.) with parameter schemas, indicator requirements, warm-up bars, and limitations. |
| `POST` | `/api/v1/backtest/run` | `BacktestRunRequest` (JSON) | Executes an authoritative, deterministic backtest against the indexed historical data. Saves auditable JSON/CSV artifacts to disk and returns complete experiment metrics and curve. Execution duration: <600 ms. |

#### `BacktestRunRequest` Schema:
```json
{
  "strategy_name": "sector_pairs_reversion",
  "universe": ["RELIANCE", "TCS", "HDFCBANK", "ICICIBANK"],
  "start_date": "2019-01-01",
  "end_date": "2025-07-14",
  "initial_capital": 1000000,
  "max_gross_exposure": 1.0,
  "transaction_cost_bps": 10.0,
  "slippage_bps": 5.0,
  "strategy_params": {
    "lookback_bars": 40,
    "entry_zscore": 1.8,
    "exit_zscore": 0.2,
    "stop_loss_zscore": 3.2,
    "min_holding_bars": 30
  }
}
```

---

### Experiment Analytics & Ledger

| Method | Endpoint | Query Parameters | Description |
| :--- | :--- | :--- | :--- |
| `GET` | `/api/v1/experiments` | `offset` (int, default 0)<br>`limit` (1–100, default 50) | Paginated list of all persisted backtest experiment summaries. |
| `GET` | `/api/v1/experiments/{id}` | Path: `id` | Full experiment detail including configuration, summary metrics, and execution metadata. |
| `GET` | `/api/v1/experiments/{id}/equity` | `maximum_points` (10–5000, default 1500) | Downsampled portfolio net equity and gross leverage series. |
| `GET` | `/api/v1/experiments/{id}/drawdown` | `maximum_points` (10–5000, default 1500) | Underwater peak-to-trough drawdown curve points. |
| `GET` | `/api/v1/experiments/{id}/trades` | `symbol` (str)<br>`outcome` (`win`/`loss`)<br>`exit_reason` (str)<br>`offset` (int)<br>`limit` (1–500) | Paginated trade execution ledger with filterable queries. |
| `GET` | `/api/v1/experiments/{id}/attribution` | None | Per-symbol P&L attribution, win rate, costs paid, return contribution, and profit factor. |
| `GET` | `/api/v1/experiments/{id}/monthly` | None | Calendar-year matrix of monthly returns and annual totals for heatmap rendering. |
| `GET` | `/api/v1/experiments/compare` | `ids` (list of strings, 2–8 IDs) | Side-by-side metric comparison across multiple saved experiments. |

---

### Artifact Export Endpoints

| Method | Endpoint | Query Parameters | Description |
| :--- | :--- | :--- | :--- |
| `GET` | `/api/v1/reports/{id}/export-csv` | `kind` (`trades` or `equity`) | Streams a formatted CSV file download for the specified experiment artifact. |