Skip to main content
GET
/
api
/
categories
List Categories
curl --request GET \
  --url https://api.example.com/api/categories
{
  "data": [
    {
      "id": "<string>",
      "userId": "<string>",
      "name": "<string>",
      "type": "<string>",
      "isFixed": true,
      "color": "<string>",
      "icon": "<string>",
      "parentId": "<string>",
      "createdAt": "<string>",
      "updatedAt": "<string>",
      "deletedAt": "<string>"
    }
  ],
  "meta": {
    "total": 123,
    "page": 123,
    "limit": 123,
    "totalPages": 123
  }
}

​
Endpoint

GET /api/categories
Returns a paginated list of categories owned by the authenticated user. Categories are returned in a flat structure with parentId indicating hierarchical relationships.

​
Authentication

Requires JWT authentication via Authorization: Bearer <token> header.

​
Query Parameters

​
type
enum
Filter by category type. One of:
  • INCOME - Only income categories
  • EXPENSE - Only expense categories
  • BOTH - Only categories marked as both
  • both (lowercase) - Returns all categories regardless of type
​
page
number
default:"1"
Page number for pagination (1-indexed)
​
limit
number
default:"20"
Number of items per page

​
Response

Returns a paginated result object:
​
data
array
Array of category objects
​
id
string
Unique identifier (UUID)
​
userId
string
Owner user ID
​
name
string
Category name
​
type
string
Category type (INCOME, EXPENSE, or BOTH)
​
isFixed
boolean
Whether this is a fixed monthly expense
​
color
string
Hex color code
​
icon
string
Icon identifier
​
parentId
string
ID of parent category (null for root categories)
​
createdAt
string
ISO 8601 creation timestamp
​
updatedAt
string
ISO 8601 last update timestamp
​
deletedAt
string
ISO 8601 deletion timestamp (always null for active categories)
​
meta
object
Pagination metadata
​
total
number
Total number of items matching the query
​
page
number
Current page number
​
limit
number
Items per page
​
totalPages
number
Total number of pages available

​
Hierarchical Structure

Categories are returned in a flat array. Use the parentId field to reconstruct the hierarchy on the client:
  • Root categories have parentId: null
  • Subcategories have parentId set to their parent’s UUID

​
Example Request

GET /api/categories?type=EXPENSE&page=1&limit=10

​
Example Response

{
  "data": [
    {
      "id": "cat-parent-uuid",
      "userId": "user-uuid",
      "name": "Entertainment",
      "type": "EXPENSE",
      "isFixed": false,
      "color": "#E74C3C",
      "icon": "film",
      "parentId": null,
      "createdAt": "2026-01-15T08:00:00.000Z",
      "updatedAt": "2026-01-15T08:00:00.000Z",
      "deletedAt": null
    },
    {
      "id": "cat-child-uuid",
      "userId": "user-uuid",
      "name": "Streaming Services",
      "type": "EXPENSE",
      "isFixed": true,
      "color": "#9B59B6",
      "icon": "tv",
      "parentId": "cat-parent-uuid",
      "createdAt": "2026-01-15T08:05:00.000Z",
      "updatedAt": "2026-01-15T08:05:00.000Z",
      "deletedAt": null
    }
  ],
  "meta": {
    "total": 2,
    "page": 1,
    "limit": 10,
    "totalPages": 1
  }
}

​
Filtering Examples

​
Get all expense categories

GET /api/categories?type=EXPENSE

​
Get all categories (regardless of type)

GET /api/categories?type=both

​
Get income categories with pagination

GET /api/categories?type=INCOME&page=2&limit=20

Build docs developers (and LLMs) love

Get started for freeTalk to us