API reference

Notifications

get/v1/notifications

List notifications

notifications.listread tokenidempotent

The caller's notifications in this ledger, newest first: bills due, renewals, large transactions, budgets crossing their line, receipts matched, a bank that needs signing in again.

Parameters

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

Returns 200 · NotificationList

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

Example

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

get/v1/notifications/preferences

Get notification preferences

notification_preferences.getread tokenidempotent

The categories of notification the caller has muted, and whether the weekly summary email and alert emails are on.

Parameters

X-Organization-Id

string | null · header

Returns 200 · NotificationPreferences

alert_emails boolean · required	A low balance, a balance projected to run short and a card payment due also arrive by email, once each. On unless switched off.
categories array of NotificationCategory · required	Every category, in the app's order. Security notices belong to none and cannot be muted.
weekly_digest boolean · required	The Monday summary email is on.

Example

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

patch/v1/notifications/preferences

Update notification preferences

notification_preferences.updatewrite tokenidempotent

Mute or unmute categories of notification, and switch the weekly summary email and alert emails on or off. Muting stops new notifications of that kind; nothing is replayed when it is turned back on.

Parameters

X-Organization-Id

string | null · header

Body · NotificationPreferencesUpdate

alert_emails boolean \| null	Switch alert emails (a low balance, a shortfall ahead, a payment due) on or off. Muting a category stops its emails too.
categories array of CategoryMute \| null	Categories to mute or unmute. Categories not listed keep their setting.
timezone string \| null	With `weekly_digest`: the IANA zone whose Monday morning it is sent on (`Europe/Madrid`). UTC when unknown.
weekly_digest boolean \| null	Switch the Monday summary email on or off. On needs the caller's login to have an email address.

Returns 200 · NotificationPreferences

alert_emails boolean · required	A low balance, a balance projected to run short and a card payment due also arrive by email, once each. On unless switched off.
categories array of NotificationCategory · required	Every category, in the app's order. Security notices belong to none and cannot be muted.
weekly_digest boolean · required	The Monday summary email is on.

Example

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

post/v1/notifications/read

Mark notifications read

notifications.mark_readwrite tokenidempotent

Mark some of the caller's notifications read, or all of them with all. Ids that are not the caller's, or already read, are skipped.

Parameters

X-Organization-Id

string | null · header

Body · MarkRead

all boolean	Mark every unread notification read instead. Default: `false`.
notification_ids array of integer \| null	The notifications to mark read, from `notifications.list`.

Returns 200 · MarkReadResult

marked

integer · required

How many were unread and are now read.

Example

curl -X POST "https://api.lumaledger.app/v1/notifications/read" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Objects

CategoryMute

Fields

key string · required	One of `bills`, `subscriptions`, `budgets`, `goals`, `large_transactions`, `accounts`, `investments`, `discoveries`, `receipts`, `automations`. Pattern: `^(bills\|subscriptions\|budgets\|goals\|large_transactions\|accounts\|investments\|discoveries\|receipts\|automations)$`.
muted boolean · required

MarkRead

Fields

all boolean	Mark every unread notification read instead. Default: `false`.
notification_ids array of integer \| null	The notifications to mark read, from `notifications.list`.

MarkReadResult

Fields

marked

integer · required

How many were unread and are now read.

Notification

Something the ledger wanted its member to know, once.

Fields

body string \| null · required
created_at datetime · required
data object · required	Facts behind it, per type (ids, names, dates); amounts are decimal strings. Keys are snake_case.
id integer · required
read boolean · required
severity string · required	`info` or `warning`.
title string · required	Written in the language the ledger member reads.
type string · required	What happened, e.g. `subscription_renewal`, `large_transaction`, `budget_threshold`. New types are added over time.

NotificationCategory

Fields

key string · required	A category of notifications that can be muted.
muted boolean · required

NotificationList

A page of notifications, newest first.

Fields

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

NotificationPreferences

Which kinds of notification the caller gets. Holds in every ledger.

Fields

alert_emails boolean · required	A low balance, a balance projected to run short and a card payment due also arrive by email, once each. On unless switched off.
categories array of NotificationCategory · required	Every category, in the app's order. Security notices belong to none and cannot be muted.
weekly_digest boolean · required	The Monday summary email is on.

NotificationPreferencesUpdate

Only the fields sent change.

Fields

alert_emails boolean \| null	Switch alert emails (a low balance, a shortfall ahead, a payment due) on or off. Muting a category stops its emails too.
categories array of CategoryMute \| null	Categories to mute or unmute. Categories not listed keep their setting.
timezone string \| null	With `weekly_digest`: the IANA zone whose Monday morning it is sent on (`Europe/Madrid`). UTC when unknown.
weekly_digest boolean \| null	Switch the Monday summary email on or off. On needs the caller's login to have an email address.