Budget Months - Kualia

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

GET /v1/workspaces/{workspace_id}/months/{month}

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

{
  "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

PATCH /v1/workspaces/{workspace_id}/months/{month}/categories/{category_id}

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" }'

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.

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

​Get a month

​Set a category’s assigned amount

Get a month

Set a category’s assigned amount