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

**Version**: `1.9.0-ENTERPRISE`  
**Backend Status**: `FROZEN & AUTHORITATIVE`  
**OpenAPI Snapshot**: [`openapi/tradesense-openapi.json`](file:///d:/Stock_project/v7.5.1US%20us%20stocks%20only%20%28them%20switch,graph%20coming%20with%20homepage%29/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)**:
  ```json
  {
    "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)**:
  ```json
  {
    "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)**:
  ```json
  {
    "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)"}`