Skip to main content

​
Endpoint

GET /api/v1/assignments
Retrieve budget assignments for the authenticated user with support for date filtering, category filtering, summaries, and optional unassigned category inclusion.

​
Query parameters

​
month
string
Filter assignments for a specific month in YYYY-MM format. Cannot be used with from_month or to_month
​
from_month
string
Filter assignments from this month onwards (YYYY-MM). Cannot be used with month
​
to_month
string
Filter assignments up to this month (YYYY-MM). Cannot be used with month
​
category_id
string
Filter assignments by category UUID
​
group_id
string
Filter assignments by categories in this group UUID
​
goal_type
string
Filter by category goal type. Options: spending, savings, emergency_fund
​
include_unassigned
boolean
default:"false"
Include categories with no assignment for the specified month (requires single month parameter). Accepts true, false, 1, or 0
​
summary
string
Group results by dimension. Options: month, category, group. Cannot be used with include_unassigned
​
fields
string
Comma-separated list of fields to return. Available fields: id, category_id, month, assigned, rollover, created_at
​
sort
string
default:"month"
Field to sort by. Options: month, assigned, created_at
​
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 assignment objects or summary objects (depending on summary parameter)
​
id
string
Unique assignment identifier (UUID)
​
category_id
string
Category UUID this assignment belongs to
​
month
string
Assignment month in YYYY-MM format
​
assigned
number
Amount assigned to this category for the month
​
rollover
number
Rollover amount from previous months
​
created_at
string
Assignment creation timestamp (ISO 8601)
​
is_assigned
boolean
Whether this category has an assignment (only included when include_unassigned=true)
​
data (when summary=month)
array
Array of monthly summary objects
​
month
string
Month in YYYY-MM format
​
total_assigned
number
Total amount assigned across all categories for this month
​
total_rollover
number
Total rollover amount across all categories for this month
​
row_count
integer
Number of assignments in this month
​
data (when summary=category)
array
Array of category summary objects
​
category_id
string
Category UUID
​
total_assigned
number
Total amount assigned to this category across all months
​
total_rollover
number
Total rollover amount for this category
​
row_count
integer
Number of assignments for this category
​
data (when summary=group)
array
Array of group summary objects
​
group_id
string
Group UUID
​
total_assigned
number
Total amount assigned to categories in this group
​
total_rollover
number
Total rollover amount for categories in this group
​
row_count
integer
Number of assignments in this group
​
meta
object
Pagination and metadata
​
total
integer
Total number of matching assignments or summary rows
​
returned
integer
Number of items 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
​
month
string | null
Month filter applied
​
from_month
string | null
From month filter applied
​
to_month
string | null
To month filter applied
​
include_unassigned
boolean
Whether unassigned categories were included
​
summary
string | null
Summary dimension used (month, category, or group)
​
sort
string
Field used for sorting
​
order
string
Sort order applied

​
Example request

curl -X GET "https://api.cashcat.app/api/v1/assignments?month=2024-03&group_id=g1h2i3j4-k5l6-7890-ghij-234567890123" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Example response

{
  "data": [
    {
      "id": "as1g2n3m-e4n5-6789-asgn-567890123456",
      "category_id": "c1d2e3f4-a5b6-7890-cdef-123456789012",
      "month": "2024-03",
      "assigned": 600.00,
      "rollover": 25.50,
      "created_at": "2024-03-01T08:00:00Z"
    },
    {
      "id": "as2h3n4m-e5n6-7890-asgn-678901234567",
      "category_id": "d2e3f4a5-b6c7-8901-defg-234567890123",
      "month": "2024-03",
      "assigned": 200.00,
      "rollover": 0.00,
      "created_at": "2024-03-01T08:00:00Z"
    }
  ],
  "meta": {
    "total": 2,
    "returned": 2,
    "limit": 100,
    "offset": 0,
    "next_cursor": null,
    "month": "2024-03",
    "from_month": null,
    "to_month": null,
    "include_unassigned": false,
    "sort": "month",
    "order": "asc"
  }
}

​
Example summary request

curl -X GET "https://api.cashcat.app/api/v1/assignments?from_month=2024-01&to_month=2024-03&summary=month" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Example summary response

{
  "data": [
    {
      "month": "2024-01",
      "total_assigned": 2500.00,
      "total_rollover": 150.00,
      "row_count": 12
    },
    {
      "month": "2024-02",
      "total_assigned": 2500.00,
      "total_rollover": 175.50,
      "row_count": 12
    },
    {
      "month": "2024-03",
      "total_assigned": 2600.00,
      "total_rollover": 200.00,
      "row_count": 12
    }
  ],
  "meta": {
    "total": 3,
    "returned": 3,
    "limit": 100,
    "offset": 0,
    "next_cursor": null,
    "month": null,
    "from_month": "2024-01",
    "to_month": "2024-03",
    "summary": "month"
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us