> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kualia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Categories

> Manage envelope categories and category groups

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)

```text theme={null}
GET /v1/workspaces/{workspace_id}/categories
```

```json theme={null}
{
  "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"
          }
        ]
      }
    ]
  }
}
```

<Note>For assigned/spent/available amounts per category, use the [months endpoints](/api/months).</Note>

## Get a category

```text theme={null}
GET /v1/workspaces/{workspace_id}/categories/{category_id}
```

## Create a category

```text theme={null}
POST /v1/workspaces/{workspace_id}/categories
```

```json theme={null}
{ "name": "Vacation", "group_id": "k1180g..." }
```

New categories are inserted at the top of their group.

## Update a category

```text theme={null}
PATCH /v1/workspaces/{workspace_id}/categories/{category_id}
```

| Field      | Type    | Description                   |
| ---------- | ------- | ----------------------------- |
| `name`     | string  | Rename the category           |
| `group_id` | string  | Move it to another group      |
| `archived` | boolean | Archive (`true`) or unarchive |

## Delete a category

```text theme={null}
DELETE /v1/workspaces/{workspace_id}/categories/{category_id}
```

| Query parameter       | Type   | Description                                               |
| --------------------- | ------ | --------------------------------------------------------- |
| `move_to_category_id` | string | Recategorize the category's transactions to this category |

Without `move_to_category_id`, affected transactions become uncategorized.

## Category groups

```text theme={null}
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.