API reference

Events

get/v1/events

List financial events

events.listread tokenidempotent

The ledger's financial events, newest first, with how each was categorized. Unposted ones are waiting for a category or a match; categorization.run and journals.generate move them along.

Parameters

limit integer · query	Page size, 1–200.
cursor string \| null · query	The `next_cursor` of the previous page.
account_id integer \| null · query	Only events on this account.
event_type string \| null · query	Only events of this `event_type`.
is_posted boolean \| null · query	Only posted (true) or unposted (false) events.
X-Organization-Id string \| null · header

Returns 200 · EventList

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

Example

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

get/v1/events/{event_id}

Get a financial event

events.getread tokenidempotent

One financial event by its id.

Parameters

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

Returns 200 · Event

account_id integer · required	The bank, card or loan account it happened on.
amount Money · required	Always positive; `event_type` says which way it went. In the account's currency.
categorization_source string \| null · required	Who filed it: `manual`, `merchant_memory`, `pfc` (the bank's own category), `llm`, `transfer`, `user_rule:…`, `uncategorized`, …
category_id integer \| null · required	The income or expense account it is filed under.
confidence string \| null · required	How sure the categorizer was, a decimal string from `0.00` to `1.00`.
created_at datetime · required
date date · required
description string · required	The source's own text for it.
event_type string · required	What kind of movement: `expense`, `income`, `transfer`, `cc_payment`, `refund`, `fee` or `interest`.
id integer · required
is_posted boolean · required
is_superseded boolean · required	Replaced by a later version of itself (a pending charge that posted).
merchant_name string \| null · required	The merchant recognized in the description.
other_account_id integer \| null · required	For a transfer, the ledger's own account on the other end.
reviewed boolean · required	A person has confirmed or set the category.
transaction_id integer \| null · required	The transaction (journal entry) it is posted as, once posted. See `transactions.get`.

Example

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

post/v1/events/{event_id}/categorize

Categorize a financial event

events.categorizewrite tokenidempotent

File one event under a category by hand, as confirmed (reviewed). Its transaction is re-posted at once, so the ledger shows the new category. With learn_merchant, the merchant is remembered and its next events are filed the same way.

Parameters

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

Body · EventCategorize

category_id integer · required	The income or expense account to file it under (from `accounts.list`), on the event's side: an income account for money in, an expense account for money out.
learn_merchant boolean	Also file this merchant's future events here. Default: `true`.

Returns 200 · Event

account_id integer · required	The bank, card or loan account it happened on.
amount Money · required	Always positive; `event_type` says which way it went. In the account's currency.
categorization_source string \| null · required	Who filed it: `manual`, `merchant_memory`, `pfc` (the bank's own category), `llm`, `transfer`, `user_rule:…`, `uncategorized`, …
category_id integer \| null · required	The income or expense account it is filed under.
confidence string \| null · required	How sure the categorizer was, a decimal string from `0.00` to `1.00`.
created_at datetime · required
date date · required
description string · required	The source's own text for it.
event_type string · required	What kind of movement: `expense`, `income`, `transfer`, `cc_payment`, `refund`, `fee` or `interest`.
id integer · required
is_posted boolean · required
is_superseded boolean · required	Replaced by a later version of itself (a pending charge that posted).
merchant_name string \| null · required	The merchant recognized in the description.
other_account_id integer \| null · required	For a transfer, the ledger's own account on the other end.
reviewed boolean · required	A person has confirmed or set the category.
transaction_id integer \| null · required	The transaction (journal entry) it is posted as, once posted. See `transactions.get`.

Example

curl -X POST "https://api.lumaledger.app/v1/events/{event_id}/categorize" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "category_id": 1
  }'

delete/v1/events/{event_id}/splits

Remove an event's splits

splits.deletewrite tokendestructiveidempotent

Remove every split, filing the event under its own single category again. Its transaction is re-posted at once.

Parameters

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

Returns 204 with no body.

Example

curl -X DELETE "https://api.lumaledger.app/v1/events/{event_id}/splits" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN"

get/v1/events/{event_id}/splits

List an event's splits

splits.listread tokenidempotent

How one event is split across categories. Empty when it is filed under a single category (category_id on the event).

Parameters

event_id integer · path · required
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 · SplitList

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

Example

curl -X GET "https://api.lumaledger.app/v1/events/{event_id}/splits" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN"

put/v1/events/{event_id}/splits

Split an event across categories

splits.replacewrite tokenidempotent

Replace an event's splits with these. The amounts must add up to the event's amount, and every part is filed on the event's own side: an expense account for spending, fees and refunds, an income account for income and interest. Its transaction is re-posted at once with one line per split. Answers with every split (up to 200, so one page).

Parameters

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

Body · SplitsReplace

splits

array of SplitInput · required

Every split the event is to have. Their amounts must add up to the event's amount. To go back to one category, use splits.delete.

Returns 200 · SplitList

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

Example

curl -X PUT "https://api.lumaledger.app/v1/events/{event_id}/splits" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "splits": [
      {
        "amount": "42.50",
        "category_id": 1
      }
    ]
  }'

Objects

Event

One movement of money as its source reported it.

Fields

account_id integer · required	The bank, card or loan account it happened on.
amount Money · required	Always positive; `event_type` says which way it went. In the account's currency.
categorization_source string \| null · required	Who filed it: `manual`, `merchant_memory`, `pfc` (the bank's own category), `llm`, `transfer`, `user_rule:…`, `uncategorized`, …
category_id integer \| null · required	The income or expense account it is filed under.
confidence string \| null · required	How sure the categorizer was, a decimal string from `0.00` to `1.00`.
created_at datetime · required
date date · required
description string · required	The source's own text for it.
event_type string · required	What kind of movement: `expense`, `income`, `transfer`, `cc_payment`, `refund`, `fee` or `interest`.
id integer · required
is_posted boolean · required
is_superseded boolean · required	Replaced by a later version of itself (a pending charge that posted).
merchant_name string \| null · required	The merchant recognized in the description.
other_account_id integer \| null · required	For a transfer, the ledger's own account on the other end.
reviewed boolean · required	A person has confirmed or set the category.
transaction_id integer \| null · required	The transaction (journal entry) it is posted as, once posted. See `transactions.get`.

EventCategorize

Fields

category_id integer · required	The income or expense account to file it under (from `accounts.list`), on the event's side: an income account for money in, an expense account for money out.
learn_merchant boolean	Also file this merchant's future events here. Default: `true`.

EventList

A page of events, newest first.

Fields

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

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

Split

One part of an event filed under its own category: a line of an itemized receipt, the groceries in a supermarket run that also bought a lamp.

Fields

amount Money · required	Positive, in the event's account's currency.
category_id integer · required	The income or expense account this part is filed under.
external_ref string \| null · required	The line's id or SKU in its source.
id integer · required
memo string \| null · required
product_name string \| null · required
quantity string \| null · required	A decimal string, up to four places.
source string · required	Who split it: `manual`, or the integration that did.
unit_price Money \| null · required

SplitInput

Fields

amount string · required	Positive decimal string, at most two decimal places: `"42.50"`. Pattern: `^\d{1,12}(\.\d{1,2})?$`.
category_id integer · required	An income or expense account in this ledger.
external_ref string \| null	The line's id or SKU in your system.
memo string \| null
product_name string \| null
quantity string \| null	Decimal string. Pattern: `^\d{1,8}(\.\d{1,4})?$`.
unit_price string \| null	Decimal string. Pattern: `^\d{1,12}(\.\d{1,2})?$`.

SplitList

An event's splits, in the order they were written.

Fields

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

SplitsReplace

Fields

splits

array of SplitInput · required

Every split the event is to have. Their amounts must add up to the event's amount. To go back to one category, use splits.delete.