docs/API_DOCUMENTATION.md

# BankBot AI — Complete API Documentation

Base URL: `http://localhost:8000`  
WebSocket: `ws://localhost:8000`  
API Docs (interactive): `http://localhost:8000/docs`

---

## Authentication

All protected endpoints require:
```
Authorization: Bearer <access_token>
```

### POST /api/auth/register
Create a new user account.

**Request:**
```json
{
  "email": "user@example.com",
  "password": "SecurePass123!",
  "name": "Alex Doe"
}
```

**Response 201:**
```json
{
  "access_token": "eyJhbGci...",
  "refresh_token": "eyJhbGci...",
  "token_type": "bearer",
  "user_id": "uuid",
  "name": "Alex Doe",
  "email": "user@example.com"
}
```

**Errors:** `409` email already registered

---

### POST /api/auth/login
Login with email and password (form-encoded).

**Request:** `application/x-www-form-urlencoded`
```
username=alex@bankbot.dev&password=BankBot2026!
```

**Response 200:** Same as register response

**Errors:** `401` incorrect credentials

---

### POST /api/auth/refresh
Exchange a refresh token for a new access token.

**Request:**
```json
{ "refresh_token": "eyJhbGci..." }
```

**Response:**
```json
{ "access_token": "eyJhbGci...", "token_type": "bearer" }
```

---

### GET /api/auth/me
Get current authenticated user profile.

**Response:**
```json
{
  "user_id": "uuid",
  "email": "alex@bankbot.dev",
  "name": "Alex Doe",
  "financial_personality": "Balanced Investor"
}
```

---

### POST /api/auth/logout
Logout (client should discard tokens).

**Response:** `{ "message": "Logged out successfully" }`

---

## Dashboard

### GET /api/dashboard/overview
Full dashboard data in a single request. Cached 2 minutes.

**Query params:** `user_id` (optional, defaults to first user)

**Response:**
```json
{
  "total_balance": 59637.82,
  "accounts": [
    { "id": "uuid", "type": "checking", "balance": 12847.32, "currency": "USD" }
  ],
  "monthly_income": 5100.00,
  "monthly_expenses": 3240.50,
  "savings_rate": 36.5,
  "spending_by_category": [
    { "name": "Housing", "value": 1950.00 },
    { "name": "Food", "value": 487.30 }
  ],
  "recent_transactions": [
    {
      "id": "uuid",
      "merchant": "Whole Foods",
      "category": "Groceries",
      "amount": -87.43,
      "type": "debit",
      "timestamp": "2026-05-24T14:32:00"
    }
  ],
  "cash_flow": [
    { "month": "Dec", "income": 5100, "expenses": 3200, "savings": 1900 }
  ],
  "health_score": 82.0,
  "fraud_alert_count": 1,
  "ai_briefing": {
    "summary": "Your financial health looks strong...",
    "briefing": null
  }
}
```

**Performance:** ~65ms cold, ~10ms cached

---

## AI Intelligence

### GET /api/ai/coaching/score
Financial health score (0-100) across 6 dimensions. Cached 10 minutes.

**Response:**
```json
{
  "overall_score": 82.0,
  "categories": {
    "savings_consistency": { "score": 15, "max": 20 },
    "debt_ratio": { "score": 20, "max": 20 },
    "spending_discipline": { "score": 16, "max": 20 },
    "emergency_funds": { "score": 15, "max": 20 },
    "investments": { "score": 10, "max": 10 },
    "subscription_management": { "score": 6, "max": 10 }
  },
  "explanation": "Your portfolio demonstrates strong debt management...",
  "actionable_improvements": [
    "Set up automated transfers to your Savings account right after payday."
  ]
}
```

---

### GET /api/ai/coaching/briefing
AI-generated daily financial briefing. Cached 1 hour.

**Response:**
```json
{
  "date": "2026-05-24",
  "user_name": "Alex Doe",
  "briefing": "DAILY BRIEFING:\n\nYour liquid capital stands at $59,637...",
  "metrics": {
    "total_liquid_capital": 59637.82,
    "monthly_income_projection": 5100.00,
    "monthly_burn_rate": 3240.50
  }
}
```

---

### GET /api/ai/behavior/insights
Spending behavior analysis. Cached 10 minutes.

**Response:**
```json
{
  "insights": [
    "Weekend spending is 34% higher than weekday average",
    "Late-night transactions detected 3 times this month"
  ],
  "metrics": {
    "weekend_pct": 34.2,
    "late_night_count": 3,
    "avg_transaction_amount": 67.40
  }
}
```

---

### GET /api/ai/twin/predict
Balance forecast for next 30 days. Cached 5 minutes.

**Response:**
```json
{
  "current_balance": 59637.82,
  "predicted_balance_30d": 61200.00,
  "monthly_projections": [
    { "month": 1, "balance": 61200, "savings": 1562 }
  ],
  "confidence": "high"
}
```

---

### GET /api/ai/twin/future
Long-term balance projection.

**Query params:** `months` (1-60, default 12)

---

### GET /api/ai/twin/scenarios
Conservative / expected / optimistic scenarios.

**Query params:** `months` (1-24, default 6)

**Response:**
```json
{
  "scenarios": {
    "conservative": [58000, 58500, 59000],
    "expected": [60000, 61500, 63000],
    "optimistic": [62000, 64500, 67000]
  }
}
```

---

### GET /api/ai/fraud/analysis
All fraud alerts for the user.

**Response:**
```json
{
  "total_alerts": 1,
  "pending_reviews": 1,
  "alerts": [
    {
      "fraud_log_id": "uuid",
      "transaction_id": "uuid",
      "amount": 847.00,
      "merchant": "Tech Store NYC",
      "risk_score": 78.0,
      "details": "Amount 3.2x above average. Late-night transaction.",
      "status": "pending"
    }
  ]
}
```

---

### POST /api/ai/chat
HTTP chat endpoint (fallback when WebSocket unavailable).

**Request:**
```json
{ "message": "Analyze my spending this month" }
```

**Response:**
```json
{ "response": "Your spending this month totals $3,240..." }
```

---

### POST /api/ai/simulate/purchase
Simulate the impact of a purchase on your finances.

**Request:**
```json
{
  "amount": 1200.00,
  "merchant": "Apple Store",
  "category": "Tech"
}
```

---

## WebSocket Chat

### WS /api/ai/chat/ws

Connect: `ws://localhost:8000/api/ai/chat/ws?user_id={id}`

**Client → Server:**
```json
{ "type": "chat", "message": "What is my savings rate?" }
{ "type": "ping" }
```

**Server → Client:**
```json
{ "type": "chat_start" }
{ "type": "chat_chunk", "content": "Your " }
{ "type": "chat_chunk", "content": "savings " }
{ "type": "chat_chunk", "content": "rate is 36.5%..." }
{ "type": "chat_end" }
{ "type": "pong" }
{ "type": "error", "message": "..." }
```

**Connection lifecycle:**
- Heartbeat: client sends `ping` every 25s
- Reconnect: exponential backoff (1s, 2s, 4s, 8s, 16s, 30s max)
- HTTP fallback: if WS unavailable, falls back to POST /api/ai/chat

---

## Transactions

### GET /api/transactions/
Paginated transaction history.

**Query params:**
- `page` (default 1)
- `limit` (default 20, max 100)
- `category` (filter by category)
- `type` (credit or debit)
- `user_id` (optional)

**Response:**
```json
{
  "transactions": [
    {
      "id": "uuid",
      "merchant": "Whole Foods",
      "category": "Groceries",
      "amount": -87.43,
      "type": "debit",
      "timestamp": "2026-05-24T14:32:00",
      "tags": ["groceries"]
    }
  ],
  "total": 301,
  "page": 1,
  "pages": 16
}
```

---

## Notifications

### GET /api/notifications/
List user notifications.

**Query params:** `limit` (default 20), `user_id`

**Response:**
```json
{
  "notifications": [
    {
      "id": "uuid",
      "title": "Unusual Transaction Detected",
      "message": "A charge of $847.00 at Tech Store NYC was flagged...",
      "type": "alert",
      "read": false,
      "created_at": "2026-05-24T22:00:00"
    }
  ],
  "unread_count": 3
}
```

### PATCH /api/notifications/{id}/read
Mark a notification as read. Returns `{ "success": true }`

### PATCH /api/notifications/read-all
Mark all notifications as read. Returns `{ "success": true }`

### DELETE /api/notifications/{id}
Dismiss a notification. Returns `{ "success": true }`

---

## Observability

### GET /health
```json
{
  "status": "healthy",
  "timestamp": 1748131200.0,
  "db": "sqlite",
  "cache": "memory",
  "uptime_s": 771.0
}
```

### GET /api/status
```json
{
  "ai_backend": "groq",
  "ai_available": true,
  "db_type": "sqlite",
  "cache_type": "memory",
  "version": "2.0.0"
}
```

### GET /api/metrics
Live observability dashboard:
```json
{
  "uptime_seconds": 771.0,
  "requests": {
    "total": 20,
    "errors": 0,
    "auth_failures": 0,
    "error_rate_pct": 0.0
  },
  "websocket": { "total_connects": 0, "reconnects": 0 },
  "ai": {
    "fallbacks": 0,
    "by_provider": {
      "groq": { "calls": 2, "errors": 0, "avg_latency_ms": 1840.5, "p95_latency_ms": null }
    }
  },
  "cache": { "hits": 12, "misses": 8, "hit_ratio_pct": 60.0 },
  "route_timings": {
    "/api/dashboard/overview": { "calls": 4, "avg_ms": 17.3, "max_ms": 50.0 }
  },
  "recent_errors": []
}
```