API reference

Categorization

post/v1/categorization/run

Categorize waiting events

categorization.runwrite tokenidempotent

Categorize the events still waiting for a category: merchant memory and the bank's own categories first, then a model for the rest, then your rules, which outrank every guess. Answers 202 with a Job (kind categorize). Its result counts each stage: rule, merchant_memory, pfc, transfer and uncategorized at the top level, then llm (llm, new_categories, skipped), rules (matched, changed), and with drain also journals_generated. Only uncategorized events are touched.

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

drain

boolean

Work through the whole backlog of events waiting for the model, then post what was categorized. Without it, one batch is categorized and nothing is posted. Default: false.

Returns 202 · Job

created_at datetime · required
error JobError \| null · required	Why it failed, once `failed`.
finished_at datetime \| null · required
id integer · required
kind string · required	What the job does: `import`, `categorize`, `generate_journals`, `reconcile`, `run_schedules`, `plaid_sync` or `rocket_money_import`.
result object \| null · required	What the work produced, once `succeeded`. Its fields depend on `kind` and are listed on the operation that started it. Counts are integers.
status string · required	`queued`, `running`, `succeeded` or `failed`.

Example

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

post/v1/journals/generate

Post categorized events

journals.generatewrite tokenidempotent

Post every categorized event that is not posted yet as a balanced journal entry, by the posting rules (posting_rules.list). Answers 202 with a Job (kind generate_journals); its result: journals_generated. Posted events are never posted twice.

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

Returns 202 · Job

created_at datetime · required
error JobError \| null · required	Why it failed, once `failed`.
finished_at datetime \| null · required
id integer · required
kind string · required	What the job does: `import`, `categorize`, `generate_journals`, `reconcile`, `run_schedules`, `plaid_sync` or `rocket_money_import`.
result object \| null · required	What the work produced, once `succeeded`. Its fields depend on `kind` and are listed on the operation that started it. Counts are integers.
status string · required	`queued`, `running`, `succeeded` or `failed`.

Example

curl -X POST "https://api.lumaledger.app/v1/journals/generate" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"

get/v1/merchant-mappings

List merchant mappings

merchant_mappings.listread tokenidempotent

The ledger's merchant memory: each merchant it recognizes, the name it shows and the category it files the merchant under.

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

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

Example

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

post/v1/merchant-mappings

Remember a merchant

merchant_mappings.createwrite tokenidempotent

Teach the ledger a merchant: events whose description starts with merchant_pattern are named merchant_name and filed under category_id from now on. A pattern already remembered is updated in place, so sending the same one twice leaves one mapping. Events already categorized are left as they are.

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

category_id integer \| null	The income or expense account to file its events under.
confidence string	How sure a match is, `0` to `1`, as a decimal string. Pattern: `^(0(\.\d{1,2})?\|1(\.0{1,2})?)$`. Default: `"0.90"`.
merchant_name string · required	The clean name to show.
merchant_pattern string · required	The text a description starts with, e.g. `STARBUCKS`. Matched ignoring case.

Returns 201 · MerchantMappingOut

category_id integer \| null · required	The income or expense account its events are filed under.
confidence string · required	How sure a match is, a decimal string from `0.00` to `1.00`.
created_at datetime · required
id integer · required
merchant_name string · required	The clean name shown for it.
merchant_pattern string · required	The text a description starts with, upper case.
source string · required	`manual`, `learned` (from a person's correction), or `api`.

Example

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

get/v1/posting-rules

List posting rules

posting_rules.listread tokenidempotent

The rules that turn categorized events into balanced journal entries. They are the platform's, the same for every ledger, and cannot be changed through the API.

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

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

Example

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

Objects

CategorizationRun

Fields

drain

boolean

Work through the whole backlog of events waiting for the model, then post what was categorized. Without it, one batch is categorized and nothing is posted. Default: false.

Job

Work that outlives the request that started it. Poll jobs.get until status is succeeded or failed.

Fields

created_at datetime · required
error JobError \| null · required	Why it failed, once `failed`.
finished_at datetime \| null · required
id integer · required
kind string · required	What the job does: `import`, `categorize`, `generate_journals`, `reconcile`, `run_schedules`, `plaid_sync` or `rocket_money_import`.
result object \| null · required	What the work produced, once `succeeded`. Its fields depend on `kind` and are listed on the operation that started it. Counts are integers.
status string · required	`queued`, `running`, `succeeded` or `failed`.

JobError

Fields

code string · required	Stable error code, as in the error envelope.
message string · required	For people, in the request's language. Never match on it.

MerchantMappingInput

Fields

category_id integer \| null	The income or expense account to file its events under.
confidence string	How sure a match is, `0` to `1`, as a decimal string. Pattern: `^(0(\.\d{1,2})?\|1(\.0{1,2})?)$`. Default: `"0.90"`.
merchant_name string · required	The clean name to show.
merchant_pattern string · required	The text a description starts with, e.g. `STARBUCKS`. Matched ignoring case.

MerchantMappingList

A page of merchant mappings, in the order they were made.

Fields

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

MerchantMappingOut

What the ledger remembers about a merchant: how to name it and where to file it.

Fields

category_id integer \| null · required	The income or expense account its events are filed under.
confidence string · required	How sure a match is, a decimal string from `0.00` to `1.00`.
created_at datetime · required
id integer · required
merchant_name string · required	The clean name shown for it.
merchant_pattern string · required	The text a description starts with, upper case.
source string · required	`manual`, `learned` (from a person's correction), or `api`.

PostingRuleList

The posting rules.

Fields

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

PostingRuleOut

How an event of one type becomes a journal entry: which role is debited and which credited. The same for every ledger.

Fields

credit_account_role string · required
debit_account_role string · required	`source`, `category` or `other`: the event's own account, its category, or the account on the other end.
event_type string · required
id integer · required
is_active boolean · required
priority integer · required	Higher wins when two rules fit.
source_account_role string \| null · required	Only for events on accounts with this role (`checking`, `credit_card`, …); null for any.