API reference

Reports

get/v1/reports/annual

Annual review

reports.annualread tokenidempotent

The year on one page: income, spending and net for each month; the categories it went to beside the year before; net worth from January to now; the biggest expenses; the goals; and the year's highlights.

Parameters

year integer \| null · query	Defaults to this year.
purpose string \| null · query	Only the `personal` or the `business` side of the ledger. Both when omitted.
X-Organization-Id string \| null · header

Returns 200 · AnnualReview

categories array of YearCategory · required	Biggest first.
currency string · required	The ledger's base currency; every amount is in it.
expenses Money · required
goals array of GoalProgress · required
highlights YearHighlights · required
income Money · required
income_sources array of IncomeSource · required
is_current boolean · required
largest_expenses array of LargestExpense · required
months array of YearMonth · required	Twelve, January to December.
months_elapsed integer · required	How many of the year's months have begun.
net Money · required
net_worth NetWorthChange · required
previous_expenses Money · required
previous_income Money · required
previous_net Money · required
previous_year integer · required
savings_rate string \| null · required	`net` / `income`. Pattern: `^-?\d+(\.\d+)?$`.
year integer · required

Example

curl -X GET "https://api.lumaledger.app/v1/reports/annual" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN"

get/v1/reports/monthly

Monthly report

reports.monthlyread tokenidempotent

The month on one page: what came in and went out, category by category beside last month and the budget; how the budget held; the recurring charges that landed; the biggest expenses; what net worth did; and the savings goals. While the month is running the figures are month-to-date.

Parameters

month string \| null · query	`YYYY-MM`. Defaults to this month.
purpose string \| null · query	Only the `personal` or the `business` side of the ledger. Both when omitted.
X-Organization-Id string \| null · header

Returns 200 · MonthlyReport

budgets ReportBudgetSummary · required
categories array of ReportCategory · required	Expense categories with activity this month or last, or a plan; biggest first.
currency string · required	The ledger's base currency; every amount is in it.
expenses Money · required
goals array of GoalProgress · required
income Money · required
income_sources array of IncomeSource · required
is_current boolean · required	The month is still running: figures are month-to-date.
is_future boolean · required	The month has not started: everything but the plan is zero.
largest_expenses array of LargestExpense · required
month string · required	`YYYY-MM`.
net Money · required	`income` − `expenses`.
net_worth NetWorthChange · required
previous_expenses Money · required
previous_income Money · required
previous_month string · required
previous_net Money · required
recurring RecurringSummary · required
savings_rate string \| null · required	`net` / `income`; null when nothing came in. Pattern: `^-?\d+(\.\d+)?$`.

Example

curl -X GET "https://api.lumaledger.app/v1/reports/monthly" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN"

get/v1/reports/recap

Monthly recap

reports.recapread tokenidempotent

A month's highlights, read off its monthly report: spending against the month before, the savings rate, budgets kept, net worth growth, the biggest drop in a category, goals reached. Wins lead; nothing is invented.

Parameters

month string \| null · query	`YYYY-MM`. Defaults to the last complete month.
X-Organization-Id string \| null · header

Returns 200 · Recap

currency string · required
is_current boolean · required
moments array of RecapMoment · required
month string · required	`YYYY-MM`.
previous_month string · required

Example

curl -X GET "https://api.lumaledger.app/v1/reports/recap" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN"

Objects

AnnualReview

One year, or the year so far: month by month, where the money went beside the year before, net worth, the biggest expenses and the goals. While the year is running, the year before is compared over the same months.

Fields

categories array of YearCategory · required	Biggest first.
currency string · required	The ledger's base currency; every amount is in it.
expenses Money · required
goals array of GoalProgress · required
highlights YearHighlights · required
income Money · required
income_sources array of IncomeSource · required
is_current boolean · required
largest_expenses array of LargestExpense · required
months array of YearMonth · required	Twelve, January to December.
months_elapsed integer · required	How many of the year's months have begun.
net Money · required
net_worth NetWorthChange · required
previous_expenses Money · required
previous_income Money · required
previous_net Money · required
previous_year integer · required
savings_rate string \| null · required	`net` / `income`. Pattern: `^-?\d+(\.\d+)?$`.
year integer · required

GoalProgress

Fields

name string · required
progress string · required	0–1. Pattern: `^-?\d+(\.\d+)?$`.
reached boolean · required
saved Money · required
savings_goal_id integer · required
target_amount Money · required

IncomeSource

Fields

amount Money · required
category_id integer · required	The income account (`accounts.list?type=income`).
code string · required
name string · required
previous_amount Money · required	The same window of the period before.

LargestExpense

Fields

amount Money · required
category string \| null · required	The category it was filed under (the largest line, when split).
date date · required
description string · required
transaction_id integer · required	What `transactions.get` takes.

Money

An amount and its currency. `amount` is a base-10 string with two decimal places and an optional leading minus sign. Parse it with a decimal type, not a float.

Fields

amount string · required	Pattern: `^-?\d+\.\d{2}$`.
currency string · required	ISO 4217 code. Pattern: `^[A-Z]{3}$`.

MonthlyReport

One month: income and spending by category beside last month and the budget, recurring charges, the biggest expenses, net worth and goals.

Fields

budgets ReportBudgetSummary · required
categories array of ReportCategory · required	Expense categories with activity this month or last, or a plan; biggest first.
currency string · required	The ledger's base currency; every amount is in it.
expenses Money · required
goals array of GoalProgress · required
income Money · required
income_sources array of IncomeSource · required
is_current boolean · required	The month is still running: figures are month-to-date.
is_future boolean · required	The month has not started: everything but the plan is zero.
largest_expenses array of LargestExpense · required
month string · required	`YYYY-MM`.
net Money · required	`income` − `expenses`.
net_worth NetWorthChange · required
previous_expenses Money · required
previous_income Money · required
previous_month string · required
previous_net Money · required
recurring RecurringSummary · required
savings_rate string \| null · required	`net` / `income`; null when nothing came in. Pattern: `^-?\d+(\.\d+)?$`.

NetWorthChange

Fields

change Money · required
end Money · required	At the period's end, or today while it is running.
start Money · required	Net worth the night before the period began.

Recap

The few things about a month worth being told, wins first. A month with nothing to say has no moments.

Fields

currency string · required
is_current boolean · required
moments array of RecapMoment · required
month string · required	`YYYY-MM`.
previous_month string · required

RecapMoment

Fields

data object · required	The moment's figures, by kind. Ratios (`change`, `rate`, `share`) are 0–1 decimal strings; amounts are decimal strings in `currency`.
kind string · required	`spending_change`, `savings_rate`, `budgets_kept`, `net_worth_up`, `biggest_drop`, `top_category` or `goals`.
shareable boolean · required	Safe to share: it carries percentages and counts only, never an amount, a merchant or an account.
tone string · required	`positive` (a win) or `neutral` (a fact worth knowing).

RecurringSummary

Fields

charges array of ReportRecurringCharge · required
total Money · required

ReportBudgetSummary

Fields

available Money · required
budgeted Money · required
over_count integer · required	Plans that ended the month over.
planned integer · required	Categories with a plan this month.
remaining Money · required
spent Money · required
unbudgeted_spent Money · required	Spending in categories with no plan.

ReportCategory

Fields

available Money \| null · required	The plan plus what rolled over; null without a plan.
budgeted Money \| null · required	What the budget allows; null without a plan.
category_id integer · required	The expense account (`accounts.list?type=expense`).
code string · required
name string · required
parent_id integer \| null · required	The category this is a subcategory of.
previous_spent Money · required	Last month.
remaining Money \| null · required	`available` − `spent`; null without a plan.
spent Money · required

ReportRecurringCharge

Fields

amount Money · required	What it charged this month, summed if more than once.
cadence string · required	`weekly`, `monthly`, `annual`, …
merchant_key string · required
name string · required
occurrences integer · required

YearCategory

Fields

category_id integer · required	The expense account (`accounts.list?type=expense`).
code string · required
monthly_average Money · required
name string · required
previous_spent Money · required	The same months of the year before.
share string · required	Share of the year's spending, 0–1. Pattern: `^-?\d+(\.\d+)?$`.
spent Money · required

YearHighlights

Fields

best_month string \| null · required	The month that put the most aside.
highest_spending_month string \| null · required	`YYYY-MM`.
lowest_spending_month string \| null · required
months_in_the_black integer · required	Months that ended with income above spending.

YearMonth

Fields

expenses Money · required
income Money · required
month string · required	`YYYY-MM`.
net Money · required

year integer \| null · query	Defaults to this year.
purpose string \| null · query	Only the `personal` or the `business` side of the ledger. Both when omitted.
X-Organization-Id string \| null · header

month string \| null · query	`YYYY-MM`. Defaults to this month.
purpose string \| null · query	Only the `personal` or the `business` side of the ledger. Both when omitted.
X-Organization-Id string \| null · header