API reference

Savings Goals

get/v1/savings-goals

List savings goals

savings_goals.listread tokenidempotent

The ledger's savings goals, each measured against its account's balance today.

Parameters

limit integer · query	Page size, 1–200.
cursor string \| null · query	The `next_cursor` of the previous page.
X-Organization-Id string \| null · header

Returns 200 · SavingsGoalList

data array of SavingsGoal · required
has_more boolean · required
next_cursor string \| null · required

Example

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

post/v1/savings-goals

Create a savings goal

savings_goals.createwrite tokenidempotent

Set a target on an asset account: "6,000 in savings by June". Two goals may share an account; each measures the same balance.

Parameters

Idempotency-Key string \| null · header	Any unique string (a UUID is ideal). A retry with the same key returns the first attempt's response instead of doing the work twice. Keys are kept for 24 hours.
X-Organization-Id string \| null · header

Body · SavingsGoalCreate

account_id integer · required	An active asset account in this ledger (see `accounts.list?type=asset`).
baseline_amount string \| null	The balance the goal counts from. Omitted: the account's balance today, so only what is saved from now on counts. `"0"` counts the whole balance. Pattern: `^\d{1,12}(\.\d{1,2})?$`.
name string · required
target_amount string · required	More than zero; decimal string, at most two decimal places. Pattern: `^\d{1,12}(\.\d{1,2})?$`.
target_date date \| null

Returns 201 · SavingsGoal

account_balance Money · required	The account's balance right now.
account_id integer · required	The asset account the money sits in (see `accounts.list`).
account_name string · required
baseline_amount Money · required	The account balance the goal counts from.
id integer · required
monthly_needed Money \| null · required	What has to go in each month to make the date. Null with no date, or once the goal is reached or overdue.
name string · required
overdue boolean · required	The date has passed and the goal was not reached.
progress string · required	`saved` / `target_amount`, a decimal string from `0.0000` to `1.0000`. Pattern: `^\d\.\d{4}$`.
reached boolean · required
remaining Money · required
saved Money · required	`account_balance` − `baseline_amount`, between zero and the target.
target_amount Money · required
target_date date \| null · required

Example

curl -X POST "https://api.lumaledger.app/v1/savings-goals" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": 1,
    "name": "…",
    "target_amount": "6000.00"
  }'

delete/v1/savings-goals/{savings_goal_id}

Delete a savings goal

savings_goals.deletewrite tokendestructiveidempotent

Remove a savings goal. The account and its money are untouched.

Parameters

savings_goal_id integer · path · required
X-Organization-Id string \| null · header

Returns 204 with no body.

Example

curl -X DELETE "https://api.lumaledger.app/v1/savings-goals/{savings_goal_id}" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN"

get/v1/savings-goals/{savings_goal_id}

Get a savings goal

savings_goals.getread tokenidempotent

One savings goal by its id.

Parameters

savings_goal_id integer · path · required
X-Organization-Id string \| null · header

Returns 200 · SavingsGoal

account_balance Money · required	The account's balance right now.
account_id integer · required	The asset account the money sits in (see `accounts.list`).
account_name string · required
baseline_amount Money · required	The account balance the goal counts from.
id integer · required
monthly_needed Money \| null · required	What has to go in each month to make the date. Null with no date, or once the goal is reached or overdue.
name string · required
overdue boolean · required	The date has passed and the goal was not reached.
progress string · required	`saved` / `target_amount`, a decimal string from `0.0000` to `1.0000`. Pattern: `^\d\.\d{4}$`.
reached boolean · required
remaining Money · required
saved Money · required	`account_balance` − `baseline_amount`, between zero and the target.
target_amount Money · required
target_date date \| null · required

Example

curl -X GET "https://api.lumaledger.app/v1/savings-goals/{savings_goal_id}" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN"

patch/v1/savings-goals/{savings_goal_id}

Update a savings goal

savings_goals.updatewrite tokenidempotent

Rename a goal, move it to another account, or change its target, baseline or date. Only the fields sent change.

Parameters

savings_goal_id integer · path · required
X-Organization-Id string \| null · header

Body · SavingsGoalUpdate

account_id integer \| null	Move the goal to another asset account.
baseline_amount string \| null	Pattern: `^\d{1,12}(\.\d{1,2})?$`.
name string \| null
target_amount string \| null	Pattern: `^\d{1,12}(\.\d{1,2})?$`.
target_date date \| null

Returns 200 · SavingsGoal

account_balance Money · required	The account's balance right now.
account_id integer · required	The asset account the money sits in (see `accounts.list`).
account_name string · required
baseline_amount Money · required	The account balance the goal counts from.
id integer · required
monthly_needed Money \| null · required	What has to go in each month to make the date. Null with no date, or once the goal is reached or overdue.
name string · required
overdue boolean · required	The date has passed and the goal was not reached.
progress string · required	`saved` / `target_amount`, a decimal string from `0.0000` to `1.0000`. Pattern: `^\d\.\d{4}$`.
reached boolean · required
remaining Money · required
saved Money · required	`account_balance` − `baseline_amount`, between zero and the target.
target_amount Money · required
target_date date \| null · required

Example

curl -X PATCH "https://api.lumaledger.app/v1/savings-goals/{savings_goal_id}" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Objects

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}$`.

SavingsGoal

A savings goal and how far along it is today.

Fields

account_balance Money · required	The account's balance right now.
account_id integer · required	The asset account the money sits in (see `accounts.list`).
account_name string · required
baseline_amount Money · required	The account balance the goal counts from.
id integer · required
monthly_needed Money \| null · required	What has to go in each month to make the date. Null with no date, or once the goal is reached or overdue.
name string · required
overdue boolean · required	The date has passed and the goal was not reached.
progress string · required	`saved` / `target_amount`, a decimal string from `0.0000` to `1.0000`. Pattern: `^\d\.\d{4}$`.
reached boolean · required
remaining Money · required
saved Money · required	`account_balance` − `baseline_amount`, between zero and the target.
target_amount Money · required
target_date date \| null · required

SavingsGoalCreate

Fields

account_id integer · required	An active asset account in this ledger (see `accounts.list?type=asset`).
baseline_amount string \| null	The balance the goal counts from. Omitted: the account's balance today, so only what is saved from now on counts. `"0"` counts the whole balance. Pattern: `^\d{1,12}(\.\d{1,2})?$`.
name string · required
target_amount string · required	More than zero; decimal string, at most two decimal places. Pattern: `^\d{1,12}(\.\d{1,2})?$`.
target_date date \| null

SavingsGoalList

A page of savings goals, by id.

Fields

data array of SavingsGoal · required
has_more boolean · required
next_cursor string \| null · required

SavingsGoalUpdate

Only the fields sent change. target_date: null removes the date.

Fields

account_id integer \| null	Move the goal to another asset account.
baseline_amount string \| null	Pattern: `^\d{1,12}(\.\d{1,2})?$`.
name string \| null
target_amount string \| null	Pattern: `^\d{1,12}(\.\d{1,2})?$`.
target_date date \| null

account_id integer \| null	Move the goal to another asset account.
baseline_amount string \| null	Pattern: `^\d{1,12}(\.\d{1,2})?$`.
name string \| null
target_amount string \| null	Pattern: `^\d{1,12}(\.\d{1,2})?$`.
target_date date \| null

account_id integer \| null	Move the goal to another asset account.
baseline_amount string \| null	Pattern: `^\d{1,12}(\.\d{1,2})?$`.
name string \| null
target_amount string \| null	Pattern: `^\d{1,12}(\.\d{1,2})?$`.
target_date date \| null