Finance
The finance endpoints of the Lifous API.
A * marks a required field. Path fields go in the address, query fields after a ?, body fields in JSON.
/api/v1/finance/overviewYour Money Overview
What the Money Overview page shows for a period: balances, income, spending, the savings rate, the budget in force, your goals, and recent and upcoming entries. Amounts are whole minor units (1250 is 12.50). `setUp: false` until Finance has been set up on the website.
| Field | In | Type | Meaning |
|---|---|---|---|
| range | query | week | month | lastMonth | 3months | year | custom | The period. month when omitted; custom needs from and to. |
| from | query | YYYY-MM-DD | First day, with custom. |
| to | query | YYYY-MM-DD | Last day, with custom. |
| timezone | query | IANA zone | Which calendar day "today" is. Your account’s zone when omitted. |
MCP tool: finance_overview
/api/v1/finance/accountsYour accounts
Every account with its type, currency and balance today, archived ones included. A balance is whole minor units of the account’s own currency.
MCP tool: list_finance_accounts
/api/v1/finance/categoriesYour categories
Income and expense categories, one level of subcategories (`parentId`), archived ones included.
MCP tool: list_finance_categories
/api/v1/finance/transactionsYour entries
Income, expenses, transfers and refunds, newest first, 25 a page. A transfer is one entry holding both accounts and is neither income nor spending.
| Field | In | Type | Meaning |
|---|---|---|---|
| type | query | income | expense | transfer | refund | One kind only. Every kind when omitted. |
| accountId | query | uuid | Entries of one account. |
| categoryId | query | uuid | Entries of one category. |
| from | query | YYYY-MM-DD | First day. |
| to | query | YYYY-MM-DD | Last day. |
| search | query | string | Words in the payee or note. |
| page | query | integer | From 1. 1 when omitted. |
MCP tool: list_finance_transactions
/api/v1/finance/transactionsAdd an entry
Records income, an expense, a refund or a transfer in one of your accounts. `amountMinor` is always positive and in whole minor units of the account’s currency: 1250 for 12.50. The type gives the direction. A transfer needs `toAccountId`.
| Field | In | Type | Meaning |
|---|---|---|---|
| type * | body | income | expense | transfer | refund | What kind of entry. |
| accountId * | body | uuid | The account. For a transfer, the one the money leaves. |
| amountMinor * | body | integer | Whole minor units, positive: 1250 is 12.50. |
| categoryId | body | uuid | A category of the same kind. Never on a transfer. |
| toAccountId | body | uuid | A transfer’s destination account. |
| toAmountMinor | body | integer | What arrived, when the destination holds another currency. |
| date | body | YYYY-MM-DD | Today when omitted. Never the future. |
| payee | body | string | Up to 80 characters. |
| description | body | string | Up to 140 characters. |
| notes | body | string | Up to 2,000 characters. |
| tags | body | string[] | Up to 10 short tags. |
| refundOfId | body | uuid | A refund’s original expense, when you know it. |
| timezone | body | IANA zone | Which day today is. Your account’s zone when omitted. |
{ "type": "expense", "accountId": "…", "amountMinor": 1250, "payee": "Bakery" }MCP tool: add_finance_transaction
/api/v1/finance/budgetsYour budgets
Every budget with its period and limits and, for a live one, where it stands now: spent, remaining, and an estimate for the period.
| Field | In | Type | Meaning |
|---|---|---|---|
| timezone | query | IANA zone | Which calendar day "today" is. Your account’s zone when omitted. |
MCP tool: list_finance_budgets
/api/v1/finance/goalsYour savings goals
Every savings goal with its target, what is set aside, the progress, and whether it is on track for its date.
| Field | In | Type | Meaning |
|---|---|---|---|
| timezone | query | IANA zone | Which calendar day "today" is. Your account’s zone when omitted. |
MCP tool: list_finance_goals