Skip to main content

​
Endpoint

GET /api/v1/categories
Retrieve all budget categories for the authenticated user with support for filtering by group, goal type, and other attributes.

​
Query parameters

​
q
string
Search categories by name using case-insensitive pattern matching
​
group_id
string
Filter categories by group UUID
​
ids
string
Comma-separated list of category UUIDs to filter by
​
goal_type
string
Filter by goal type. Options: spending, savings, emergency_fund
​
rollover_enabled
boolean
default:"false"
Filter by rollover enabled status. Accepts true, false, 1, or 0
​
has_goal
boolean
default:"true"
Filter categories that have a goal set (goal > 0). Accepts true, false, 1, or 0
​
include_group
boolean
default:"false"
Include group name in response. Accepts true, false, 1, or 0
​
fields
string
Comma-separated list of fields to return. Available fields: id, name, group, goal, goal_type, rollover_enabled, timeframe, created_at, group_name
​
sort
string
default:"name"
Field to sort by. Options: name, goal, created_at, goal_type
​
order
string
default:"asc"
Sort order. Options: asc, desc
​
limit
integer
default:"100"
Maximum number of results to return (1-1000)
​
offset
integer
default:"0"
Number of results to skip for pagination
​
cursor
string
Cursor for pagination. Cannot be used with offset

​
Response fields

​
data
array
Array of category objects
​
id
string
Unique category identifier (UUID)
​
name
string
Category name
​
group
string
Group UUID this category belongs to
​
goal
number | null
Monthly budget goal amount
​
goal_type
string
Type of goal: spending, savings, or emergency_fund
​
rollover_enabled
boolean
Whether unused budget rolls over to next month
​
timeframe
string | null
Goal timeframe
​
created_at
string
Category creation timestamp (ISO 8601)
​
group_name
string | null
Name of the group (only included when include_group=true)
​
meta
object
Pagination and metadata
​
total
integer
Total number of matching categories
​
returned
integer
Number of categories returned in this response
​
limit
integer
Maximum results per page
​
offset
integer
Current offset
​
next_cursor
string | null
Cursor for the next page, or null if no more results
​
sort
string
Field used for sorting
​
order
string
Sort order applied
​
include_group
boolean
Whether group names were included

​
Example request

curl -X GET "https://api.cashcat.app/api/v1/categories?goal_type=spending&include_group=true&sort=goal&order=desc" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Example response

{
  "data": [
    {
      "id": "c1d2e3f4-a5b6-7890-cdef-123456789012",
      "name": "Groceries",
      "group": "g1h2i3j4-k5l6-7890-ghij-234567890123",
      "goal": 600.00,
      "goal_type": "spending",
      "rollover_enabled": true,
      "timeframe": "monthly",
      "created_at": "2024-01-01T12:00:00Z",
      "group_name": "Essential Expenses"
    },
    {
      "id": "d2e3f4a5-b6c7-8901-defg-234567890123",
      "name": "Dining Out",
      "group": "g1h2i3j4-k5l6-7890-ghij-234567890123",
      "goal": 200.00,
      "goal_type": "spending",
      "rollover_enabled": false,
      "timeframe": "monthly",
      "created_at": "2024-01-02T10:00:00Z",
      "group_name": "Essential Expenses"
    }
  ],
  "meta": {
    "total": 2,
    "returned": 2,
    "limit": 100,
    "offset": 0,
    "next_cursor": null,
    "sort": "goal",
    "order": "desc",
    "include_group": true
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us