All endpoints are mounted under /api. 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.
- JSON is snake_case. Request and response bodies use snake_case property names
(
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/quotesmap keyed by symbol) keep their original keys. - Authentication is a cookie. Log in via
POST /api/auth/login; the server sets thecapitrack.sidcookie. All endpoints require the cookie exceptPOST /auth/login,POST /auth/logout,GET /auth/session, andGET /health, which are anonymous. - Unauthenticated calls return
401(not a redirect) with{ "error": "..." }. - Status codes:
200 OKfor reads/updates/deletes,201 Createdfor creates,400 Bad Requestfor validation errors,401 Unauthorizedfor auth failures,404 Not Foundfor missing resources/symbols,500for upstream/price errors. - Error shape: failures return
{ "error": "human-readable message" }. Simple successes often return{ "message": "..." }. - IDs in paths are integers (
{id:int}). Dates areYYYY-MM-DDstrings.
Authenticate and receive the session cookie.
Body:
{ "username": "admin", "password": "your-password" }200:
{ "username": "admin", "base_currency": "EUR" }400 if username/password missing; 401 { "error": "Invalid credentials" } otherwise.
Clears the session cookie. 200 → { "message": "Logged out" }.
Returns the current user if the cookie is valid, else 401.
200:
{ "username": "admin", "base_currency": "EUR" }401 → { "error": "Not authenticated" }.
Change the password. camelCase body (the exception to the snake_case rule).
{ "currentPassword": "admin", "newPassword": "N3w!Secret" }The new password must be ≥ 8 characters and contain an uppercase letter, a lowercase
letter, a digit, and one of ! @ # $ % ^ & *.
200 → { "message": "Password updated" }. 400 if missing or too weak; 401
{ "error": "Current password is incorrect" }.
Set the user's base/main currency (drives dashboard conversions).
{ "base_currency": "USD" }200 → { "message": "Base currency updated" }. 400 if missing.
An account DTO:
{
"id": 1,
"name": "Crypto Portfolio",
"type": "crypto",
"currency": "USD",
"description": "Main crypto holdings",
"icon": "bitcoin",
"color": "#f59e0b",
"created_at": "2026-05-31T10:00:00",
"updated_at": "2026-05-31T10:00:00",
"tags": []
}List all accounts (newest first). 200 → array of account DTOs.
Create an account. Only name is required; the rest default
(type=general, currency=EUR, icon=wallet, color=#6366f1).
{ "name": "Stocks", "type": "stock", "currency": "USD",
"description": "", "icon": "chart-line", "color": "#10b981",
"tag_ids": [1, 2] }201 → the created account DTO. 400 if name is empty.
200 → account DTO. 404 if not found.
Partial update — omitted/empty fields keep their current value; tag_ids, when supplied,
replaces the account's tag set. 200 → updated DTO. 404 if not found.
Deletes the account (and, via cascade, its transactions and tag links). 200 →
{ "message": "Account deleted" }. 404 if not found.
Per-symbol holdings for the account (quantity, average cost, total cost, transaction count, first/last dates), ordered by total cost descending.
[
{
"symbol": "BTC-USD",
"quantity": 0.5,
"avg_cost": 30000.0,
"total_cost": 15010.0,
"transaction_count": 2,
"first_transaction": "2024-01-10",
"last_transaction": "2024-03-02"
}
]404 if the account does not exist.
Danger-zone wipe: deletes all accounts, transactions, goals, tags, and cached prices.
200 → { "message": "All accounts, transactions, goals, and cached prices have been purged." }.
A transaction DTO:
{
"id": 12,
"account_id": 1,
"symbol": "AAPL",
"type": "buy",
"quantity": 10.0,
"price": 150.0,
"fee": 1.0,
"currency": "USD",
"date": "2024-02-01",
"notes": "",
"created_at": "2024-02-01T09:00:00",
"account_name": "Stock Portfolio",
"tags": []
}type is one of buy, sell, transfer_in, transfer_out, dividend, interest, fee.
List transactions (newest first by date, then id). Query parameters (all optional):
| Param | Meaning |
|---|---|
account_id |
filter to one account |
symbol |
filter to one symbol |
limit |
max rows to return |
offset |
rows to skip (paging) |
200 → array of transaction DTOs.
200 → transaction DTO. 404 if not found.
Create a transaction. account_id, symbol, type, and date are required; numeric
fields default to 0 and currency defaults to EUR. The symbol is upper-cased.
{ "account_id": 1, "symbol": "aapl", "type": "buy",
"quantity": 10, "price": 150, "fee": 1, "currency": "USD",
"date": "2024-02-01", "notes": "", "tag_ids": [] }201 → created DTO. 400 if required fields missing; 404 if the account doesn't exist.
Partial update (same omit-keeps-value semantics as accounts; tag_ids replaces the set).
200 → updated DTO. 404 if not found.
200 → { "message": "Transaction deleted" }. 404 if not found.
Download transactions as CSV (optionally filtered by account_id). Returns a text/csv
file (transactions.csv) with columns:
id, account_name, symbol, type, quantity, price, fee, currency, date, notes.
Import a CSV file. multipart/form-data with:
| Field | Required | Meaning |
|---|---|---|
file |
yes | the CSV file |
account_id |
yes | target account |
format |
no | force a format (revolut-stocks, revolut-commodities, trezor, generic); auto-detected if omitted |
200:
{ "imported": 8, "skipped": 2, "total": 10, "errors": [], "format": "revolut-stocks" }400 if file missing or the CSV cannot be parsed; 404 if the account doesn't exist.
See csv-import.md for format details.
Detect the format of a CSV without importing. multipart/form-data with file.
200:
{ "format": "trezor", "headers": ["Transaction ID", "Type", "Amount", "Amount unit", "Date"] }format is unknown when no parser matches.
A goal DTO:
{
"id": 1,
"title": "Emergency fund",
"target_amount": 10000.0,
"target_date": "2026-12-31",
"description": "",
"achieved": 0,
"category_id": null,
"created_at": "2026-01-01T00:00:00",
"updated_at": "2026-01-01T00:00:00",
"tags": []
}List goals (ordered by target date). Optional query: category_id, tag_id. 200 → array.
200 → goal DTO. 404 if not found.
title and target_date required.
{ "title": "Emergency fund", "target_amount": 10000, "target_date": "2026-12-31",
"description": "", "achieved": false, "tag_ids": [] }201 → created DTO. 400 if title/target date missing.
Partial update. achieved is a boolean in the request but stored as 0/1 and returned as an
integer. 200 → updated DTO. 404 if not found.
200 → { "message": "Goal deleted" }. 404 if not found.
Delete all goals. 200 → { "message": "All goals deleted" }.
A tag DTO: { "id": 1, "name": "long-term", "color": "#6366f1", "created_at": "..." }.
List tags (alphabetical). 200 → array.
200 → tag DTO. 404 if not found.
name required; color defaults to #6366f1. 201 → created DTO. 400 if name missing
or a tag with that name already exists.
Update name/color. 200 → updated DTO. 400 if the new name collides with another tag;
404 if not found.
200 → { "message": "Tag deleted" }. 404 if not found.
A rate DTO:
{ "id": 1, "from_currency": "USD", "to_currency": "EUR", "rate": 0.92, "updated_at": "..." }.
List rates (ordered by from/to). 200 → array.
Upsert a rate by (from_currency, to_currency). Currencies are upper-cased.
{ "from_currency": "USD", "to_currency": "EUR", "rate": 0.92 }201 → the saved rate DTO. 400 if any field missing. (If the pair already exists its rate
is updated in place.)
Update a rate by id. 200 → updated DTO. 404 if not found.
200 → { "message": "Rate deleted" }. 404 if not found.
Convert an amount. Query: from, to, amount (all required).
GET /api/currencies/convert?from=USD&to=EUR&amount=100
200 → { "result": 92.0, "rate": 0.92 }. If from == to, returns the amount unchanged
with rate: 1. 400 if a param is missing; 404 if no rate exists for the pair.
A quote DTO carries only the fields Yahoo's quote/chart-meta provides:
{ "symbol": "AAPL", "price": 187.4, "currency": "USD", "name": "Apple Inc.", "change_percent": 0.83 }A stale boolean is added only when the value came from a stale cache. (Richer fields such
as P/E or market cap are not fetched — see architecture.md.)
Live quote for one symbol (5-minute cache, stale fallback). 200 → quote DTO. 404
{ "error": "Could not fetch price for X" } if nothing is available.
Batch quotes. Body { "symbols": ["AAPL", "BTC-USD"] }. Returns a map keyed by symbol
(keys are not snake_cased):
{
"AAPL": { "symbol": "AAPL", "price": 187.4, "currency": "USD", "name": "Apple Inc.", "change_percent": 0.83 },
"BTC-USD": { "symbol": "BTC-USD", "price": 0, "error": "Service unavailable" }
}400 if symbols is missing.
Historical OHLCV. Query period (default 1y): 1w, 1m, 3m, 6m, 1y, 5y, or
max. (The interval is chosen automatically: hourly for 1w, daily for 1m, otherwise
weekly.) 200 → array of points with a non-null close:
[ { "date": "2024-01-05T00:00:00", "close": 181.2, "open": 180.0, "high": 182.1, "low": 179.5, "volume": 51000000 } ]404 if history can't be fetched.
Symbol search via Yahoo. 200:
[ { "symbol": "AAPL", "name": "Apple Inc.", "type": "EQUITY", "exchange": "NMS" } ]500 on upstream error.
Total wealth, cost, and gain in the base currency, plus a per-account breakdown.
{
"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
}500 on error.
Portfolio value over time (transaction replay over historical prices, no FX conversion).
Query account_id (optional, scope to one account) and period (default 3m): 1w, 1m,
3m, 6m, ytd, 1y, 5y, all.
[ { "date": "2024-03-01", "value": 18250.0, "cost": 17000.0, "gain": 1250.0 } ]500 on error.
Saved daily-wealth snapshots between two dates. Query start, end (YYYY-MM-DD, both
required).
[ { "date": "2026-05-30", "total_wealth": 25000.0, "total_cost": 21000.0,
"base_currency": "EUR", "details": { "accounts": [], "holdings_count": 5 } } ]400 if start/end missing.
Compute and upsert today's snapshot using cached prices. 200:
{ "date": "2026-05-31", "total_wealth": 25340.55, "total_cost": 21000.0, "base_currency": "EUR" }{ "db_path": "/app/data/capitrack.db", "version": "1.0.0",
"app_name": "Capitrack", "repository": "https://github.com/jeff-nasseri/Capitrack",
"license": "MIT" }{ "path": "/app/data/capitrack.db", "exists": true }Set the SQLite path (persisted to settings.json; takes effect on restart). Body
{ "path": "/app/data/capitrack.db" }. Creates the directory if needed.
200 → { "message": "Database path updated successfully", "path": "...", "exists": false }.
400 if the path is missing or the directory can't be created.
A no-op "refresh" hook. 200 → { "message": "Application refreshed successfully", "db_path": "..." }.
{ "name": "Capitrack",
"description": "Personal wealth tracking and investment portfolio management platform",
"version": "1.0.0", "license": "MIT",
"repository": "https://github.com/jeff-nasseri/Capitrack",
"author": "Jeff Nasseri", "open_source": true }200 → { "status": "ok" }. Used by the API container's Docker healthcheck.