Categories

Overview

The Categories API provides read-only access to transaction categories. Categories help organize transactions and trades into logical groups for budgeting and reporting. Categories can be hierarchical with parent categories and subcategories.

List
Get

curl -X GET "https://api.sure.app/v1/categories?classification=expense" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Retrieve a paginated list of categories with optional filtering.

Query parameters

page

integer

default:"1"

Page number for pagination

per_page

integer

default:"25"

Number of categories per page (max 100)

classification

string

Filter by classification: income or expense

roots_only

boolean

If true, only return root categories (no parent)

parent_id

integer

Filter by parent category ID (returns only subcategories)

Response

categories

array

Array of category objects

Show Category object

integer

Unique identifier for the category

name

string

Category name

classification

string

Category classification: income or expense

color

string

Hex color code for UI display (e.g., “#f97316”)

icon

string

Lucide icon name for UI display

parent

object

Parent category information (null for root categories)

Show Parent

integer

Parent category ID

name

string

Parent category name

subcategories_count

integer

Number of subcategories

created_at

string

ISO 8601 timestamp

updated_at

string

ISO 8601 timestamp

pagination

object

Pagination metadata

{
  "categories": [
    {
      "id": 5,
      "name": "Food & Drink",
      "classification": "expense",
      "color": "#f97316",
      "icon": "utensils",
      "parent": null,
      "subcategories_count": 2,
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    },
    {
      "id": 15,
      "name": "Restaurants",
      "classification": "expense",
      "color": "#f97316",
      "icon": "utensils",
      "parent": {
        "id": 5,
        "name": "Food & Drink"
      },
      "subcategories_count": 0,
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    },
    {
      "id": 6,
      "name": "Shopping",
      "classification": "expense",
      "color": "#3b82f6",
      "icon": "shopping-cart",
      "parent": null,
      "subcategories_count": 0,
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total_count": 3,
    "total_pages": 1
  }
}

Get a category

curl -X GET https://api.sure.app/v1/categories/5 \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Retrieve a specific category by ID.

Path parameters

integer

required

Category ID

Response

Returns a category object.

{
  "id": 5,
  "name": "Food & Drink",
  "classification": "expense",
  "color": "#f97316",
  "icon": "utensils",
  "parent": null,
  "subcategories_count": 2,
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}

Category hierarchy

Parent and subcategories

Categories can have a two-level hierarchy:

Root categories: Top-level categories with no parent
Subcategories: Child categories that belong to a parent

Subcategories inherit the color of their parent category and must have the same classification (income or expense).

Filtering by hierarchy

To work with category hierarchies:

Get only root categories

curl -X GET "https://api.sure.app/v1/categories?roots_only=true" \
  -H "X-Api-Key: YOUR_API_KEY"

Get subcategories of a parent

curl -X GET "https://api.sure.app/v1/categories?parent_id=5" \
  -H "X-Api-Key: YOUR_API_KEY"

Category properties

Classification

Categories are classified as either:

income: For income transactions (salary, interest, etc.)
expense: For expense transactions (most transaction categories)

Display properties

color: Hex color code for consistent UI display across your application
icon: Lucide icon name for visual representation
name: Human-readable category name

Common expense categories

Category	Icon	Use case
Food & Drink	utensils	Restaurants, dining
Groceries	shopping-bag	Grocery shopping
Shopping	shopping-cart	Retail purchases
Transportation	bus	Gas, parking, transit
Travel	plane	Hotels, flights
Entertainment	drama	Movies, events
Healthcare	pill	Medical expenses
Utilities	lightbulb	Electric, water, internet
Mortgage / Rent	home	Housing payments
Insurance	shield	Insurance premiums

Read-only resource

Categories are read-only through the API. Category management (creating, updating, and deleting) is handled through the Sure web interface to maintain data consistency and integrity across your workspace. To assign a category to a transaction or trade, use the category_id field when creating or updating those resources.

Error responses

error

string

Error code identifier

message

string

Human-readable error description

{
  "error": "unauthorized",
  "message": "Invalid or missing API key"
}

Getting Started

Resources

Overview

Query parameters

Response

Get a category

Path parameters

Response

Category hierarchy

Parent and subcategories

Filtering by hierarchy

Category properties

Classification

Display properties

Common expense categories

Read-only resource

Error responses

Build docs developers (and LLMs) love

Getting Started

Resources

​Overview

​List categories

​Query parameters

​Response

​Get a category

​Path parameters

​Response

​Category hierarchy

​Parent and subcategories

​Filtering by hierarchy

​Category properties

​Classification

​Display properties

​Common expense categories

​Read-only resource

​Error responses

Build docs developers (and LLMs) love

Overview

List categories

Query parameters

Response

Get a category

Path parameters

Response

Category hierarchy

Parent and subcategories

Filtering by hierarchy

Category properties

Classification

Display properties

Common expense categories

Read-only resource

Error responses