API reference

Rules

get/v1/rules

List rules

rules.listread tokenidempotent

The ledger's rules, in the order they run.

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

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

Example

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

post/v1/rules

Create a rule

rules.createwrite tokenidempotent

Save a rule. It applies to transactions that arrive from now on; call rules.run to apply it to the ones already in the ledger.

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

actions array of RuleActionInput
conditions array of RuleConditionInput
is_active boolean	Default: `true`.
match_type string	`all` or `any`. Pattern: `^(all\|any)$`. Default: `"all"`.
name string · required
priority integer	Lower runs first. -1000–1000. Default: `0`.
stop_processing boolean	Default: `false`.

Returns 201 · Rule

actions array of RuleAction · required
applied_count integer · required	Transactions the rule has changed, all time.
conditions array of RuleCondition · required
created_at datetime · required
id integer · required
is_active boolean · required	An inactive rule is kept but never applied.
last_applied_at datetime \| null · required
match_type string · required	`all` or `any`: how the rule reads its condition groups.
name string · required
priority integer · required	Lower runs first. Ties run in id order.
stop_processing boolean · required	When it matches, no lower-priority rule runs on that transaction.
updated_at datetime · required

Example

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

delete/v1/rules/{rule_id}

Delete a rule

rules.deletewrite tokendestructiveidempotent

Delete a rule. What it already did stays done: a category it set is the transaction's category now.

Parameters

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

Returns 204 with no body.

Example

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

get/v1/rules/{rule_id}

Get a rule

rules.getread tokenidempotent

One rule, with its conditions and actions.

Parameters

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

Returns 200 · Rule

actions array of RuleAction · required
applied_count integer · required	Transactions the rule has changed, all time.
conditions array of RuleCondition · required
created_at datetime · required
id integer · required
is_active boolean · required	An inactive rule is kept but never applied.
last_applied_at datetime \| null · required
match_type string · required	`all` or `any`: how the rule reads its condition groups.
name string · required
priority integer · required	Lower runs first. Ties run in id order.
stop_processing boolean · required	When it matches, no lower-priority rule runs on that transaction.
updated_at datetime · required

Example

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

put/v1/rules/{rule_id}

Replace a rule

rules.updatewrite tokenidempotent

Replace a rule wholesale: send the whole rule, as rules.create takes it. Its conditions and actions are rewritten (and get new ids). What the rule already did stays done.

Parameters

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

Body · RuleInput

actions array of RuleActionInput
conditions array of RuleConditionInput
is_active boolean	Default: `true`.
match_type string	`all` or `any`. Pattern: `^(all\|any)$`. Default: `"all"`.
name string · required
priority integer	Lower runs first. -1000–1000. Default: `0`.
stop_processing boolean	Default: `false`.

Returns 200 · Rule

actions array of RuleAction · required
applied_count integer · required	Transactions the rule has changed, all time.
conditions array of RuleCondition · required
created_at datetime · required
id integer · required
is_active boolean · required	An inactive rule is kept but never applied.
last_applied_at datetime \| null · required
match_type string · required	`all` or `any`: how the rule reads its condition groups.
name string · required
priority integer · required	Lower runs first. Ties run in id order.
stop_processing boolean · required	When it matches, no lower-priority rule runs on that transaction.
updated_at datetime · required

Example

curl -X PUT "https://api.lumaledger.app/v1/rules/{rule_id}" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "…"
  }'

post/v1/rules/{rule_id}/run

Apply a rule to past transactions

rules.runwrite tokenidempotent

Apply one rule to the transactions already in the ledger. Runs within the request and is bounded: when truncated is true there is older history left, and calling again continues. Applying a rule twice changes nothing the second time.

Parameters

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

Returns 200 · RuleRunResult

changed integer · required	Transactions the rule actually changed.
matched integer · required
scanned integer · required
truncated boolean · required	The run hit its bound; call again to reach older history.

Example

curl -X POST "https://api.lumaledger.app/v1/rules/{rule_id}/run" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN"

post/v1/rules/preview

Preview what a rule would match

rules.previewread tokenidempotent

Which recent transactions a rule's conditions would match, without saving the rule or changing anything. A read: any member may call it.

Parameters

X-Organization-Id

string | null · header

Body · RulePreviewInput

conditions array of RuleConditionInput · required
match_type string	`all` or `any`. Pattern: `^(all\|any)$`. Default: `"all"`.

Returns 200 · RulePreview

matched integer · required	How many of those the conditions match.
sample array of RulePreviewMatch · required	A few of the matches, newest first.
scanned integer · required	Recent transactions looked at (the newest 2,000).

Example

curl -X POST "https://api.lumaledger.app/v1/rules/preview" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "conditions": [
      {
        "field": "…",
        "operator": "…"
      }
    ]
  }'

post/v1/rules/run-all

Apply every rule to transactions no rule has seen

rules.run_allwrite tokenidempotent

Run every active rule over the transactions the rules have not seen yet (new ones are normally handled as they sync). Runs synchronously within the request, one bounded batch per call: call again while pending is above zero.

Parameters

X-Organization-Id

string | null · header

Returns 200 · RuleRunPendingResult

changed integer · required
matched integer · required
pending integer · required	Transactions still waiting. Call again while this is above zero.
scanned integer · required

Example

curl -X POST "https://api.lumaledger.app/v1/rules/run-all" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN"

get/v1/rules/schema

Get the rule vocabulary

rules.get_schemaread tokenidempotent

Every condition field (with the operators it admits and the kind of value it takes), every action, and the limits a rule must stay within. Read it before writing a rule: a key that is not here is refused.

Parameters

X-Organization-Id

string | null · header

Returns 200 · RuleSchema

actions array of RuleActionSpec · required
fields array of RuleFieldSpec · required
limits RuleLimits · required
operators RuleOperatorArity · required
tag_colors array of string · required	The colors `tags.create` accepts.

Example

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

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

Rule

A standing instruction: when a transaction matches the conditions, the actions are applied to it.

Fields

actions array of RuleAction · required
applied_count integer · required	Transactions the rule has changed, all time.
conditions array of RuleCondition · required
created_at datetime · required
id integer · required
is_active boolean · required	An inactive rule is kept but never applied.
last_applied_at datetime \| null · required
match_type string · required	`all` or `any`: how the rule reads its condition groups.
name string · required
priority integer · required	Lower runs first. Ties run in id order.
stop_processing boolean · required	When it matches, no lower-priority rule runs on that transaction.
updated_at datetime · required

RuleAction

Fields

action string · required	An action key from `rules.get_schema` (`set_category`, `add_tags`, …).
id integer · required
params object · required	Named inputs, for an action that declares `params` in the schema.
value string \| null · required	The action's one value, when it takes one (a category id, an address).
values array of string · required	The action's values, when it takes several (tag ids, split lines).

RuleActionInput

Fields

action string · required	An action key from `rules.get_schema`.
params object	Named inputs the action declares in `rules.get_schema`.
value string \| null	For an action that takes one value.
values array of string	For an action that takes several.

RuleActionParamSpec

Fields

key string · required
required boolean · required
value_type string · required

RuleActionSpec

Fields

app string \| null · required	The connected app the action writes to, if any.
conflicts_with array of string · required	Actions that cannot share a rule with this one.
key string · required
multi boolean · required	Takes `values` rather than `value`.
params array of RuleActionParamSpec · required
value_type string · required

RuleCondition

Fields

field string · required	A field key from `rules.get_schema` (`description`, `amount`, …).
group_index integer · required	Conditions in the same group must all hold (AND); any group may match (OR).
id integer · required
operator string · required	One of the operators that field admits.
value string \| null · required	The value, for a one-value operator. Canonical text: decimals as `12.50`, dates ISO, ids as digits.
value_to string \| null · required	The upper bound, for a range operator.
values array of string · required	The values, for a list operator.

RuleConditionInput

Fields

field string · required	A field key from `rules.get_schema`.
group_index integer	AND within a group, OR across groups. 0–5. Default: `0`.
operator string · required	One of the operators that field admits.
value string \| null	For a one-value operator.
value_to string \| null	The upper bound, for a range operator.
values array of string	For a list operator.

RuleFieldSpec

Fields

choices array of string · required	The only values allowed, when the field is an enumeration.
key string · required
multi boolean · required	Takes a list operator's `values`.
operators array of string · required
value_type string · required	What a value is: `text`, `number`, `date`, `category`, `tag`, …

RuleInput

A whole rule. At least one condition and one action; ids a rule names (categories, accounts, tags) must be this ledger's.

Fields

actions array of RuleActionInput
conditions array of RuleConditionInput
is_active boolean	Default: `true`.
match_type string	`all` or `any`. Pattern: `^(all\|any)$`. Default: `"all"`.
name string · required
priority integer	Lower runs first. -1000–1000. Default: `0`.
stop_processing boolean	Default: `false`.

RuleLimits

Fields

actions integer · required
conditions integer · required
groups integer · required
rules integer · required
tags integer · required

RuleList

A page of rules, in the order they run (priority, then id).

Fields

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

RuleOperatorArity

What a condition carries, by operator. An operator in none of these takes a single value.

Fields

list_operators array of string · required	Operators that take `values`.
nullary_operators array of string · required	Operators that take no value (`is_empty`).
range_operators array of string · required	Operators that take `value` and `value_to`.

RulePreview

Fields

matched integer · required	How many of those the conditions match.
sample array of RulePreviewMatch · required	A few of the matches, newest first.
scanned integer · required	Recent transactions looked at (the newest 2,000).

RulePreviewInput

The conditions of a rule that need not exist yet. Actions are ignored: a preview only asks what would match.

Fields

conditions array of RuleConditionInput · required
match_type string	`all` or `any`. Pattern: `^(all\|any)$`. Default: `"all"`.

RulePreviewMatch

Fields

account_id integer · required	The real account it is on.
amount Money · required	Always positive; `event_type` says which way it moved.
category_id integer \| null · required	The category it is filed under now.
date date · required
description string · required
event_type string · required	`expense`, `income`, `transfer`, `refund`, `fee`, …
transaction_id integer \| null · required	The transaction (journal entry) id, for `transactions.get`. Null while the bank transaction has not been posted to the ledger yet.

RuleRunPendingResult

Fields

changed integer · required
matched integer · required
pending integer · required	Transactions still waiting. Call again while this is above zero.
scanned integer · required

RuleRunResult

Fields

changed integer · required	Transactions the rule actually changed.
matched integer · required
scanned integer · required
truncated boolean · required	The run hit its bound; call again to reach older history.

RuleSchema

What a rule may say: every field, operator and action there is.

Fields

actions array of RuleActionSpec · required
fields array of RuleFieldSpec · required
limits RuleLimits · required
operators RuleOperatorArity · required
tag_colors array of string · required	The colors `tags.create` accepts.