API reference

Ledger API

Status live
Base URL https://api.sasek.org/ledger
Endpoints 71

Personal finance: accounts, transactions, categories, rules, imports, reports and notifications.

Personal finance ledger. Money is always integer cents (amount_cents, negative means money out). Dates are YYYY-MM-DD, months YYYY-MM, timestamps ISO 8601 UTC. Lists are JSON arrays. Auth: every route requires the X-Ledger-Token header. A missing, wrong or revoked token, or a method its scope does not allow, gets 404 not_found, the same as an unknown route. Paging: /v1/transactions, /v1/accounts/{id}/balances, /v1/holdings/history and /v1/notifications return X-Next-Cursor when more rows follow. Send it back as cursor=. Other lists return one page. Transactions also accept offset (0 to 1,000,000), but not together with cursor. Rate limits: 120 requests a minute per client address, counting every request. After 30 failed authentications in 15 minutes, the address gets 429 until the window ends. A 429 carries Retry-After in seconds. Idempotency: POST /v1/transactions and POST /v1/imports accept an Idempotency-Key header (1 to 200 characters). A retry with the same key gets the stored 2xx response, with Idempotent-Replayed: true. Versions: the path version is /v1. info.version is the revision of this document. Adding a field, endpoint or optional parameter does not change the path version.

Auth. Send the token in the X-Ledger-Token header. Some routes need none; each operation says so.

Health

Method	Endpoint	What it does
GET	`/v1/health`	Liveness check

Accounts

Method	Endpoint	What it does
GET	`/v1/accounts`	Every linked account with its most recent balance
GET	`/v1/accounts/{id}/portfolio`	An account's holdings and cash, as of its latest balance date
GET	`/v1/accounts/{id}/balances`	Balance snapshots for one account, newest first
DELETE	`/v1/accounts/{id}`	Delete an account. Refused while it holds transactions, balances, holdings or imports.
PATCH	`/v1/accounts/{id}`	Set an account's type, institution or nickname. The bank's own name is never changed.

Account types

Method	Endpoint	What it does
PATCH	`/v1/account-types/{name}`	Rename an account type everywhere it is used
DELETE	`/v1/account-types/{name}`	Delete an account type. If accounts use it, replace_with must name the type they move to.
GET	`/v1/account-types`	The account type list, with how many accounts use each type
POST	`/v1/account-types`	Add an account type. Adding an existing one is safe.

Transfers

Method	Endpoint	What it does
GET	`/v1/transfers`	Transactions matched as transfers between two of your accounts
POST	`/v1/transfers`	Link two transactions as a transfer by hand
DELETE	`/v1/transfers/{id}`	Remove a transfer link. The transactions go back to being ordinary spending or income.
GET	`/v1/transfers/review`	Possible transfers that could not be matched automatically

Rules

Method	Endpoint	What it does
GET	`/v1/rules`	Categorization rules in the order they are tried
POST	`/v1/rules`	Add a rule. A pattern that already has a rule is reported, not changed.
POST	`/v1/rules/preview`	What a rule would match, without creating it
PATCH	`/v1/rules/{id}`	Change a rule's pattern, category or priority. Transactions are re-categorized immediately.
DELETE	`/v1/rules/{id}`	Remove a rule. Transactions it had categorized become uncategorized, then the remaining rules decide again.
POST	`/v1/rules/apply`	Re-run every rule. Manual categories are never changed.
GET	`/v1/rules/match`	Which rule would apply to a description, to test a rule before relying on it

Tokens

Method	Endpoint	What it does
GET	`/v1/tokens`	Named API tokens, admin token only. The tokens themselves are never shown here.
POST	`/v1/tokens`	Create a named token, admin token only. The plain token is returned once; only its hash is kept.
DELETE	`/v1/tokens/{id}`	Revoke a named token, admin token only. It stops working at once and cannot be restored; create a new one instead.

Sources

Method	Endpoint	What it does
GET	`/v1/sources/{id}/settings`	A source's settings, admin token only. A source with no settings yet is off.
PUT	`/v1/sources/{id}/settings`	Turn a source on or off, and set what it needs. Admin token only. Omitted fields keep their current values; config replaces the whole config. A source cannot be enabled until its config has profile_url. Only https URLs are accepted.

Openapi.yaml

Method	Endpoint	What it does
GET	`/v1/openapi.yaml`	This contract, as YAML

Dashboard

Method	Endpoint	What it does
GET	`/v1/dashboard/session`	Whether the caller has a dashboard session. Public; carries no data.
GET	`/v1/dashboard/github/start`	Starts the owner's GitHub sign-in. Redirects to GitHub with a state and a PKCE challenge, and sets a five-minute cookie that holds the state and verifier.
GET	`/v1/dashboard/github/callback`	GitHub's redirect back. Accepts only the owner's GitHub user id. On success it sets the session cookie and redirects to the dashboard. Any failure redirects to the dashboard with signin=failed and counts against the address.
POST	`/v1/dashboard/logout`	Ends the dashboard session and clears its cookie. Public; a request without a session is still a success.

Status

Method	Endpoint	What it does
GET	`/v1/status`	Is the data current? Counts, the uncategorized total, and the latest run of each source.

Net worth

Method	Endpoint	What it does
GET	`/v1/net-worth`	Net worth now, from each account's latest balance
GET	`/v1/net-worth/series`	Net worth at the end of each month

Summary

Method	Endpoint	What it does
GET	`/v1/summary/categories`	Spending and income by category over a date range. Transfers are excluded.
GET	`/v1/summary/cashflow`	Income, spending, net and savings rate per month. Transfers are excluded.
GET	`/v1/summary/monthly`	Spending and income per account per month

Imports

Method	Endpoint	What it does
POST	`/v1/imports`	Import a Ledger CSV v1 file for one account. Format in docs/import-format.md.
GET	`/v1/imports`	Past imports, newest first
GET	`/v1/imports/template.csv`	A blank Ledger CSV v1 template with two example rows
DELETE	`/v1/imports/{id}`	Undo an import: remove every transaction it added. Bank and other imported rows are untouched.

Notification rules

Method	Endpoint	What it does
GET	`/v1/notification-rules`	Notification rules
POST	`/v1/notification-rules`	Add a rule. Rules only see transactions and data that arrive after they are created.
PATCH	`/v1/notification-rules/{id}`	Change a rule's name, threshold, category or enabled flag. The event cannot change.
DELETE	`/v1/notification-rules/{id}`	Delete a rule and its inbox items

Notifications

Method	Endpoint	What it does
GET	`/v1/notifications`	The inbox, newest first
POST	`/v1/notifications/read-all`	Mark every unread item as read
POST	`/v1/notifications/{id}/read`	Mark one item as read. Marking it again changes nothing.

Merchants

Method	Endpoint	What it does
GET	`/v1/merchants`	Merchants as they are shown, with alias names applied, most spending first. Transfers are excluded.

Merchant aliases

Method	Endpoint	What it does
GET	`/v1/merchant-aliases`	The alias list. The longest matching pattern wins.
POST	`/v1/merchant-aliases`	Name a merchant. Bank text containing the pattern is shown under the name. Bank text is never changed.
PATCH	`/v1/merchant-aliases/{id}`	Change an alias's pattern or name
DELETE	`/v1/merchant-aliases/{id}`	Remove an alias. Transactions show their normalized bank text again.

Method	Endpoint	What it does
PATCH	`/v1/categories/{name}`	Rename a category everywhere it is used (transactions and rules). Built-in categories cannot be renamed.
DELETE	`/v1/categories/{name}`	Delete a category. If it is in use, replace_with must name a category to move its transactions and rules to.
GET	`/v1/categories`	The category list, with how many transactions use each one
POST	`/v1/categories`	Add a category to the list. Adding an existing one is safe.

Transactions

Method	Endpoint	What it does
POST	`/v1/transactions/bulk-categorize`	Set the category of up to 500 transactions in one request
POST	`/v1/transactions/{id}/split`	Split a transaction into parts that add up to its amount
DELETE	`/v1/transactions/{id}/split`	Undo a split. Deletes its parts and counts the parent again.
GET	`/v1/transactions/export.csv`	The transactions matching the same filters as the list, as CSV
DELETE	`/v1/transactions/{id}`	Delete a manual or Apple Pay transaction. Bank transactions cannot be deleted.
PATCH	`/v1/transactions/{id}`	Edit a transaction. Manual and Apple Pay entries can change every field; bank transactions can change only category and note. Sending any other field to a bank transaction returns 400.
GET	`/v1/transactions`	Transactions, newest first
POST	`/v1/transactions`	Record a manual or Apple Pay transaction. Retrying with the same external_id, or the same Idempotency-Key, is safe.

Holdings

Method	Endpoint	What it does
GET	`/v1/holdings/history`	How each holding's value changed over time, newest first
GET	`/v1/holdings`	Investment positions with their latest market value

Budgets

Method	Endpoint	What it does
GET	`/v1/budgets`	The budgets in effect for a month, with what was spent in each category. Spending is outgoing amounts, with transfers and split parents left out.
GET	`/v1/budgets/suggestions`	A suggested budget per category, the average monthly spend over the last 3 or 4 complete months, rounded up to the next dollar. Read only; nothing is saved.
PUT	`/v1/budgets/{category}`	Set a category's budget from a month on. Setting the same month again replaces that month's amount. Months before this one cannot be changed.
DELETE	`/v1/budgets/{category}`	End a category's budget from a month on. The month and the months before it keep their amounts; the budget is not listed from that month.

Schemas

Account

Field	Type	Required	Description
`id`	string	required	SimpleFIN account id
`conn_id`	string or null	optional
`org_name`	string or null	optional	The institution name as the bank reports it
`institution`	string or null	optional	Your name for the bank. Falls back to org_name.
`name`	string	required	The account name as the bank reports it
`nickname`	string or null	optional	Your name for the account
`display_name`	string	optional	nickname if set
`created_at`	string or null (date-time)	optional	When this account was first seen
`updated_at`	string or null (date-time)	optional	When its latest balance was recorded
`currency`	string or null	optional
`account_type`	string or null	optional	From the account type list. null until set.
`balance_cents`	integer or null	optional
`available_cents`	integer or null	optional
`balance_date`	string or null (date-time)	optional

Balance

Field	Type	Required	Description
`balance_date`	string (date-time)	required	When the bank reported it
`balance_cents`	integer	required
`available_cents`	integer or null	optional
`captured_at`	string (date-time)	optional

Transaction

Field	Type	Required	Description
`id`	integer	required
`source`	string: one of `manual`, `apple_pay`, `simplefin`	required
`external_id`	string	required
`account_id`	string or null	optional
`posted`	string (date)	required	Bank posting date
`transacted_at`	string or null (date-time)	optional	When the purchase happened
`amount_cents`	integer	required
`merchant`	string	required	The bank's description
`payee`	string or null	optional
`memo`	string or null	optional
`category`	string	optional	Never null. Uncategorized until a rule or you set it.
`category_source`	string: one of `manual`, `rule`, `transfer`, `default`	optional	manual: you set it; rule: a rule set it; transfer: it is a matched transfer; default: nothing has set it yet
`rule_id`	integer or null	optional	The rule that set the category
`note`	string or null	optional

Portfolio

Field	Type	Required	Description
`account_id`	string	required
`name`	string	optional
`org_name`	string or null	optional
`currency`	string or null	optional
`as_of`	string or null (date-time)	optional	The account's latest balance date
`balance_cents`	integer or null	optional
`holdings_value_cents`	integer or null	optional	Sum of holdings at as_of; null if any holding has no value
`cash_balance_cents`	integer or null	optional	balance_cents minus holdings_value_cents; derived
`cash_is_derived`	boolean: one of `True`	required
`holdings`	object[]	required

AccountType

Field	Type	Required	Description
`name`	string	required
`accounts`	integer	required	Number of accounts using this type

Transfer

Field	Type	Required	Description
`id`	integer	required
`amount_cents`	integer	required	Positive amount moved
`method`	string: one of `auto`, `manual`	required
`created_at`	string (date-time)	optional
`out_tx_id`	integer	required	The money-out side
`from_account_id`	string	required
`out_posted`	string (date)	optional
`in_tx_id`	integer	required	The money-in side
`to_account_id`	string	required
`in_posted`	string (date)	optional

ApiToken

Field	Type	Required
`id`	integer	required
`name`	string	required
`scope`	string: one of `read`, `write`	required
`created_at`	string (date-time)	required
`last_used_at`	string or null (date-time)	optional
`revoked_at`	string or null (date-time)	optional

SourceSettings

Field	Type	Required
`source`	string: one of `collectr`	required
`enabled`	boolean	required
`config`	object	required
`updated_at`	string or null (date-time)	required

Rule

Field	Type	Required	Description
`id`	integer	required
`pattern`	string	required
`category`	string	required
`priority`	integer	required
`created_at`	string (date-time)	optional
`transactions`	integer	optional	Transactions currently set by this rule

RuleCreated

Field	Type	Required
`id`	integer	required
`pattern`	string	required
`category`	string	required
`created`	boolean	required

CategoryCreated

Field	Type	Required	Description
`name`	string	required
`created`	boolean	required	false when the category already existed

Import

Field	Type	Required
`id`	integer	required
`account_id`	string	required
`filename`	string or null	optional
`created_at`	string (date-time)	required
`rows_total`	integer	required
`rows_new`	integer	required
`rows_duplicate`	integer	required

ImportResult

Field	Type	Required	Description
`dry_run`	boolean	required
`import_id`	integer	optional	Present when the import was written
`rows_total`	integer	required
`rows_new`	integer	required
`rows_duplicate`	integer	required
`uncategorized`	integer	optional	New rows still Uncategorized after the rules ran
`categorized_by_you`	integer	optional	Dry run only: rows with a category in the file
`categorized_by_rule`	integer	optional	Dry run only: rows the rules would categorize

NotificationRule

Field	Type	Required
`id`	integer	required
`name`	string	required
`event`	string: one of `income`, `large_spend`, `spend_digest`, `transaction`, `balance_below`, `sync_failed`, `uncategorized_over`	required
`threshold`	integer or null	optional
`category`	string or null	optional
`topic`	string or null	optional
`enabled`	boolean	required
`created_at`	string (date-time)	optional

Notification

Field	Type	Required
`id`	integer	required
`rule_id`	integer	required
`title`	string	required
`detail`	string or null	optional
`transaction_id`	integer or null	optional
`created_at`	string (date-time)	required
`read_at`	string or null (date-time)	optional

MerchantAlias

Field	Type	Required	Description
`id`	integer	required
`pattern`	string	required
`name`	string	required
`created_at`	string (date-time)	optional
`created`	boolean	optional	Present on POST only

Holding

Field	Type	Required	Description
`id`	string	required
`account_id`	string	required
`symbol`	string or null	optional
`description`	string or null	optional
`currency`	string or null	optional
`shares`	number or null	optional
`purchase_price`	string or null	optional	Per-share price as the bank sent it
`cost_basis_cents`	integer or null	optional
`created_at`	string or null (date-time)	optional
`as_of`	string or null (date-time)	optional	Date of the latest snapshot
`market_value_cents`	integer or null	optional

MonthlySummary

Field	Type	Required
`account_id`	string or null	required
`month`	string	required
`spent_cents`	integer	required
`received_cents`	integer	required
`count`	integer	required

NewTransaction

Field	Type	Required	Description
`source`	string: one of `manual`, `apple_pay`	required
`external_id`	string	optional	Client-generated unique id, e.g. a UUID per entry
`posted`	string (date)	required
`amount_cents`	integer	required	Non-zero, magnitude up to 10000000
`merchant`	string	required
`category`	string	optional	Must be on the category list
`account_id`	string	optional	Must match an existing account
`note`	string	optional

Created

Field	Type	Required	Description
`created`	boolean	required	false when the transaction already existed

Error

Field	Type	Required	Description
`error`	string	required	Human-readable message
`code`	string	required	Stable machine-readable code, such as invalid_request, not_found, conflict, rate_limited, invalid_split, unsupported_media_type, payload_too_large, internal_error