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 organize transactions into meaningful groups such as “Groceries”, “Salary”, or “Utilities”. Finper supports a one-level hierarchy: a category can have an optional parent category, but nesting is limited to a single level deep. Categories also carry a type that must match the transactions they are assigned to. All endpoints require the token header.

​
Category Type Reference

TypeDescription
expenseUsed for outgoing transactions.
incomeUsed for incoming transactions.
not_computableUsed for neutral movements (e.g. transfers).

​
POST /api/categories

Create a new category for the authenticated user. POST /api/categories

​
Request Body

​
name
string
required
Human-readable name for the category (e.g. "Groceries", "Salary").
​
type
string
required
Category type. One of: income, expense, not_computable.
​
parent
string
Optional ID of an existing category to use as the parent. The parent must belong to the authenticated user. If provided, this category becomes a child of the specified parent.
​
budgetRuleClass
string
Optional budget rule classification for the 50/30/20 rule. One of: needs, wants, savings, none. Defaults to none.

​
Response — 201 Created

Returns the newly created category object.

​
Example

curl -X POST http://localhost:3008/api/categories \
  -H 'token: <your-jwt>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Groceries",
    "type": "expense",
    "parent": "64a1f2e3b4c5d6e7f8g9h0c0",
    "budgetRuleClass": "needs"
  }'

​
GET /api/categories

List all categories for the authenticated user as a flat array. GET /api/categories

​
Response — 200 OK

Returns a flat array of all category objects, including both root categories and their children. Each category includes its parent ID if one exists.
​
id
string
Unique identifier.
​
name
string
Category name.
​
type
string
One of income, expense, or not_computable.
​
parent
string
ID of the parent category, if this is a child category. null for root categories.
​
budgetRuleClass
string
Budget rule class: needs, wants, savings, or none.

​
Example

curl http://localhost:3008/api/categories \
  -H 'token: <your-jwt>'

​
GET /api/categories/grouped

List categories grouped by their parent category. GET /api/categories/grouped

​
Response — 200 OK

Returns categories structured hierarchically, with child categories nested under their respective parents. Root categories with no parent appear at the top level.

​
Example

curl http://localhost:3008/api/categories/grouped \
  -H 'token: <your-jwt>'

[
  {
    "id": "64a1f2e3b4c5d6e7f8g9h0c0",
    "name": "Food",
    "type": "expense",
    "parent": null,
    "budgetRuleClass": "needs",
    "children": [
      {
        "id": "64a1f2e3b4c5d6e7f8g9h0c1",
        "name": "Groceries",
        "type": "expense",
        "parent": "64a1f2e3b4c5d6e7f8g9h0c0",
        "budgetRuleClass": "needs"
      }
    ]
  }
]

​
PATCH /api/categories/:id

Update an existing category’s fields. PATCH /api/categories/:id
Although PATCH semantically implies optional fields, the underlying edit schema marks name and type as required — both fields must be present together whenever a body is sent. You cannot update name alone without also supplying type, and vice versa. The optional fields (parent, budgetRuleClass) may be omitted freely.

​
Path Parameters

​
id
string
required
The unique identifier of the category to update.

​
Request Body

​
name
string
required
Updated category name. Must be provided alongside type.
​
type
string
required
Updated type. One of: income, expense, not_computable. Must be provided alongside name.
​
parent
string
Updated parent category ID. The parent must exist and belong to the authenticated user.
​
budgetRuleClass
string
Updated budget rule class. One of: needs, wants, savings, none.

​
Response — 200 OK

Returns the updated category object.

​
Example

curl -X PATCH http://localhost:3008/api/categories/64a1f2e3b4c5d6e7f8g9h0c1 \
  -H 'token: <your-jwt>' \
  -H 'Content-Type: application/json' \
  -d '{"name": "Supermarket", "type": "expense"}'

​
DELETE /api/categories/:id

Permanently delete a category. DELETE /api/categories/:id

​
Path Parameters

​
id
string
required
The unique identifier of the category to delete.

​
Response — 204 No Content

No response body on success.
Deleting a category that has transactions or budgets associated with it may leave those records without a valid category reference. Before deleting, reassign or delete any transactions and budgets that reference this category to maintain data integrity.

​
Example

curl -X DELETE http://localhost:3008/api/categories/64a1f2e3b4c5d6e7f8g9h0c1 \
  -H 'token: <your-jwt>'

Build docs developers (and LLMs) love

Get started for freeTalk to us