Skip to main content
The Finance REST API is a set of read-only HTTP endpoints that expose the same analytical queries powering the AI agent. Every route under /api/finance/ is a thin wrapper around agent/lib/finance.ts — the shared library that both the REST routes and the agent’s authored tools call into directly. This means the REST API and the agent always return identical numbers for the same inputs; there is no separate data path, no synchronisation lag, and no extra service to run.

​
Base URL

All endpoints are served from the same origin as the Next.js application. There is no separate API service and no base-URL environment variable to configure.
Because the API is co-located with the frontend at the same origin, there are no CORS restrictions on same-origin requests. Cross-origin clients may make requests freely in the demo configuration.

​
Authentication

No authentication is required. The eve channel is configured with none() auth, which means all /api/finance/* endpoints are publicly accessible in the current demo setup. Before pointing the application at real (non-synthetic) financial data, replace none() in agent/channels/eve.ts with a real auth provider such as vercelOidc() and add equivalent middleware to the REST routes.

​
All Endpoints

​
Error Handling

Every route that accepts query parameters validates them against a Zod schema using the shared parseQuery helper (agent/lib/api-route.ts). If validation fails, the route returns a 400 Bad Request response with a JSON body describing the validation errors:
On success, all routes return 200 OK with a JSON body. There are no partial-success or pagination envelopes — the full result set is returned in a single response.

​
Date Format

All date parameters (from, to, and month) are plain YYYY-MM-DD strings. Dates are inclusive on both ends: a request with from=2025-01-01&to=2025-03-31 includes all transactions on both January 1 and March 31. The month parameter accepted by /budget-status is truncated to the first of the month internally, so passing any date within the target month (e.g. 2025-06-15) is equivalent to passing 2025-06-01.
These endpoints share the same analytics library as the agent tools. Any change to agent/lib/finance.ts is automatically reflected in both the REST API and the agent.

​
Endpoint Pages

GET /summary

Total income, expense, and net profit for a date range.

GET /trend

Monthly time series of income or expense, with optional department grouping.

GET /category-breakdown

Monthly totals broken down by spending or revenue category.

GET /cashflow

Monthly cash flow series with cumulative net profit.

GET /budget-status

Budget vs actual expense per department for a single month.

GET /anomalies

Statistical outlier transactions flagged by per-category mean and stddev.

GET /profitability

Income, expense, net profit, and margin per department for a date range.

GET /data-overview

Dataset metadata: date coverage, transaction counts, and category breakdown.

GET /highlights

Richer dataset meta used by the chat UI’s suggested question chips.