Get the authenticated user's information.

Args: exclude_fields: Optional list of field names to exclude from the response. If omitted, the model's default exclude list is used (see FIELDS.md). Pass [] to return all fields. Pass a custom list to override the default.

List all plans in the user's YNAB account. Call this first to get plan IDs.

Args: exclude_fields: Optional list of field names to exclude from each plan. If omitted, the model's default exclude list is used (see FIELDS.md). Pass [] to return all fields. Pass a custom list to override the default.

Get details for a specific plan.

Args: plan_id: The plan ID (use list_plans to find available IDs) exclude_fields: Optional list of field names to exclude from the response. If omitted, the model's default exclude list is used (see FIELDS.md). Pass [] to return all fields. Pass a custom list to override the default.

Get settings for a plan (date format and currency format).

Args: plan_id: The plan ID (use list_plans to find available IDs) exclude_fields: Optional list of field names to exclude from the response. If omitted, the model's default exclude list is used (see FIELDS.md). Pass [] to return all fields. Pass a custom list to override the default.

List all accounts in a plan.

Args: plan_id: The plan ID (use list_plans to find available IDs) exclude_fields: Optional list of field names to exclude from each account. If omitted, the model's default exclude list is used (see FIELDS.md). Pass [] to return all fields. Pass a custom list to override the default.

Create a new account.

Args: plan_id: The plan ID (use list_plans to find available IDs) name: The name of the account type: The type of account ('checking', 'savings', 'cash', 'creditCard', 'lineOfCredit', 'otherAsset', 'otherLiability', 'mortgage', 'autoLoan', 'studentLoan', 'personalLoan', 'medicalDebt', 'otherDebt') balance: The current balance in dollars (e.g. 1000.00) exclude_fields: Optional list of field names to exclude from the response. If omitted, the model's default exclude list is used (see FIELDS.md). Pass [] to return all fields. Pass a custom list to override the default.

Get details for a specific account.

Args: account_id: The account ID plan_id: The plan ID (use list_plans to find available IDs) exclude_fields: Optional list of field names to exclude from the response. If omitted, the model's default exclude list is used (see FIELDS.md). Pass [] to return all fields. Pass a custom list to override the default.

List transactions in a plan. Can filter by date and type.

Args: plan_id: The plan ID (use list_plans to find available IDs) since_date: Only return transactions on or after this date (YYYY-MM-DD) type: Filter by 'uncategorized' or 'unapproved' exclude_fields: Optional list of field names to exclude from each transaction. If omitted, the model's default exclude list is used (see FIELDS.md). Pass [] to return all fields. Pass a custom list to override the default.

Get a specific transaction by ID.

Args: transaction_id: The transaction ID plan_id: The plan ID (use list_plans to find available IDs) exclude_fields: Optional list of field names to exclude from the response. If omitted, the model's default exclude list is used (see FIELDS.md). Pass [] to return all fields. Pass a custom list to override the default.

Get transactions for a specific account, excluding pending transactions.

Args: account_id: The account ID plan_id: The plan ID (use list_plans to find available IDs) since_date: Only return transactions on or after this date (YYYY-MM-DD) type: Filter by 'uncategorized' or 'unapproved' exclude_fields: Optional list of field names to exclude from each transaction. If omitted, the model's default exclude list is used (see FIELDS.md). Pass [] to return all fields. Pass a custom list to override the default.

Get all transactions for a specific category, excluding pending transactions.

Returns hybrid transactions which may represent regular transactions or subtransactions of split transactions. Each result includes a 'type' field ('transaction' or 'subtransaction') and 'parent_transaction_id' (set on subtransactions only).

Args: category_id: The category ID plan_id: The plan ID (use list_plans to find available IDs) since_date: Only return transactions on or after this date (YYYY-MM-DD) type: Filter by 'uncategorized' or 'unapproved' exclude_fields: Optional list of field names to exclude from each transaction. If omitted, the model's default exclude list is used (see FIELDS.md). Pass [] to return all fields. Pass a custom list to override the default.

Get all transactions for a specific plan month, excluding pending transactions.

Args: month: Month in YYYY-MM-DD format (first of month) or 'current' plan_id: The plan ID (use list_plans to find available IDs) since_date: Only return transactions on or after this date (YYYY-MM-DD) type: Filter by 'uncategorized' or 'unapproved' exclude_fields: Optional list of field names to exclude from each transaction. If omitted, the model's default exclude list is used (see FIELDS.md). Pass [] to return all fields. Pass a custom list to override the default.

Get all transactions for a specific payee, excluding pending transactions.

Returns hybrid transactions which may represent regular transactions or subtransactions of split transactions. Each result includes a 'type' field ('transaction' or 'subtransaction') and 'parent_transaction_id' (set on subtransactions only).

Args: payee_id: The payee ID plan_id: The plan ID (use list_plans to find available IDs) since_date: Only return transactions on or after this date (YYYY-MM-DD) type: Filter by 'uncategorized' or 'unapproved' exclude_fields: Optional list of field names to exclude from each transaction. If omitted, the model's default exclude list is used (see FIELDS.md). Pass [] to return all fields. Pass a custom list to override the default.

Search transactions by text across payee, memo, and category fields.

Args: plan_id: The plan ID (use list_plans to find available IDs) query: Text to search for (case-insensitive, matches payee, memo, and category) since_date: Only search transactions on or after this date (YYYY-MM-DD) amount_min: Minimum amount in dollars (e.g. -100.00). Filters by absolute value if both min and max are positive, otherwise by raw value. amount_max: Maximum amount in dollars (e.g. -10.00) exclude_fields: Optional list of field names to exclude from each transaction. If omitted, the model's default exclude list is used (see FIELDS.md). Pass [] to return all fields. Pass a custom list to override the default.

Create a new transaction. Future-dated transactions are not permitted (use scheduled transactions instead).

Args: plan_id: The plan ID (use list_plans to find available IDs) account_id: The account ID for this transaction date: Transaction date in YYYY-MM-DD format (must not be in the future) amount: Amount in dollars (negative for outflow, positive for inflow). e.g. -50.25 for spending $50.25 payee_id: Payee ID (use list_payees to find available IDs). For account transfers, use the target account's transfer_payee_id. payee_name: Payee name. If payee_id is null, this resolves to an existing payee or creates a new one. category_id: Category ID. Use null with subtransactions to create a split. Credit Card Payment categories are ignored. memo: Memo/note (max 500 chars) cleared: 'cleared', 'uncleared', or 'reconciled' approved: Whether the transaction is approved flag_color: 'red', 'orange', 'yellow', 'green', 'blue', 'purple', or null import_id: Unique import identifier (max 36 chars). Used for matching against imported transactions. subtransactions: For splits, an array of dicts with keys: amount (dollars, required), payee_id, payee_name, category_id, memo exclude_fields: Optional list of field names to exclude from the response. If omitted, the model's default exclude list is used (see FIELDS.md). Pass [] to return all fields. Pass a custom list to override the default.

Create multiple transactions in a single API call. Ideal for bulk imports.

Future-dated transactions are not permitted. The response includes any duplicate_import_ids that were rejected because of an existing import_id on the same account.

Args: plan_id: The plan ID (use list_plans to find available IDs) account_id: Default account ID for all transactions transactions: List of transaction dicts, each with: - date: Transaction date in YYYY-MM-DD format (required) - amount: Amount in dollars (required, negative for outflow, positive for inflow) - account_id: (optional) Override the default account ID - payee_id: (optional) Payee ID - payee_name: (optional) Payee name (resolves to existing or creates a new payee) - category_id: (optional) Category ID. Use null with subtransactions for splits. - memo: (optional) Memo (max 500 chars) - cleared: (optional) 'cleared', 'uncleared', or 'reconciled' (default: 'uncleared') - approved: (optional) Whether the transaction is approved (default: false) - flag_color: (optional) 'red', 'orange', 'yellow', 'green', 'blue', 'purple', or null - import_id: (optional) Unique import identifier (max 36 chars) - subtransactions: (optional) For splits, a list of subtransaction dicts with: amount, payee_id, payee_name, category_id, memo exclude_fields: Optional list of field names to exclude from each created transaction. If omitted, the model's default exclude list is used (see FIELDS.md). Pass [] to return all fields. Pass a custom list to override the default.

Update an existing transaction. Only provide the fields you want to change.

Future-dated transactions are not permitted. Split transaction amounts and dates cannot be changed. If an existing transaction is a split, category_id cannot be changed and updating subtransactions is not supported.

Args: plan_id: The plan ID (use list_plans to find available IDs) transaction_id: The transaction ID to update account_id: New account ID date: New date (YYYY-MM-DD, must not be in the future) amount: New amount in dollars (negative for outflow, positive for inflow) payee_id: New payee ID. For account transfers, use target account's transfer_payee_id. payee_name: New payee name (resolves to existing or creates a new payee) category_id: New category ID. Use null with subtransactions to create a split. memo: New memo (max 500 chars) cleared: 'cleared', 'uncleared', or 'reconciled' approved: Whether the transaction is approved flag_color: 'red', 'orange', 'yellow', 'green', 'blue', 'purple', or null subtransactions: For creating a new split, list of dicts with: amount, payee_id, payee_name, category_id, memo exclude_fields: Optional list of field names to exclude from the response. If omitted, the model's default exclude list is used (see FIELDS.md). Pass [] to return all fields. Pass a custom list to override the default.

Delete a transaction.

Args: transaction_id: The transaction ID to delete plan_id: The plan ID (use list_plans to find available IDs) exclude_fields: Optional list of field names to exclude from the response. If omitted, the model's default exclude list is used (see FIELDS.md). Pass [] to return all fields. Pass a custom list to override the default.

Import available transactions on all linked accounts for the given plan.

Equivalent to clicking 'Import' on each account in the YNAB web app or tapping the 'New Transactions' banner in the mobile app. Returns the list of transaction IDs that were imported.

Args: plan_id: The plan ID (use list_plans to find available IDs)

Update multiple transactions in a single API call.

Each transaction must include either 'id' or 'import_id' for lookup (not both). Only provided fields are updated (sparse update). Ideal for bulk recategorization, bulk approval, bulk clearing, etc. Updating subtransactions on an existing split is not supported. Future-dated transactions are not permitted.

Args: plan_id: The plan ID (use list_plans to find available IDs) transactions: List of transaction dicts. Each must include EITHER: - id: The transaction ID OR - import_id: The transaction's import_id (used for lookup, cannot be changed) And optionally any of: - account_id: New account ID - date: New date (YYYY-MM-DD) - amount: New amount in dollars (negative for outflow, positive for inflow) - payee_id: New payee ID - payee_name: New payee name - category_id: New category ID (use null with subtransactions to create a split) - memo: New memo (max 500 chars) - cleared: 'cleared', 'uncleared', or 'reconciled' - approved: Whether the transaction is approved - flag_color: 'red', 'orange', 'yellow', 'green', 'blue', 'purple', or null - subtransactions: For creating a new split, list of dicts with: amount, payee_id, payee_name, category_id, memo exclude_fields: Optional list of field names to exclude from each updated transaction. If omitted, the model's default exclude list is used (see FIELDS.md). Pass [] to return all fields. Pass a custom list to override the default.

List all categories grouped by category group.

Args: plan_id: The plan ID (use list_plans to find available IDs) exclude_fields: Optional list of field names to exclude from each category group. If omitted, the model's default exclude list is used (see FIELDS.md). Pass [] to return all fields. Pass a custom list to override the default.

Get a single category. Amounts are specific to the current plan month (UTC).

Args: category_id: The category ID plan_id: The plan ID (use list_plans to find available IDs) exclude_fields: Optional list of field names to exclude from the response. If omitted, the model's default exclude list is used (see FIELDS.md). Pass [] to return all fields. Pass a custom list to override the default.

Create a new category in a category group.

Args: plan_id: The plan ID (use list_plans to find available IDs) category_group_id: The category group ID to create the category in name: The name of the new category note: Optional note for the category goal_target: Optional goal target amount in dollars. If specified and no goal exists, a monthly 'Needed for Spending' goal will be created. goal_target_date: Optional goal target date in ISO format (e.g. '2026-12-01') exclude_fields: Optional list of field names to exclude from the response. If omitted, the model's default exclude list is used (see FIELDS.md). Pass [] to return all fields. Pass a custom list to override the default.

Update a category. Only provide the fields you want to change.

Args: plan_id: The plan ID (use list_plans to find available IDs) category_id: The category ID to update name: New name for the category note: New note for the category category_group_id: Move category to a different category group goal_target: Goal target amount in dollars. If specified and no goal exists, a monthly 'Needed for Spending' goal will be created. goal_target_date: Goal target date in ISO format (e.g. '2026-12-01') exclude_fields: Optional list of field names to exclude from the response. If omitted, the model's default exclude list is used (see FIELDS.md). Pass [] to return all fields. Pass a custom list to override the default.

Create a new category group.

Args: plan_id: The plan ID (use list_plans to find available IDs) name: The name of the category group (max 50 characters) exclude_fields: Optional list of field names to exclude from the response. If omitted, the model's default exclude list is used (see FIELDS.md). Pass [] to return all fields. Pass a custom list to override the default.

Update a category group.

Args: plan_id: The plan ID (use list_plans to find available IDs) category_group_id: The category group ID to update name: New name for the category group (max 50 characters) exclude_fields: Optional list of field names to exclude from the response. If omitted, the model's default exclude list is used (see FIELDS.md). Pass [] to return all fields. Pass a custom list to override the default.

Get category details for a specific month.

Args: category_id: The category ID month: Month in YYYY-MM-DD format (use first of month, e.g. '2026-03-01') plan_id: The plan ID (use list_plans to find available IDs) exclude_fields: Optional list of field names to exclude from the response. If omitted, the model's default exclude list is used (see FIELDS.md). Pass [] to return all fields. Pass a custom list to override the default.

Update the budgeted amount for a category in a specific month.

Args: category_id: The category ID month: Month in YYYY-MM-DD format (use first of month, e.g. '2026-03-01') budgeted: Budgeted amount in dollars (e.g. 500.00) plan_id: The plan ID (use list_plans to find available IDs) exclude_fields: Optional list of field names to exclude from the response. If omitted, the model's default exclude list is used (see FIELDS.md). Pass [] to return all fields. Pass a custom list to override the default.

List all payees in a plan.

Args: plan_id: The plan ID (use list_plans to find available IDs) exclude_fields: Optional list of field names to exclude from each payee. If omitted, the model's default exclude list is used (see FIELDS.md). Pass [] to return all fields. Pass a custom list to override the default.

Get a single payee.

Args: payee_id: The payee ID plan_id: The plan ID (use list_plans to find available IDs) exclude_fields: Optional list of field names to exclude from the response. If omitted, the model's default exclude list is used (see FIELDS.md). Pass [] to return all fields. Pass a custom list to override the default.

Update a payee.

Args: plan_id: The plan ID (use list_plans to find available IDs) payee_id: The payee ID to update name: New name for the payee (max 500 characters) exclude_fields: Optional list of field names to exclude from the response. If omitted, the model's default exclude list is used (see FIELDS.md). Pass [] to return all fields. Pass a custom list to override the default.

List all payee locations in a plan.

Args: plan_id: The plan ID (use list_plans to find available IDs) exclude_fields: Optional list of field names to exclude from each location. If omitted, the model's default exclude list is used (see FIELDS.md). Pass [] to return all fields. Pass a custom list to override the default.

Get a single payee location.

Args: payee_location_id: The payee location ID plan_id: The plan ID (use list_plans to find available IDs) exclude_fields: Optional list of field names to exclude from the response. If omitted, the model's default exclude list is used (see FIELDS.md). Pass [] to return all fields. Pass a custom list to override the default.

Get all locations for a specific payee.

Args: payee_id: The payee ID plan_id: The plan ID (use list_plans to find available IDs) exclude_fields: Optional list of field names to exclude from each location. If omitted, the model's default exclude list is used (see FIELDS.md). Pass [] to return all fields. Pass a custom list to override the default.

List all money movements in a plan.

Args: plan_id: The plan ID (use list_plans to find available IDs) exclude_fields: Optional list of field names to exclude from each movement. If omitted, the model's default exclude list is used (see FIELDS.md). Pass [] to return all fields. Pass a custom list to override the default.

Get all money movements for a specific month.

Args: month: Month in YYYY-MM-DD format (first of month) or 'current' plan_id: The plan ID (use list_plans to find available IDs) exclude_fields: Optional list of field names to exclude from each movement. If omitted, the model's default exclude list is used (see FIELDS.md). Pass [] to return all fields. Pass a custom list to override the default.

List all money movement groups in a plan.

Args: plan_id: The plan ID (use list_plans to find available IDs) exclude_fields: Optional list of field names to exclude from each group. If omitted, the model's default exclude list is used (see FIELDS.md). Pass [] to return all fields. Pass a custom list to override the default.

Get all money movement groups for a specific month.

Args: month: Month in YYYY-MM-DD format (first of month) or 'current' plan_id: The plan ID (use list_plans to find available IDs) exclude_fields: Optional list of field names to exclude from each group. If omitted, the model's default exclude list is used (see FIELDS.md). Pass [] to return all fields. Pass a custom list to override the default.

List all plan months.

Args: plan_id: The plan ID (use list_plans to find available IDs) exclude_fields: Optional list of field names to exclude from each month. If omitted, the model's default exclude list is used (see FIELDS.md). Pass [] to return all fields. Pass a custom list to override the default.

Get detailed plan month summary including all categories. Use 'current' for the current month.

Args: month: Month in YYYY-MM-DD format (first of month) or 'current' plan_id: The plan ID (use list_plans to find available IDs) exclude_fields: Optional list of field names to exclude from the response. If omitted, the model's default exclude list is used (see FIELDS.md). Pass [] to return all fields. Pass a custom list to override the default.

List all scheduled (recurring) transactions.

Args: plan_id: The plan ID (use list_plans to find available IDs) exclude_fields: Optional list of field names to exclude from each transaction. If omitted, the model's default exclude list is used (see FIELDS.md). Pass [] to return all fields. Pass a custom list to override the default.

Get a single scheduled transaction.

Args: scheduled_transaction_id: The scheduled transaction ID plan_id: The plan ID (use list_plans to find available IDs) exclude_fields: Optional list of field names to exclude from the response. If omitted, the model's default exclude list is used (see FIELDS.md). Pass [] to return all fields. Pass a custom list to override the default.

Create a scheduled transaction (a transaction with a future date).

Splits are not supported on this endpoint. Date must be in the future, no more than 5 years out.

Args: plan_id: The plan ID (use list_plans to find available IDs) account_id: The account ID for this scheduled transaction date: Future date in YYYY-MM-DD format (no more than 5 years out) amount: Amount in dollars (negative for outflow, positive for inflow). e.g. -50.25 for spending $50.25 payee_id: Payee ID (use list_payees to find available IDs). For account transfers, use the target account's transfer_payee_id. payee_name: Payee name. If payee_id is null, this resolves to an existing payee or creates a new one. category_id: Category ID. Credit Card Payment categories are not permitted. memo: Memo/note (max 500 chars) flag_color: 'red', 'orange', 'yellow', 'green', 'blue', 'purple', or null frequency: One of 'never', 'daily', 'weekly', 'everyOtherWeek', 'twiceAMonth', 'every4Weeks', 'monthly', 'everyOtherMonth', 'every3Months', 'every4Months', 'twiceAYear', 'yearly', 'everyOtherYear' exclude_fields: Optional list of field names to exclude from the response. If omitted, the model's default exclude list is used (see FIELDS.md). Pass [] to return all fields. Pass a custom list to override the default.

Update a scheduled transaction.

The API requires account_id and date on every update. Splits are not supported on this endpoint. Date must be in the future, no more than 5 years out.

Args: plan_id: The plan ID (use list_plans to find available IDs) scheduled_transaction_id: The scheduled transaction ID to update account_id: The account ID for this scheduled transaction (required) date: Future date in YYYY-MM-DD format (required, no more than 5 years out) amount: Amount in dollars (negative for outflow, positive for inflow) payee_id: Payee ID. For account transfers, use the target account's transfer_payee_id. payee_name: Payee name (resolves to existing or creates a new payee) category_id: Category ID. Credit Card Payment categories are not permitted. memo: Memo/note (max 500 chars) flag_color: 'red', 'orange', 'yellow', 'green', 'blue', 'purple', or null frequency: One of 'never', 'daily', 'weekly', 'everyOtherWeek', 'twiceAMonth', 'every4Weeks', 'monthly', 'everyOtherMonth', 'every3Months', 'every4Months', 'twiceAYear', 'yearly', 'everyOtherYear' exclude_fields: Optional list of field names to exclude from the response. If omitted, the model's default exclude list is used (see FIELDS.md). Pass [] to return all fields. Pass a custom list to override the default.

Delete a scheduled transaction.

Args: scheduled_transaction_id: The scheduled transaction ID to delete plan_id: The plan ID (use list_plans to find available IDs) exclude_fields: Optional list of field names to exclude from the response. If omitted, the model's default exclude list is used (see FIELDS.md). Pass [] to return all fields. Pass a custom list to override the default.

Build Sankey chart data showing money flow from income sources to spending category groups.

Returns nodes and index-based links suitable for Sankey/flow visualizations.

Args: plan_id: The plan ID (use list_plans to find available IDs) month: Month in YYYY-MM-DD format (first of month, e.g. '2026-03-01') or 'current'

Get per-category spending breakdown for a month, with budget vs actual comparison.

Returns categories sorted by spending (highest first), grouped by category group, with budgeted, spent, balance, and percentage of total spending.

Args: plan_id: The plan ID (use list_plans to find available IDs) month: Month in YYYY-MM-DD format (first of month, e.g. '2026-03-01') or 'current'