# TradeSense AI — API Endpoint Inventory & Contract Audit **Module 00: Production Forensic Audit** **Audit Timestamp:** 2026-10-05T12:20:00+05:30 **Status:** COMPLETE & VERIFIED --- ## 1. Executive Summary The active FastAPI backend exposes **36 endpoints** across 9 functional routers. - **Authenticated Endpoints**: 15 endpoints enforce JWT Bearer Token validation via `Security(get_current_user)` and RBAC checks (`require_role(...)`). - **Public / Unauthenticated Endpoints**: 21 endpoints are accessible without credentials. - **Contract Integrity**: Pydantic v2 schemas govern all request payloads and response models, enforcing strict data typing and validation errors (`422 Unprocessable Entity`). --- ## 2. Complete API Endpoint Inventory | Method | Endpoint | Auth | RBAC Role | Request Schema | Response Schema | DB / Ext API | Caching / Rate Limit | Status | |---|---|---|---|---|---|---|---|---| | `GET` | `/` | None | Public | None | HTML | None / Local Disk | Static / None | **VERIFIED** | | `GET` | `/health` | None | Public | None | `HealthStatusResponse` | SQLite / None | None | **VERIFIED** | | `GET` | `/ready` | None | Public | None | `ReadinessResponse` | SQLite, Cache / None | None | **VERIFIED** | | `GET` | `/startup` | None | Public | None | `StartupResponse` | Schema Check / None | None | **VERIFIED** | | `GET` | `/metrics` | None | Public | None | Prometheus Text | In-Memory Counters | Real-time | **VERIFIED** | | `POST` | `/api/v1/auth/login` | None | Public | Query: `username`, `password` | `TokenResponse` | Users Table / None | 5 failed lockout | **VERIFIED** | | `POST` | `/api/v1/auth/logout` | JWT | Authenticated | None | `MessageResponse` | Revocation List | Token Blacklist | **VERIFIED** | | `POST` | `/api/v1/auth/token` | JWT | Authenticated | None | `TokenResponse` | Users Table | None | **VERIFIED** | | `GET` | `/api/v1/market/quote/{symbol}` | None | Public | Path: `symbol`, Query: `exchange` | `QuoteResponse` | Cache → yfinance | 5s In-Memory Cache | **VERIFIED** | | `GET` | `/api/v1/market/chart/{symbol}` | None | Public | Path: `symbol`, Query: `timeframe` | `ChartResponse` (OHLCV) | Cache → yfinance | 60s Cache | **VERIFIED** | | `GET` | `/api/v1/market/search` | None | Public | Query: `q` (min 1 char) | `List[SearchResult]` | In-memory Indian catalog | None / In-memory | **VERIFIED** | | `GET` | `/api/v1/market/company_overview` | None | Public | None | `CompanyOverviewResponse` | Cache → Quotes | 30s Cache | **VERIFIED** | | `GET` | `/api/v1/market/live_ticker` | None | Public | None | `LiveTickerResponse` | Cache → Quotes | 10s Cache | **VERIFIED** | | `GET` | `/api/v1/market/context` | None | Public | None | `MarketContextResponse` | Macro indicators | 60s Cache | **VERIFIED** | | `GET` | `/api/v1/market/options/{symbol}` | None | Public | Path: `symbol` | `OptionsSummaryResponse` | yfinance options chain | 30s Cache | **VERIFIED** | | `GET` | `/api/v1/calendar/sessions` | None | Public | None | `SessionResponse` | NSE / BSE trading calendar | Static / None | **VERIFIED** | | `GET` | `/api/v1/research/{ticker}` | None | Public | Path: `ticker` | `ResearchAnalysisResponse` | Master Quant Engine | Compute heavy / None | **RISK (P0)** | | `POST` | `/api/v1/research/runs` | JWT | `RESEARCHER` | `ResearchRunSubmissionRequest` | `ResearchRunAccepted` | SQLite + Worker Queue | Rate Limited | **VERIFIED** | | `GET` | `/api/v1/research/runs` | JWT | `VIEWER` | Query: `limit`, `offset` | `List[ResearchRunSummary]` | SQLite Runs Table | None | **VERIFIED** | | `GET` | `/api/v1/research/runs/{run_id}` | JWT | `VIEWER` | Path: `run_id` | `ResearchRunDetail` | SQLite Runs Table | None | **VERIFIED** | | `GET` | `/api/v1/research/runs/{run_id}/evidence_package` | JWT | `VIEWER` | Path: `run_id` | `EvidencePackageResponse` | Runs + Audit Table | None | **VERIFIED** | | `POST` | `/api/v1/research/runs/{run_id}/reproduce` | JWT | `SENIOR_RESEARCHER` | Path: `run_id` | `ReproductionResult` | Runs + Quant Engine | None | **VERIFIED** | | `GET` | `/api/v1/governance/decisions` | JWT | `VIEWER` | Query: `status` | `List[GovernanceDecision]` | Governance Table | None | **VERIFIED** | | `POST` | `/api/v1/governance/decisions/{id}/reviews` | JWT | `SENIOR_RESEARCHER` | Query: `verdict`, `comments` | `ReviewResponse` | Governance Table | None | **VERIFIED** | | `GET` | `/api/v1/governance/family_1_archive` | JWT | `AUDITOR` | None | `ArchiveResponse` | Archive Records | None | **VERIFIED** | | `GET` | `/api/v1/audit/events` | JWT | `AUDITOR` | Query: `limit`, `offset` | `List[AuditEvent]` | Audit Ledger Table | None | **VERIFIED** | | `GET` | `/api/v1/audit/verify` | JWT | `ADMIN` | None | `LedgerVerificationResult` | Audit Ledger Table | Computes SHA-256 chain | **VERIFIED** | | `POST` | `/api/v1/organizations` | JWT | `ADMIN` | Query: `name` | `OrgResponse` | Organizations Table | None | **VERIFIED** | | `GET` | `/api/v1/organizations` | JWT | `ADMIN` | None | `List[OrgResponse]` | Organizations Table | None | **VERIFIED** | | `GET` | `/api/v1/tenants/usage` | JWT | `OPERATOR` | None | `TenantUsageResponse` | Tenant Quotas Table | None | **VERIFIED** | | `GET` | `/api/v1/observability/metrics` | JWT | `OPERATOR` | None | `ObservabilitySnapshot` | Metrics Aggregator | Real-time | **VERIFIED** | | `GET` | `/api/v1/screener` | None | Public | None | `ScreenerResponse` | Multi-stock stats | 60s Cache | **VERIFIED** | | `GET` | `/api/v1/journal` | None | Public | None | `JournalResponse` | Prediction Journal | None | **VERIFIED** | | `GET` | `/api/v1/statutory/costs` | None | Public | Query: `price`, `qty`, `turnover` | `StatutoryCostBreakdown` | Local Indian Tax Rules | Pure compute | **VERIFIED** | | `GET` | `/api/v1/data/health` | None | Public | None | `DataHealthResponse` | Provider health pings | 15s Cache | **VERIFIED** | | `GET` | `/api/v1/data/diagnostics` | None | Public | None | `DataDiagnosticsResponse` | Provider telemetry | None | **VERIFIED** | --- ## 3. Contract Discrepancies & API Hazards ### 3.1 Field Naming & Serialization Mismatches 1. **`last_price` Nullability in Search Results**: - Schema: `/api/v1/market/search` returns `last_price: Optional[float] = None`. - Frontend: `app.js` line 2395 expects a float or assigns `0`. Injects `₹0.00` into the Company Overview table for any searched stock that hasn't had an explicit `/quote` fetched yet. 2. **`change_pct` vs `change_percent`**: - Backend `QuoteResponse` outputs `change_pct: float`. - Legacy frontend snippets refer to `quote.change_percent`, causing undefined badges in un-updated UI cards. ### 3.2 Unauthenticated Denial of Service (DoS) Risk on `/api/v1/research/{ticker}` - **Symptom**: `GET /api/v1/research/{ticker}` executes a full walk-forward backtest, conformal prediction interval generation, and risk falsification pipeline synchronously in the ASGI thread pool. - **Root Cause**: The endpoint is unauthenticated and lacks per-IP rate limiting. - **Exploitation Impact**: An external attacker issuing 10 concurrent requests to `/api/v1/research/TATAMOTORS` exhausts all Python worker threads, locking up Uvicorn and starving market quote endpoints. - **Fix Required**: Enforce JWT authentication or wrap `/api/v1/research/{ticker}` in a background Celery/rq worker with token bucket rate-limiting (e.g. 2 runs per minute per IP).