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.

Categories and Budgets work hand-in-hand to give you control over where your money goes. Categories form a two-level hierarchy that classifies every transaction — groceries, utilities, salary, and so on. Budgets let you set a spending (or income) target for a category in a given month, and Finper tracks how your actual transactions measure up against those targets in real time.

​
Categories

A Category classifies transactions and belongs to a single user. The hierarchy is one level deep: a category can have a parent, and all categories sharing the same parent are considered siblings (children). There is no further nesting beyond parent → child.

​
Category Type

Every category carries a type that mirrors the transaction type enum:
ValueUse
expenseUsed to tag spending transactions
incomeUsed to tag income transactions
not_computableUsed for transfers or corrections that shouldn’t count toward totals

​
Endpoints

MethodPathDescription
POST/api/categoriesCreate a category (optionally set a parent ID)
GET/api/categoriesFlat list of all categories for the current user
GET/api/categories/groupedCategories nested under their parent
PATCH/api/categories/:idPartially update a category
DELETE/api/categories/:idDelete a category
GET /api/categories/grouped is particularly useful for building tree-view UIs. It returns each parent category with a children array containing its sub-categories, saving you the work of grouping them client-side.

​
Category Fields

FieldTypeRequiredDescription
namestring✅Display name for the category
typestring✅expense, income, or not_computable
parentObjectId❌ID of the parent category (omit for a top-level category)
budgetRuleClassstring❌Budget rule classification: needs, wants, savings, or none (default none)
budgetRuleClass lets you tag each category according to the 50/30/20 or similar budget rules. Use needs for essential expenses (rent, groceries), wants for discretionary spending (dining out, streaming), savings for saving/investment categories, and none (the default) for categories that don’t fit any rule class.

​
Example: Creating a Category

curl -s -X POST http://localhost:3008/api/categories \
  -H 'token: <your-jwt>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Groceries",
    "type": "expense",
    "parent": "64a1f2e3b4c5d6e7f8a9b0c3",
    "budgetRuleClass": "needs"
  }'
To create a top-level (parent) category, simply omit the parent field: 
curl -s -X POST http://localhost:3008/api/categories \
  -H 'token: <your-jwt>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Food & Home",
    "type": "expense"
  }'

​
Budgets

A Budget is a monthly spending (or income) target for a specific category. Each budget is uniquely identified by the combination of category + year + month + user — there can only be one budget per category per calendar month per user.

​
Month indexing

Budget months are 0-indexed: January = 0, February = 1, …, December = 11. This matches JavaScript’s Date.getMonth() convention.

​
Endpoints

MethodPathDescription
GET/api/budgetsList budgets filtered by year (required) and optionally month
PATCH/api/budgets/:category/:year/:monthUpsert the budgeted amount for a category/period
POST/api/budgetsCopy all budgets from one month to another

​
Query Parameters for GET /api/budgets

ParameterRequiredDescription
year✅Four-digit year to filter by
month❌0-indexed month (0–11). Omit to retrieve all months for the year

​
Upsert Pattern

PATCH /api/budgets/:category/:year/:month performs an upsert: if a budget document already exists for that category/year/month combination it is updated; if it does not exist yet it is created. This means you can call the same endpoint to both create and modify a budget — you never need to check first. 
# Sets (or updates) the October 2024 budget for category 64a1f2e3b4c5d6e7f8a9b0c3 to €350
# October is month index 9 (0-indexed)
curl -s -X PATCH \
  "http://localhost:3008/api/budgets/64a1f2e3b4c5d6e7f8a9b0c3/2024/9" \
  -H 'token: <your-jwt>' \
  -H 'Content-Type: application/json' \
  -d '{ "amount": 350 }'

​
Copying Budgets Between Periods

POST /api/budgets clones all budget records from a source month into a target month. This is useful at the start of each month when your planned spending is similar to the previous period — instead of entering every category budget again, you copy them in bulk and then adjust individual amounts as needed. The body fields are:
FieldTypeRequiredDescription
yearnumber✅Destination year
monthnumber✅Destination month (0–11, 0-indexed)
yearOriginnumber✅Source year
monthOriginnumber✅Source month (0–11, 0-indexed)
# Copy all budgets from September 2024 (month 8) to October 2024 (month 9)
curl -s -X POST http://localhost:3008/api/budgets \
  -H 'token: <your-jwt>' \
  -H 'Content-Type: application/json' \
  -d '{
    "yearOrigin": 2024,
    "monthOrigin": 8,
    "year": 2024,
    "month": 9
  }'

​
Example: Querying Budgets for a Specific Month

Pass year (required) and month (optional, 0-indexed) as query parameters: 
# Retrieve budgets for October 2024 (month index 9)
curl -s "http://localhost:3008/api/budgets?year=2024&month=9" \
  -H 'token: <your-jwt>'
The response includes each category’s budgeted amount alongside the actual spending accumulated so far in that month, allowing you to compare plan vs. reality at a glance.
Call GET /api/dashboard/stats to get a precomputed summary of the current month’s actual income, actual expenses, and total budgeted amounts — perfect for building a home-screen widget without aggregating transactions yourself.

Build docs developers (and LLMs) love

Get started for freeTalk to us