Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/soker90/finper/llms.txt

Use this file to discover all available pages before exploring further.

Finper provides two complementary modules for tracking money that moves outside your regular transaction flow: Debts for informal IOUs with named third parties, and Goals for ring-fencing savings toward a specific target. Neither module requires a formal account or loan structure — they are intentionally lightweight.

​
Debts

A Debt represents an informal obligation between you and a named person or organisation. Because Finper is self-hosted and personal, the counterparty is stored as a free-text string in the from field — there is no contact directory.

​
Debt type

TypeMeaning
fromThe counterparty owes you money (you lent it)
toYou owe the counterparty money (you borrowed it)

​
Endpoints

MethodRouteDescription
POST/api/debtsCreate a new debt
GET/api/debtsList all debts, grouped by type and summarised by person
GET/api/debts/from/:fromList all debts for a specific counterparty name
PUT/api/debts/:idReplace a debt record
DELETE/api/debts/:idDelete a debt record
POST/api/debts/:id/payRegister a payment or receipt against a debt

​
Debt fields

FieldTypeRequiredDescription
fromstring✅Free-text name of the counterparty
amountnumber✅Outstanding amount
typefrom | to✅Direction of the debt
datenumber❌Unix timestamp (ms) of the debt date
paymentDatenumber❌Unix timestamp (ms) of the expected or actual payment date
conceptstring❌Optional description or notes

​
Recording a payment with POST /:id/pay

POST /api/debts/:id/pay subtracts the supplied amount from the debt’s outstanding balance. If the payment covers the full remaining amount (or more), the debt record is automatically deleted. The body requires a single field: 
{ "amount": 50 }
The endpoint does not automatically create a transaction in your accounts — if you want to record the cash movement, create a transaction separately.

​
Example: Create a debt

curl -X POST http://localhost:3008/api/debts \
  -H 'token: <your-jwt>' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": "Alice",
    "amount": 120,
    "type": "from",
    "date": 1718000000000,
    "paymentDate": 1720000000000,
    "concept": "Concert tickets advance"
  }'

​
Example: Record a payment on a debt

curl -X POST http://localhost:3008/api/debts/abc123/pay \
  -H 'token: <your-jwt>' \
  -H 'Content-Type: application/json' \
  -d '{ "amount": 60 }'
The remaining balance will be updated to 60. If you pass 120 or more, the debt is deleted entirely.

​
Goals

A Goal is a named savings target. You set a targetAmount and then gradually increase currentAmount through explicit fund and withdraw operations. Goals are visual-friendly — each one carries a color and an icon chosen from closed enums.

​
Endpoints

MethodRouteDescription
POST/api/goalsCreate a new goal
GET/api/goalsList all goals
GET/api/goals/:idGet a single goal by ID
PUT/api/goals/:idUpdate goal metadata (name, target, deadline, color, icon)
DELETE/api/goals/:idDelete a goal
POST/api/goals/:id/fundAdd money to the goal
POST/api/goals/:id/withdrawRemove money from the goal

​
Goal fields

FieldTypeRequiredDescription
namestring✅Human-readable label
targetAmountnumber✅Savings target (must be positive)
currentAmountnumber❌Current saved amount (defaults to 0)
deadlineISO date string❌Optional target date as an ISO 8601 string (e.g. "2026-12-31"), or null
colorstring (hex)✅One of the 10 allowed hex values
iconstring✅One of the 10 allowed Ant Design icon names
deadline accepts an ISO 8601 date string such as "2026-12-31" — not a Unix timestamp. Pass null to clear a deadline.

​
Color options

#4CAF50  #2196F3  #9C27B0  #FF9800  #F44336
#00BCD4  #795548  #607D8B  #E91E63  #FFC107

​
Icon options

DollarOutlined   HomeOutlined    CarOutlined     LaptopOutlined
HeartOutlined    RocketOutlined  GiftOutlined    BankOutlined
TrophyOutlined   StarOutlined

​
Funding and withdrawing

Both sub-actions take a single amount field (positive number).
  • POST /api/goals/:id/fund — increases currentAmount by amount. The total allocation across all goals is validated against your active account balances; an error is returned if the new total would exceed your available balance.
  • POST /api/goals/:id/withdraw — decreases currentAmount by amount. Returns an error if amount exceeds the current balance of the goal.
currentAmount is always rounded to 2 decimal places after each fund or withdraw operation.

​
Example: Create a goal

curl -X POST http://localhost:3008/api/goals \
  -H 'token: <your-jwt>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Emergency Fund",
    "targetAmount": 5000,
    "color": "#4CAF50",
    "icon": "BankOutlined",
    "deadline": "2026-12-31"
  }'

​
Example: Add funds to a goal

curl -X POST http://localhost:3008/api/goals/xyz789/fund \
  -H 'token: <your-jwt>' \
  -H 'Content-Type: application/json' \
  -d '{ "amount": 250 }'
The response returns the updated goal object with the new currentAmount.

Build docs developers (and LLMs) love

Get started for freeTalk to us