docs/api/API_REFERENCE.md

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:

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) start (ISO date) end (ISO date) resolution (15m, 1h, 1d) 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:

{
  "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) 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) outcome (win/loss) exit_reason (str) offset (int) 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.