Reference: Categories

A category is an envelope you assign money to — rent, groceries, the vacation fund — with a budgeted amount, activity, and balance for a given month. Categories live inside category groups. Two tools here operate on a specific month (update_category_budget, get_month_category); the rest operate on the category’s own record. Note: the YNAB API has no endpoint for reordering categories within a group, so no tool here can do that either.

Tools

create_category WRITE

Create a category in a category group (newer YNAB endpoint; verify availability on your plan).

**Milliunits:** `goal_target` — 1000 = one currency unit.

Parameters

Name	Type	Required	Description
budget_id	string		Budget id or alias (“last-used”, “default”). Defaults to YNAB_BUDGET_ID.
name	string	✓
category_group_id	string	✓
goal_target	number
goal_target_date	string
goal_needs_whole_amount	boolean

YNAB API

• POST /budgets/{budget_id}/categories → Categories/createCategory

create_category_group WRITE

Create a category group (newer YNAB endpoint; verify availability on your plan).

Parameters

Name	Type	Required	Description
budget_id	string		Budget id or alias (“last-used”, “default”). Defaults to YNAB_BUDGET_ID.
name	string	✓

YNAB API

• POST /budgets/{budget_id}/category_groups → Categories/createCategoryGroup

get_category READ

Get one category by id (current month figures).

Parameters

Name	Type	Required	Description
budget_id	string		Budget id or alias (“last-used”, “default”). Defaults to YNAB_BUDGET_ID.
category_id	string	✓

YNAB API

• GET /budgets/{budget_id}/categories/{category_id} → Categories/getCategoryById

get_month_category READ

Get one category’s figures for a specific month (budgeted/activity/balance).

Parameters

Name	Type	Required	Description
budget_id	string		Budget id or alias (“last-used”, “default”). Defaults to YNAB_BUDGET_ID.
month	string		ISO month or “current”. Defaults to current.
category_id	string	✓

YNAB API

• GET /budgets/{budget_id}/months/{month}/categories/{category_id} → Categories/getMonthCategoryById

list_categories READ

List category groups and their categories (budgeted, activity, balance).

Parameters

Name	Type	Required	Description
budget_id	string		Budget id or alias (“last-used”, “default”). Defaults to YNAB_BUDGET_ID.
last_knowledge_of_server	number

YNAB API

• GET /budgets/{budget_id}/categories → Categories/getCategories

update_category WRITE

Rename a category, set its note, and/or MOVE it to another group via category_group_id (newer YNAB endpoint). Note: YNAB has no API for reordering categories within a group.

**Milliunits:** `goal_target` — 1000 = one currency unit.

Parameters

Name	Type	Required	Description
budget_id	string		Budget id or alias (“last-used”, “default”). Defaults to YNAB_BUDGET_ID.
category_id	string	✓
name	string
note	string
category_group_id	string		Move the category into this group.
goal_target	number
goal_target_date	string
goal_needs_whole_amount	boolean

YNAB API

• PATCH /budgets/{budget_id}/categories/{category_id} → Categories/updateCategory

update_category_budget WRITE

Set the budgeted amount (milliunits) for a category in a given month.

**Milliunits:** `budgeted` — 1000 = one currency unit.

Parameters

Name	Type	Required	Description
budget_id	string		Budget id or alias (“last-used”, “default”). Defaults to YNAB_BUDGET_ID.
month	string		“YYYY-MM-01” or “current”.
category_id	string	✓
budgeted	number	✓	Budgeted amount in milliunits (1000 = 1 unit).

YNAB API

• PATCH /budgets/{budget_id}/months/{month}/categories/{category_id} → Categories/updateMonthCategory

update_category_group WRITE

Rename a category group (newer YNAB endpoint).

Parameters

Name	Type	Required	Description
budget_id	string		Budget id or alias (“last-used”, “default”). Defaults to YNAB_BUDGET_ID.
category_group_id	string	✓
name	string	✓

YNAB API

• PATCH /budgets/{budget_id}/category_groups/{category_group_id} → Categories/updateCategoryGroup