> ## 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.

# Budget Months

> Read monthly envelope status and assign money to categories

Kualia is an envelope budget: each month you assign money to categories, spending draws it down, and leftovers carry forward. The months endpoints expose that monthly view and let you set assignments.

## Get a month

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

`month` is `YYYY-MM`, e.g. `/months/2026-07`.

```json theme={null}
{
  "data": {
    "currency": "USD",
    "month": {
      "month": "2026-07",
      "ready_to_assign": "412.50",
      "summary": {
        "percentage_funded": 82,
        "total_target_amount": "3200.00",
        "total_funded": "2624.00",
        "total_remaining_to_fund": "576.00",
        "total_overspent": "0.00"
      },
      "category_groups": [
        {
          "id": "k1180g...",
          "name": "Essentials",
          "type": "expense",
          "categories": [
            {
              "id": "k5511c...",
              "name": "Groceries",
              "archived": false,
              "category_type": "custom",
              "assigned": "600.00",
              "activity": "-484.20",
              "carryover_from_previous": "13.75",
              "available": "129.55",
              "target": {
                "assignment_needed": "600.00",
                "remaining_to_assign": "0.00",
                "underfunded_amount": "0.00",
                "overfunded_by_amount": "0.00",
                "funded_ratio": 1,
                "snoozed": false
              }
            }
          ]
        }
      ]
    }
  }
}
```

Per category: `assigned` is what you allocated this month, `activity` is the month's spending/inflows, `carryover_from_previous` is what rolled over, and `available` is what's left to spend. The `target` block reflects the category's savings/spending target for the month.

## Set a category's assigned amount

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

```bash theme={null}
curl -X PATCH https://api.kualia.com/v1/workspaces/WORKSPACE_ID/months/2026-07/categories/CATEGORY_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "assigned": "650.00" }'
```

<Warning>
  `assigned` **overwrites** the month's assignment — it is not an increment. To add \$50 to a category that already has
  \$600 assigned, send `"assigned": "650.00"`. Negative values pull money back to Ready to Assign.
</Warning>

The response returns the category's refreshed month status (same shape as in `GET /months/{month}`), so you can see the new `available` immediately.