NagentArtefacts
Dev & Technology
Enterprise and White Glove
Company
YNAB connects to a Nagent workspace with OAuth sign-in. Once it is connected, agents can call 27 YNAB actions, such as "Create a new account in a budget", "Create Scheduled Transaction" and "Get Account by ID". Nothing is enabled on connect: each action is allowed one at a time, and an action with side effects runs or waits for a person according to the agent's level.
Every operation an agent can call against YNAB, with input parameters and output schema.
YNAB_CREATE_ACCOUNTTool to create a new account in a budget. Use when you need to add a manual (non-linked) account to a specific budget.
Input parameters
The account object to create with name, type, and initial balance
ID of the budget in which to create the account. Use 'default' for the default budget or 'last-used' for the last used budget.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
YNAB_CREATE_SCHEDULED_TRANSACTIONCreates a scheduled (recurring) transaction in a YNAB budget. Use this to set up bills, recurring expenses, or income that repeats on a schedule. Requires an account_id (from YNAB_LIST_ACCOUNTS), a date, frequency, and amount in milliunits.
Input parameters
Budget UUID or literal 'last-used'/'default' to operate on
Scheduled transaction object to create
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
YNAB_DELETE_SCHEDULED_TRANSACTIONPermanently deletes a scheduled transaction from a YNAB budget. Use this when a recurring transaction is no longer needed. This action cannot be undone. Obtain the scheduled_transaction_id from list_scheduled_transactions or get_scheduled_transaction_by_id before calling this.
Input parameters
The budget UUID, or use 'last-used' to target the last used budget, or 'default' when default budget selection is enabled.
The UUID of the scheduled transaction to delete. Obtain this from list_scheduled_transactions or get_scheduled_transaction_by_id.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
YNAB_GET_ACCOUNT_BY_IDTool to retrieve a single account resource. Use when you need details of a specific account by its ID after determining the budget.
Input parameters
Budget identifier; use 'default' if the default budget selection is enabled for your OAuth app.
Account identifier (UUID) within the specified budget.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
YNAB_GET_BUDGET_BY_IDRetrieve a complete budget export by ID, including all accounts, categories, payees, and transactions. Use this tool when you need comprehensive budget data. The response includes: - Budget metadata (name, date/currency formats) - All accounts with balances - Category groups and categories with budgeted amounts and balances - All payees - All transactions and scheduled transactions (optional, may be large) For incremental syncing, use last_knowledge_of_server to only fetch changes since your last request. Note: Currency amounts are in 'milliunits' format (divide by 1000 for standard units).
Input parameters
The ID of the budget to retrieve. Use 'last-used' for the most recently accessed budget, or 'default' if default budget selection is enabled in YNAB settings.
Optional. If provided, returns only entities changed since this server knowledge value (delta request).
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
YNAB_GET_BUDGET_MONTHTool to retrieve a specific budget month. Use when you need detailed summary and category budgets for a given month after confirming the budget ID. Monetary amounts are returned in milliunits (divide by 1000 for standard currency). Response includes high-level aggregates and a nested category array within the month payload for per-category budget analysis.
Input parameters
Budget month in ISO 8601 format (YYYY-MM-01) or 'current' for the current calendar month (UTC).
Budget identifier; if OAuth 'default budget selection' is enabled, you may use 'default'.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
YNAB_GET_BUDGET_SETTINGSTool to retrieve budget-level settings. Use when you need to fetch currency and date formatting preferences for a specific budget.
Input parameters
ID of the budget to fetch settings for. Supports special values like 'last-used' or 'default'.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
YNAB_GET_CATEGORY_BY_IDRetrieve a single YNAB budget category by its ID. Use this to get detailed category information including budgeted amounts, activity, balance, and goal settings. Amounts are returned for the current budget month (UTC). Requires both budget_id and category_id - use 'last-used' or 'default' for budget_id if you don't have a specific budget ID.
Input parameters
The budget ID (UUID format). Use 'last-used' for the most recently accessed budget, or 'default' if default budget selection is enabled.
The unique identifier (UUID) of the category to retrieve.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
YNAB_GET_MONTH_CATEGORY_BY_IDTool to retrieve a single category for a specific budget month. Use after selecting the budget and month when you need month-specific category details.
Input parameters
Budget month in ISO 8601 full-date format (YYYY-MM-DD).
Budget identifier; use 'default' if default budget selection is enabled.
Category identifier (UUID) within the specified budget month.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
YNAB_GET_PAYEE_BY_IDTool to retrieve a single payee by its ID. Use when you need full details of a payee after confirming the budget and payee selection.
Input parameters
The unique identifier (UUID) of the payee to retrieve.
The budget identifier. Can be a UUID, 'default' (if OAuth default budget selection is enabled), or 'last-used' to reference the last accessed budget.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
YNAB_GET_SCHEDULED_TRANSACTION_BY_IDTool to retrieve a single scheduled transaction. Use when you need details of a specific scheduled transaction by its ID after confirming the budget.
Input parameters
The budget UUID or special value: 'last-used' for the last accessed budget, or 'default' if default budget selection is enabled in YNAB settings.
The UUID of the scheduled transaction to retrieve.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
YNAB_GET_TRANSACTION_BY_IDTool to retrieve a single transaction by its ID. Use when you need detailed information for a specific transaction after confirming the budget.
Input parameters
The budget ID. Use 'default' to reference the default budget when OAuth default budget selection is enabled, or 'last-used' for the last accessed budget.
The UUID of the transaction to retrieve.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
YNAB_GET_USERTool to retrieve the authorized user's information. Use after authentication to get current user details.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
YNAB_LIST_ACCOUNTSRetrieves all accounts for a specified YNAB budget. Use this tool to: - Get a complete list of accounts (checking, savings, credit cards, loans, etc.) in a budget - Retrieve account IDs for use with other YNAB account-related operations - Monitor account balances (current, cleared, and uncleared) - Perform efficient delta syncing by passing last_knowledge_of_server Returns account details including balances in milliunits (1000 milliunits = 1 currency unit). For example, a balance of 150000 milliunits equals $150.00. Note: Use 'default' or 'last-used' as budget_id for convenience, or obtain specific budget UUIDs from the List Budgets endpoint.
Input parameters
The budget UUID or special value. Use 'default' for the user's default budget, or 'last-used' for the most recently accessed budget. Alternatively, provide a specific budget UUID obtained from the List Budgets endpoint.
If provided, only entities that have changed since this server knowledge value will be included in the response (delta request). Obtain this value from a previous response's server_knowledge field for efficient syncing.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
YNAB_LIST_BUDGETSRetrieves all budgets accessible to the authenticated YNAB user. Use this tool to: - Get a list of all budgets in the user's YNAB account - Retrieve budget IDs for use with other YNAB operations - Optionally include account details for each budget Returns budget summaries including name, last modification time, date range, and formatting preferences. Budget IDs from this response are required for most other YNAB API operations.
Input parameters
If True, includes the list of accounts for each budget in the response.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
YNAB_LIST_CATEGORIESTool to list all category groups and their categories for a budget. Use when you need the full set of budget categories or only those changed since last sync. Category names may include emojis or near-identical labels; always use category_id from the response in downstream requests.
Input parameters
Budget identifier; use 'default' if the default budget selection is enabled for your OAuth app.
For delta syncing: only return categories changed since this server knowledge. Response will include an updated server_knowledge.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
YNAB_LIST_MONTHSTool to list months for a budget with summary information. Use when you need an overview of all months or only changed months since a given knowledge value (delta requests).
Input parameters
The budget UUID to list months for. Use 'last-used' to specify the last accessed budget, or 'default' if default budget selection is enabled in the OAuth application settings.
Server knowledge value from a previous response. When provided, only months that have changed since this value will be returned (delta request). Omit for a full list of months.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
YNAB_LIST_PAYEE_LOCATIONSRetrieves all GPS locations associated with payees in a budget. Payee locations are recorded when transactions are saved using the YNAB mobile apps, storing GPS coordinates to help pre-populate nearby payees. Use this tool when you need to find all recorded locations for payees in a budget. Note: Not all payees will have locations recorded.
Input parameters
The ID of the budget (UUID format). Use 'last-used' to specify the last used budget, or 'default' if default budget selection is enabled in your YNAB account settings.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
YNAB_LIST_PAYEE_LOCATIONS_BY_PAYEERetrieves all GPS locations associated with a specific payee in a budget. Payee locations are recorded when transactions are saved using the YNAB mobile apps, storing GPS coordinates to help pre-populate nearby payees. Use this tool when you need to find where a payee's transactions typically occur. Note: Not all payees will have locations recorded.
Input parameters
The unique identifier (UUID) of the payee to retrieve locations for.
The ID of the budget (UUID format). Use 'last-used' to specify the last used budget, or 'default' if default budget selection is enabled in your YNAB account settings.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
YNAB_LIST_PAYEESTool to list payees in a budget. Use when you need all payees or only those changed since a known server knowledge value.
Input parameters
Budget identifier (UUID). Use 'last-used' to refer to the last accessed budget or 'default' if OAuth default budget selection is enabled.
Only return entities changed since this server knowledge value (delta requests).
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
YNAB_LIST_SCHEDULED_TRANSACTIONSList all scheduled (recurring) transactions for a YNAB budget. Returns future-dated transactions that repeat on a schedule (e.g., rent, subscriptions, paychecks). Supports delta sync to fetch only changes since a previous request using the server_knowledge value.
Input parameters
The budget ID. Use 'last-used' to get the last used budget, or 'default' if default budget selection is enabled. Otherwise, provide the actual budget UUID.
Server knowledge value for delta sync. When provided, only scheduled transactions changed since this value are returned. Use the server_knowledge value from a previous response.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
YNAB_LIST_TRANSACTIONSTool to list transactions in a budget. Use when you need all or delta-filtered transactions after confirming the budget. Omitting all filters returns the full transaction history, which may produce large payloads; prefer since_date, type, or last_knowledge_of_server to scope results.
Input parameters
Filter by transaction type; supported values: 'uncategorized', 'unapproved'.
Budget identifier (UUID). Use 'default' if default budget selection is enabled, or 'last-used' to specify the last used budget.
Only include transactions on or after this ISO date (YYYY-MM-DD).
Optional. If provided, returns only entities changed since this server knowledge value (delta request).
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
YNAB_LIST_TRANSACTIONS_BY_ACCOUNTTool to list transactions for a specific account. Use when you need all or delta-filtered transactions for a given account after confirming the budget and account ID.
Input parameters
If specified, only transactions of the specified type will be included. Use 'uncategorized' to get transactions without a category, or 'unapproved' to get transactions that have not been approved.
The ID of the budget. Use 'default' if default budget selection is enabled, or 'last-used' to specify the last used budget.
The ID of the account to retrieve transactions from (UUID format).
If specified, only transactions on or after this date will be included. The date should be ISO formatted (e.g., '2024-01-01').
The starting server knowledge value. If provided, only entities that have changed since this value will be included (delta request). Useful for syncing.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
YNAB_LIST_TRANSACTIONS_BY_CATEGORYTool to list transactions for a specific category (excludes pending). Use when you need completed transactions for a given category after obtaining budget_id and category_id. Response includes deleted transactions; filter client-side using the deleted boolean field.
Input parameters
Filter by transaction type; supported values: 'uncategorized', 'unapproved'.
Budget identifier (UUID). Use 'default' if default budget selection is enabled, or 'last-used' to specify the last used budget.
Only include transactions on or after this ISO date (YYYY-MM-DD). No upper-bound parameter exists; apply client-side filtering for bounded date ranges.
Category identifier whose transactions are to be retrieved. Confirm the exact UUID before fetching; category names may be ambiguous due to similar labels or emoji.
Delta-style filter; only return entities changed since this server knowledge index.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
YNAB_LIST_TRANSACTIONS_BY_PAYEETool to list transactions for a specific payee in a budget. Use when you need to fetch all non-pending transactions for a payee after confirming budget and payee IDs.
Input parameters
Optional filter by transaction type: 'uncategorized' or 'unapproved'.
Payee identifier to filter transactions.
Budget identifier; use 'default' for the default budget if enabled for your OAuth app.
Optional ISO date (YYYY-MM-DD). Only include transactions on or after this date.
Optional. If provided, returns only entities changed since this server knowledge value (delta request).
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
YNAB_UPDATE_PAYEETool to update a payee. Use when you need to rename an existing payee.
Input parameters
The new name for the payee.
The unique identifier (UUID) of the payee to update.
Budget identifier. Use 'default' if OAuth default budget selection is enabled.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
YNAB_UPDATE_SCHEDULED_TRANSACTIONUpdate an existing scheduled transaction in YNAB. Allows modifying the date, frequency, amount, payee, category, memo, or account of a scheduled transaction. Use YNAB_LIST_SCHEDULED_TRANSACTIONS first to get the scheduled_transaction_id. Amounts should be in milliunits (negative for expenses, positive for income).
Input parameters
Budget UUID or literal 'last-used'/'default' to operate on
Fields of the scheduled transaction to update
Identifier of the scheduled transaction to update
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
Agents can call 27 YNAB actions on Nagent, including "Create a new account in a budget", "Create Scheduled Transaction" and "Get Account by ID". Create a new account in a budget: Create a new account in a budget. Each action is listed on this page with its input parameters and its output.
YNAB connects with OAuth sign-in, under your workspace's own connection. Nothing is enabled on connect: each action is allowed one at a time and can be scoped to the agents that need it.
Create a new account in a budget takes 2 required inputs: account and budget_id. It returns data, error and successful.