Backend HTTP Surface
Use this page for controller-level contract summaries after they have been verified against the backend implementation.
Truth Sources
When this page and the implementation disagree, use this order:
- backend controllers under
core/backend/src/**/interfaces/http/ - backend application and supporting services
- backend workspace manifests and scripts
- this page
Runtime Surface
| Surface | Notes |
|---|---|
GET /health | Aggregate finance backend health response |
GET /health/live | Liveness probe |
GET /health/ready | Readiness probe |
GET /ops/metrics | Prometheus-compatible metrics payload, including process defaults plus HTTP request count and duration |
POST /auth/register | Create a local email/password user and return a bearer session |
POST /auth/login | Authenticate a local user and return a bearer session |
GET /auth/me | Return the current bearer-session user |
GET /auth/google/start | Redirect to Google OAuth using configured client credentials |
GET /auth/google/callback | Complete Google OAuth, create/link the user, and redirect to the frontend callback route |
GET /finance/overview | Dashboard read model with net worth, cashflow, accounts, transactions, budgets, goals, bills, chart data, selected range, and review count for the active finance month |
GET /finance/overview?period=YYYY-MM | Dashboard read model for an explicit selected month; response includes periodKey, rangeStart, rangeEnd, and availablePeriods |
GET /finance/overview?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD&account=<account> | Dashboard read model filtered to a custom date range and finance account |
GET /finance/accounts | Account overview records |
POST /finance/accounts | Create an account record |
GET /finance/categories | Return user-scoped categories, including delete-protected defaults, custom categories, and usage counts from transactions, recurring entries, and budgets |
POST /finance/categories | Create a custom category for the authenticated user |
PATCH /finance/categories/:id | Rename any authenticated-user category and update same-user transactions, recurring entries, and budgets using it |
DELETE /finance/categories/:id | Delete an unused custom category; default categories and categories with transactions, recurring entries, or budgets are rejected |
GET /finance/transactions | Recent ledger transactions |
POST /finance/transactions | Create a transaction and apply its balance impact |
PATCH /finance/transactions/review | Mark selected authenticated-user transactions reviewed, optionally applying one category in bulk |
PATCH /finance/transactions/bulk | Update selected authenticated-user transactions in one database transaction, currently category and/or source account |
DELETE /finance/transactions/bulk | Delete selected authenticated-user transactions in one database transaction and reverse their balance impact |
POST /finance/voice/interpret | Upload a short audio command, transcribe it with Speech-to-Text, interpret it with Gemini Flash-Lite or local rules, normalize the result against transcript facts, and return a preview-only action, including safe open_route tab navigation for known routes |
POST /finance/voice/confirm | Confirm a previewed voice create_transaction action and save it as a review-tagged authenticated-user transaction |
POST /finance/imports/invoice/preview | Parse a CSV/TXT invoice upload into a reviewable expense preview |
POST /finance/imports/invoice/jobs | Enqueue one to five invoice/statement files for async Gemini classification, or return a completed cached job when the same scoped file content was already classified; digital PDFs send bounded extracted text so the model can ignore document noise and return real transaction rows with persisted progress, summary totals, and classificationSource |
GET /finance/imports/jobs/notifications | Return unread completed/failed import-job notifications for the authenticated user |
GET /finance/imports/jobs/:id | Return one authenticated user's import classification job, including progressPercent, progressMessage, income/spend/transfer summary totals, errors/fallbacks, and completed preview when ready |
PATCH /finance/imports/jobs/:id/read | Mark an import-job notification read |
POST /finance/imports/invoice/confirm | Import selected invoice preview rows as ledger withdrawals, deposits, or transfers after server-side direction normalization |
POST /finance/imports/statement/preview | Parse a CSV/TXT/basic OFX bank statement into a reviewable ledger preview |
POST /finance/imports/statement/confirm | Import selected statement rows as scoped ledger withdrawals, deposits, or transfers |
PATCH /finance/transactions/:id | Update a transaction and reapply its balance impact |
DELETE /finance/transactions/:id | Delete a transaction and reverse its balance impact |
GET /finance/budgets | User-scoped category budgets with active flag and computed spend |
POST /finance/budgets | Create a category budget with period, monthly amount, currency, and active flag |
PATCH /finance/budgets/:id | Update one authenticated user's category budget |
DELETE /finance/budgets/:id | Delete one authenticated user's category budget |
GET /finance/automation | Bills, recurring transactions with category, and rules |
POST /finance/automation/recurring-transactions | Create a user-scoped recurring expense entry using an existing category |
PATCH /finance/automation/recurring-transactions/:id | Update one authenticated user's recurring expense entry |
DELETE /finance/automation/recurring-transactions/:id | Delete one authenticated user's recurring expense entry |
GET /finance/reports | Cashflow, category-spend, and budget-performance report data |
GET /finance/feature-map | Clean rewrite parity map |
Finance endpoints require a bearer session and must return only records owned by the authenticated user.
Backend responses include x-request-id. Error responses are normalized with requestId, statusCode, message, path, and timestamp so UI/support can correlate failures with logs and metrics.