Hugging Face's logo

Spaces:
mohsin-devs
/
BankBot-AI
Build error

App Files Community
BankBot-AI / docs /API_DOCUMENTATION.md
mohsin-devs's picture
mohsin-devs
Deploy to HF
a282d4b
preview code
|
raw
history blame contribute delete
8.52 kB

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:

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

Response 201:

{
  "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:

{ "refresh_token": "eyJhbGci..." }

Response:

{ "access_token": "eyJhbGci...", "token_type": "bearer" }

GET /api/auth/me

Get current authenticated user profile.

Response:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{ "message": "Analyze my spending this month" }

Response:

{ "response": "Your spending this month totals $3,240..." }

POST /api/ai/simulate/purchase

Simulate the impact of a purchase on your finances.

Request:

{
  "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:

{ "type": "chat", "message": "What is my savings rate?" }
{ "type": "ping" }

Server → Client:

{ "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:

{
  "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:

{
  "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 

{
  "status": "healthy",
  "timestamp": 1748131200.0,
  "db": "sqlite",
  "cache": "memory",
  "uptime_s": 771.0
}

GET /api/status 

{
  "ai_backend": "groq",
  "ai_available": true,
  "db_type": "sqlite",
  "cache_type": "memory",
  "version": "2.0.0"
}

GET /api/metrics

Live observability dashboard:

{
  "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": []
}