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.

Budgets set a monthly spending limit for a given category. Finper stores one budget record per (category, year, month, user) combination. The budget system supports upsert semantics — the same PATCH endpoint creates or updates depending on whether a record already exists — and a copy operation that replicates an entire month’s budget plan to a different period. All endpoints require the token header.
Budgets enforce a unique constraint on the combination of (category, year, month, user). The PATCH /:category/:year/:month endpoint relies on this index to perform an upsert: if a budget for that combination already exists it is updated, otherwise a new budget record is inserted.

​
GET /api/budgets

List all budgets for the authenticated user, optionally filtered by year and/or month. GET /api/budgets

​
Query Parameters

​
year
number
required
The calendar year to retrieve budgets for (e.g. 2024).
​
month
number
The month number (0–11, where 0 = January and 11 = December). If omitted, all months for the specified year are returned.

​
Response — 200 OK

Returns an array of budget objects. The category field is populated with the category object.
​
id
string
Unique identifier of the budget record.
​
category
object
Populated category object (id, name, type).
​
year
number
The budget year.
​
month
number
The budget month (0–11).
​
amount
number
The budgeted spending limit for this category in this period.

​
Example

curl "http://localhost:3008/api/budgets?year=2024&month=0" \
  -H 'token: <your-jwt>'

​
PATCH /api/budgets/:category/:year/:month

Create or update the budget amount for a specific category and period. PATCH /api/budgets/:category/:year/:month This endpoint uses upsert semantics: if a budget already exists for the given (category, year, month) combination it is updated; otherwise a new budget record is created.

​
Path Parameters

​
category
string
required
The ID of the category to set the budget for. The category must belong to the authenticated user.
​
year
number
required
The calendar year (e.g. 2024).
​
month
number
required
The month number (0–11, where 0 = January and 11 = December).

​
Request Body

​
amount
number
required
The spending limit to set for this category and period.

​
Response — 200 OK

Returns the upserted budget object.

​
Example

# Set a €500 grocery budget for January 2024 (month=0)
curl -X PATCH "http://localhost:3008/api/budgets/64a1f2e3b4c5d6e7f8g9h0c1/2024/0" \
  -H 'token: <your-jwt>' \
  -H 'Content-Type: application/json' \
  -d '{"amount": 500}'

​
POST /api/budgets

Copy all budgets from one month to another. POST /api/budgets This is a bulk-copy operation. It reads every budget that exists for the origin period and creates (or overwrites) corresponding budget records in the destination period. This is useful for recurring monthly plans where most category limits stay the same.

​
Request Body

​
yearOrigin
number
required
The source year to copy budgets from. Must be between 2000 and 2100.
​
monthOrigin
number
required
The source month (0–11) to copy budgets from.
​
year
number
required
The destination year to copy budgets to. Must be between 2000 and 2100.
​
month
number
required
The destination month (0–11) to copy budgets to.

​
Response — 200 OK

Returns the list of budget records created or updated in the destination period.

​
Example

# Copy all budgets from January 2024 to February 2024
curl -X POST http://localhost:3008/api/budgets \
  -H 'token: <your-jwt>' \
  -H 'Content-Type: application/json' \
  -d '{
    "yearOrigin": 2024,
    "monthOrigin": 0,
    "year": 2024,
    "month": 1
  }'

Build docs developers (and LLMs) love

Get started for freeTalk to us