API reference

Capitrack exposes a RESTful JSON API for every operation in the app. Everything you can do in the UI you can automate — managing accounts, recording transactions, importing CSVs, tracking goals, fetching prices and reading settings.

Base URL & conventions

All endpoints are mounted under /api on the host you run Capitrack on. In the normal Docker setup the browser calls them on the same origin as the web app (port 3000) and nginx proxies them to the API container.

http://localhost:3000/api

• JSON is snake_case. Request and response bodies use snake_case (base_currency, account_id, tag_ids, change_percent…). The one exception is the change-password endpoint, which uses camelCase (currentPassword, newPassword). Dictionary-keyed responses (the /prices/quotes map keyed by symbol) keep their original keys.
• IDs in paths are integers; dates are YYYY-MM-DD strings.
• Error shape: failures return { "error": "message" }; simple successes often return { "message": "..." }.

Authentication

Capitrack uses a session cookie. Call POST /api/auth/login to start a session; the server sets the capitrack.sid cookie (HttpOnly, 7-day sliding expiry). Send that cookie with every subsequent request. All endpoints require it except POST /auth/login, POST /auth/logout, GET /auth/session and GET /health, which are anonymous. Unauthenticated calls return 401 (not a redirect).

Log in

$ curl -X POST http://localhost:3000/api/auth/login \
    -H "Content-Type: application/json" \
    -c cookies.txt \
    -d '{ "username": "admin", "password": "your-password" }'

{
  "username": "admin",
  "base_currency": "EUR"
}

Returns 401 { "error": "Invalid credentials" } for a bad username/password.

Change password

This endpoint is the exception that uses a camelCase body.

{
  "currentPassword": "your-password",
  "newPassword": "N3w!Secret"
}

Accounts

Create an account

$ curl -X POST http://localhost:3000/api/accounts \
    -H "Content-Type: application/json" -b cookies.txt \
    -d '{ "name": "Stocks", "type": "stock", "currency": "USD",
         "icon": "chart-line", "color": "#10b981", "tag_ids": [] }'

Omitted fields default: type=general, currency=EUR, icon=wallet, color=#6366f1. Returns 201 with the created account, or 400 if name is empty.

Transactions

A transaction's type is one of buy, sell, transfer_in, transfer_out, dividend, interest, fee.

List transactions

$ curl -b cookies.txt \
    "http://localhost:3000/api/transactions?account_id=1&limit=50"

[
  {
    "id": 12,
    "account_id": 1,
    "account_name": "Stock Portfolio",
    "symbol": "AAPL",
    "type": "buy",
    "quantity": 10.0,
    "price": 150.0,
    "fee": 1.0,
    "currency": "USD",
    "date": "2024-02-01",
    "tags": []
  }
]

Import a CSV

multipart/form-data with file (required), account_id (required) and an optional format to force a parser. The same response shape is returned by the UI:

$ curl -X POST http://localhost:3000/api/transactions/import/csv \
    -b cookies.txt \
    -F "[email protected]" -F "account_id=1"

{ "imported": 8, "skipped": 2, "total": 10, "errors": [], "format": "revolut-stocks" }

See CSV import for the supported formats and field mapping.

Goals

Tags

Currencies

{ "result": 92.0, "rate": 0.92 }

If from == to the amount is returned unchanged with rate: 1. Returns 404 if no rate exists for the pair.

Prices

Quotes come from Yahoo Finance and carry only the fields the quote/chart source provides (symbol, price, currency, name, change_percent); richer fields like P/E or market cap are not fetched. Quotes are cached for 5 minutes with a stale fallback.

Dashboard summary

{
  "total_wealth": 25340.55,
  "total_cost": 21000.0,
  "total_gain": 4340.55,
  "total_gain_percent": 20.67,
  "base_currency": "EUR",
  "accounts": [ { "account_id": 1, "account_name": "Crypto Portfolio", "market_value": 12000.0, "cost_basis": 9000.0, "holdings_count": 2 } ],
  "holdings_count": 5
}

Settings

Health

Status codes