Skip to main content
Categories are your budget envelopes, organized into category groups. System-managed items (like the Credit Card Payments group and its categories) are readable but cannot be modified through the API.

​
List categories (grouped)

GET /v1/workspaces/{workspace_id}/categories

{
  "data": {
    "category_groups": [
      {
        "id": "k1180g...",
        "name": "Essentials",
        "type": "expense",
        "system": false,
        "categories": [
          {
            "id": "k5511c...",
            "name": "Groceries",
            "group_id": "k1180g...",
            "archived": false,
            "system": false,
            "category_type": "custom"
          }
        ]
      }
    ]
  }
}
For assigned/spent/available amounts per category, use the months endpoints.

​
Get a category

GET /v1/workspaces/{workspace_id}/categories/{category_id}

​
Create a category

POST /v1/workspaces/{workspace_id}/categories

{ "name": "Vacation", "group_id": "k1180g..." }
New categories are inserted at the top of their group.

​
Update a category

PATCH /v1/workspaces/{workspace_id}/categories/{category_id}
FieldTypeDescription
namestringRename the category
group_idstringMove it to another group
archivedbooleanArchive (true) or unarchive

​
Delete a category

DELETE /v1/workspaces/{workspace_id}/categories/{category_id}
Query parameterTypeDescription
move_to_category_idstringRecategorize the category’s transactions to this category
Without move_to_category_id, affected transactions become uncategorized.

​
Category groups

GET   /v1/workspaces/{workspace_id}/category_groups
POST  /v1/workspaces/{workspace_id}/category_groups
PATCH /v1/workspaces/{workspace_id}/category_groups/{group_id}
POST takes { "name": "..." } and creates an expense group (duplicate names return 409). PATCH takes { "name": "..." } to rename. Groups cannot be deleted through the API; move or delete their categories first, then remove the group in the app.