Skip to main content

API Reference

REST API endpoints for the Hello Goblin webapp.

Authentication​

All endpoints (except login) require JWT authentication.

Login​

POST /api/auth/login/
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "your-password"
}

Response:

{
  "access": "eyJ0eXAiOiJKV1QiLCJhbGci...",
  "refresh": "eyJ0eXAiOiJKV1QiLCJhbGci..."
}

Using Tokens​

GET /api/accounts/
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGci...

Refresh Token​

POST /api/auth/refresh/
Content-Type: application/json

{
  "refresh": "eyJ0eXAiOiJKV1QiLCJhbGci..."
}

Accounts​

List Accounts​

GET /api/accounts/

Query parameters:

  • account_type - Filter by type (checking, savings, credit, investment)
  • is_active - Filter by active status

Get Account​

GET /api/accounts/{id}/

Get Balance History​

GET /api/accounts/{id}/balances/

Query parameters:

  • start_date - Start date (YYYY-MM-DD)
  • end_date - End date (YYYY-MM-DD)

Transactions​

List Transactions​

GET /api/transactions/

Query parameters:

  • account - Filter by account ID
  • category - Filter by category ID
  • start_date - Start date
  • end_date - End date
  • min_amount - Minimum amount
  • max_amount - Maximum amount
  • search - Search in description/merchant
  • page - Page number
  • page_size - Results per page (default: 50)

Update Transaction​

PUT /api/transactions/{id}/
Content-Type: application/json

{
  "category": 5,
  "notes": "Monthly subscription"
}

Analytics​

Net Worth​

GET /api/analytics/net-worth/

Query parameters:

  • months - Number of months (default: 12)

Response:

{
  "current": 150000.00,
  "history": [
    {"month": "2024-01", "assets": 200000, "liabilities": 50000, "net_worth": 150000}
  ]
}

Profit & Loss​

GET /api/analytics/pnl/

Query parameters:

  • year - Year (default: current)
  • month - Month (optional, for single month)

Spending by Category​

GET /api/analytics/spending-by-category/

Query parameters:

  • year - Year
  • month - Month

Balance Sheet​

GET /api/analytics/balance-sheet/

Debt​

List Debt Accounts​

GET /api/debt/accounts/

List Payoff Scenarios​

GET /api/debt/scenarios/

Create Scenario​

POST /api/debt/scenarios/
Content-Type: application/json

{
  "name": "Aggressive Payoff",
  "strategy": "avalanche",
  "extra_payment": 500.00
}

Get Projections​

GET /api/debt/projections/?scenario={id}

AI Agent​

Get Insights​

GET /api/ai/insights/

Query parameters:

  • insight_type - Filter by type
  • severity - Filter by severity
  • acknowledged - Filter by acknowledged status

Get Recommendations​

GET /api/ai/recommendations/

Query parameters:

  • status - pending, approved, executed, rejected

Execute Trade​

POST /api/ai/execute-trade/
Content-Type: application/json

{
  "recommendation_id": 123
}

Chat​

POST /api/ai/chat/
Content-Type: application/json

{
  "message": "What were my biggest expenses last month?"
}

Integrations​

POST /api/integrations/plaid/link-token/

Exchange Plaid Token​

POST /api/integrations/plaid/exchange-token/
Content-Type: application/json

{
  "public_token": "public-sandbox-..."
}

Schwab Authorization​

POST /api/integrations/schwab/authorize/

Returns OAuth URL to redirect user.

Trigger Sync​

POST /api/sync/trigger/
Content-Type: application/json

{
  "source": "monarch"  // monarch, plaid, schwab, fred, all
}

Notifications​

List Notifications​

GET /api/notifications/

Mark as Read​

POST /api/notifications/{id}/read/

Update Preferences​

PUT /api/notifications/preferences/
Content-Type: application/json

{
  "sms_enabled": true,
  "email_enabled": true,
  "push_enabled": false,
  "large_transaction_alerts": true,
  "budget_alerts": true
}

Error Responses​

All errors return JSON:

{
  "error": "error_code",
  "message": "Human readable message",
  "details": {}
}

Common status codes:

  • 400 - Bad request (validation error)
  • 401 - Unauthorized (invalid/missing token)
  • 403 - Forbidden (insufficient permissions)
  • 404 - Not found
  • 429 - Rate limited
  • 500 - Server error

Rate Limits​

EndpointLimit
Authentication5/minute
Trading10/minute
General100/minute

API Documentation​

Interactive documentation available at: