API reference

Project Budgets

get/v1/project-budgets

List project budgets

project_budgets.listread tokenidempotent

The ledger's project budgets, each with what has been spent on it so far.

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 · ProjectBudgetList

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

Example

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

post/v1/project-budgets

Create a project budget

project_budgets.createwrite tokenidempotent

Budget a project: an amount for everything tagged with its tag between two dates. Tag its transactions (by hand or with a rule) and they count towards it.

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 · ProjectBudgetCreate

amount string · required	Decimal string, at most two decimal places. Pattern: `^\d{1,12}(\.\d{1,2})?$`.
end_date date \| null	Omit for an open-ended project.
name string · required
start_date date · required
tag string \| null	The name of the tag that marks the project's transactions. Created if the ledger has no tag by that name (case-insensitively). Defaults to `name`. A tag budgets one project at most.

Returns 201 · ProjectBudget

amount Money · required	The budget for the whole project.
end_date date \| null · required	Null: open-ended.
id integer · required
is_current boolean · required	Today is inside the window.
name string · required
remaining Money · required	`amount` − `spent`. Negative is over budget.
spent Money · required	Tagged expenses inside the window, refunds netted off.
start_date date · required
tag_color string \| null · required
tag_id integer · required	The tag that marks this project's transactions.
tag_name string · required
transaction_count integer · required	How many tagged transactions count towards it.

Example

curl -X POST "https://api.lumaledger.app/v1/project-budgets" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "2500.00",
    "name": "…",
    "start_date": "2026-09-01"
  }'

delete/v1/project-budgets/{project_budget_id}

Delete a project budget

project_budgets.deletewrite tokendestructiveidempotent

Remove a project budget. Its tag, and the transactions carrying it, stay.

Parameters

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

Returns 204 with no body.

Example

curl -X DELETE "https://api.lumaledger.app/v1/project-budgets/{project_budget_id}" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN"

get/v1/project-budgets/{project_budget_id}

Get a project budget

project_budgets.getread tokenidempotent

One project budget by its id.

Parameters

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

Returns 200 · ProjectBudget

amount Money · required	The budget for the whole project.
end_date date \| null · required	Null: open-ended.
id integer · required
is_current boolean · required	Today is inside the window.
name string · required
remaining Money · required	`amount` − `spent`. Negative is over budget.
spent Money · required	Tagged expenses inside the window, refunds netted off.
start_date date · required
tag_color string \| null · required
tag_id integer · required	The tag that marks this project's transactions.
tag_name string · required
transaction_count integer · required	How many tagged transactions count towards it.

Example

curl -X GET "https://api.lumaledger.app/v1/project-budgets/{project_budget_id}" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN"

patch/v1/project-budgets/{project_budget_id}

Update a project budget

project_budgets.updatewrite tokenidempotent

Rename a project budget, change its amount or dates, or move it to another tag. Only the fields sent change.

Parameters

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

Body · ProjectBudgetUpdate

amount string \| null	Pattern: `^\d{1,12}(\.\d{1,2})?$`.
end_date date \| null
name string \| null
start_date date \| null
tag string \| null	See `ProjectBudgetCreate.tag`.

Returns 200 · ProjectBudget

amount Money · required	The budget for the whole project.
end_date date \| null · required	Null: open-ended.
id integer · required
is_current boolean · required	Today is inside the window.
name string · required
remaining Money · required	`amount` − `spent`. Negative is over budget.
spent Money · required	Tagged expenses inside the window, refunds netted off.
start_date date · required
tag_color string \| null · required
tag_id integer · required	The tag that marks this project's transactions.
tag_name string · required
transaction_count integer · required	How many tagged transactions count towards it.

Example

curl -X PATCH "https://api.lumaledger.app/v1/project-budgets/{project_budget_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}$`.

ProjectBudget

A budget for a project, measured from the transactions carrying its tag.

Fields

amount Money · required	The budget for the whole project.
end_date date \| null · required	Null: open-ended.
id integer · required
is_current boolean · required	Today is inside the window.
name string · required
remaining Money · required	`amount` − `spent`. Negative is over budget.
spent Money · required	Tagged expenses inside the window, refunds netted off.
start_date date · required
tag_color string \| null · required
tag_id integer · required	The tag that marks this project's transactions.
tag_name string · required
transaction_count integer · required	How many tagged transactions count towards it.

ProjectBudgetCreate

Fields

amount string · required	Decimal string, at most two decimal places. Pattern: `^\d{1,12}(\.\d{1,2})?$`.
end_date date \| null	Omit for an open-ended project.
name string · required
start_date date · required
tag string \| null	The name of the tag that marks the project's transactions. Created if the ledger has no tag by that name (case-insensitively). Defaults to `name`. A tag budgets one project at most.

ProjectBudgetList

A page of project budgets, by id.

Fields

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

ProjectBudgetUpdate

Only the fields sent change. end_date: null makes it open-ended.

Fields

amount string \| null	Pattern: `^\d{1,12}(\.\d{1,2})?$`.
end_date date \| null
name string \| null
start_date date \| null
tag string \| null	See `ProjectBudgetCreate.tag`.

amount string \| null	Pattern: `^\d{1,12}(\.\d{1,2})?$`.
end_date date \| null
name string \| null
start_date date \| null
tag string \| null	See `ProjectBudgetCreate.tag`.

amount string \| null	Pattern: `^\d{1,12}(\.\d{1,2})?$`.
end_date date \| null
name string \| null
start_date date \| null
tag string \| null	See `ProjectBudgetCreate.tag`.