tradesenseAi / docs /audit /api_inventory.md
Niranjan-Murugarasu024
feat: TradeSense AI Chairman Edition production release ready for Hugging Face Spaces
0125724
|
Raw History Blame Contribute Delete
7.38 kB

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).