docs/api/frontend_contract.md

TradeSense AI — Frontend API Contract Specification (M19.1 Frozen)

Version: 1.9.0-ENTERPRISE
Backend Status: FROZEN & AUTHORITATIVE
OpenAPI Snapshot: openapi/tradesense-openapi.json

---

1. Authentication & Session Management

POST /api/v1/auth/login

• Purpose: Authenticate user with PBKDF2 verification & account lockout guard.
• Parameters: username (string), password (string), tenant_id (string, default: default_tenant).
• Response (200):

  {
    "access_token": "eyJhbGciOi...",
    "token_type": "bearer",
    "tenant_id": "default_tenant",
    "username": "lead_quant",
    "expires_in_minutes": 60
  }
  

• Error Codes: 401 Unauthorized (bad password), 423 Locked (5 consecutive failures).

POST /api/v1/auth/logout

• Headers: Authorization: Bearer <token>
• Response (200): {"message": "Successfully logged out and revoked access token."}

---

2. Research Plane Endpoints

POST /api/v1/research/runs

• Headers: Authorization: Bearer <token>, Idempotency-Key: <uuid>
• Query: experiment_id (string), strategy_id (string)
• Body: ConfigurationSnapshot
• Response (202): {"run_id": "run_...", "status": "QUEUED", "workflow_state": "PRE_REGISTERED", "enqueued": true}

GET /api/v1/research/runs

• Query: experiment_id (optional), limit (int, default 50), offset (int, default 0)
• Response (200): {"total": 12, "tenant_id": "...", "runs": [...]}

GET /api/v1/research/runs/{run_id}

• Response (200): ResearchRun domain object with configuration, provenance, status, workflow_state, metrics_summary.

GET /api/v1/research/runs/{run_id}/evidence_package

• Purpose: Sealed Institutional Evidence Package export with SHA-256 root digest.
• Response (200):

  {
    "evidence_package": {
      "package_schema_version": "1.9.0-INSTITUTIONAL-EVIDENCE",
      "metadata": { ... },
      "specification": { ... },
      "governance": { ... },
      "audit_subchain": [ ... ],
      "family_1_control_reference": { ... }
    },
    "cryptographic_verification": {
      "root_digest_sha256": "3a8f...",
      "algorithm": "SHA-256",
      "verified": true
    }
  }
  

---

3. Control Plane & Governance Endpoints

GET /api/v1/governance/decisions

• Response (200): {"total": 5, "decisions": [...]} (Includes Family 1 permanent benchmark).

POST /api/v1/governance/decisions/{decision_id}/reviews

• Query: verdict (APPROVE | REJECT | REQUEST_CHANGES), comments (string)
• Response (201): ResearchDecision with updated peer_reviews list.

GET /api/v1/governance/family_1_archive

• Purpose: Permanent Immutable Control Benchmark record.
• Response (200):

  {
    "family_id": "family_1_5d_reversal",
    "classification": "EXPLAINED_FACTOR_PREMIUM",
    "operational_status": "NO_GENERALIZABLE_ALPHA",
    "workflow_state": "ARCHIVED",
    "evidence_summary": {
      "net_annualized_alpha_pct": -0.45,
      "newey_west_hac_t_stat": -0.04,
      "p_value": 0.9703
    }
  }
  

GET /api/v1/audit/events

• Query: limit, offset, actor_id
• Response (200): {"total": 45, "events": [...]}

GET /api/v1/audit/verify

• Response (200): {"ledger_cryptographically_verified": true, "tampering_detected": false}

---

4. Multi-Tenant Organizations & Usage

GET /api/v1/organizations / POST /api/v1/organizations

GET /api/v1/tenants/usage

• Response (200): {"period_date": "2026-09", "research_runs_count": 12, "total_cpu_seconds": 45.2, "storage_bytes": 2048576, "api_requests_count": 142}

---

5. Health, Probes & Version

• GET /startup -> {"status": "READY", "initialized": true}
• GET /health -> {"status": "UP"}
• GET /ready -> {"status": "READY"}
• GET /api/v1/version -> {"version": "1.9.0-ENTERPRISE", "family_1_status": "EXPLAINED_FACTOR_PREMIUM (CLOSED & IMMUTABLE)"}