Models

Pydantic models and TypedDicts for YNAB API response shapes. Base models use extra="ignore" so additional fields returned by the YNAB API do not cause validation errors. TypedDicts provide lightweight structural types for raw API response dicts where key-access patterns need type safety.

---

models

Pydantic models and TypedDicts for YNAB API responses.

Base models for validating and typing YNAB API response data. All models use extra="ignore" so that additional fields returned by the YNAB API do not cause validation errors.

TypedDicts provide lightweight structural types for raw API response dicts where key-access patterns need type safety under pyright strict mode, without the overhead of Pydantic validation.

AccountsResponseData

Bases: TypedDict

Shape of data from GET /budgets/{id}/accounts.

AccountResponseData

Bases: TypedDict

Shape of data from GET /budgets/{id}/accounts/{id}.

TransactionsResponseData

Bases: TypedDict

Shape of data from GET /budgets/{id}/transactions.

TransactionResponseData

Bases: TypedDict

Shape of data from GET /budgets/{id}/transactions/{id}.

CategoriesResponseData

Bases: TypedDict

Shape of data from GET /budgets/{id}/categories.

CategoryResponseData

Bases: TypedDict

Shape of data from GET /budgets/{id}/categories/{id}.

PayeesResponseData

Bases: TypedDict

Shape of data from GET /budgets/{id}/payees.

PayeeResponseData

Bases: TypedDict

Shape of data from GET /budgets/{id}/payees/{id}.

PayeeLocationsResponseData

Bases: TypedDict

Shape of data from GET /budgets/{id}/payee_locations.

PayeeLocationResponseData

Bases: TypedDict

Shape of data from GET /budgets/{id}/payee_locations/{id}.

MonthsResponseData

Bases: TypedDict

Shape of data from GET /budgets/{id}/months.

MonthResponseData

Bases: TypedDict

Shape of data from GET /budgets/{id}/months/{month}.

MoneyMovementsResponseData

Bases: TypedDict

Shape of data from GET .../money_movements.

MoneyMovementGroupsResponseData

Bases: TypedDict

Shape of data from GET .../money_movement_groups.

ScheduledTransactionsResponseData

Bases: TypedDict

Shape of data from GET /budgets/{id}/scheduled_transactions.

ScheduledTransactionResponseData

Bases: TypedDict

Shape of data from GET /budgets/{id}/scheduled_transactions/{id}.

BudgetResponseData

Bases: TypedDict

Shape of data from GET /budgets/{id}.

SettingsResponseData

Bases: TypedDict

Shape of data from GET /budgets/{id}/settings.

UserResponseData

Bases: TypedDict

Shape of data from GET /user.

BudgetsResponseData

Bases: TypedDict

Shape of data from GET /budgets.

CategoryGroupResponseData

Bases: TypedDict

Shape of data from POST/PATCH category groups.

BatchTransactionResponseData

Bases: TypedDict

Shape of data from batch transaction create/update.

ErrorDetail

Bases: BaseModel

A single YNAB API error detail.

Attributes:

• id (str) –

  YNAB error identifier (e.g., "404.2").

• name (str) –

  Error name (e.g., "resource_not_found").

• detail (str) –

  Human-readable error description.

ErrorResponse

Bases: BaseModel

Top-level YNAB API error response wrapper.

Attributes:

• error (ErrorDetail) –

  The error detail object.

BudgetSummary

Bases: BaseModel

Summary of a single YNAB budget.

Attributes:

• id (str) –

  Budget UUID.

• name (str) –

  Budget display name.

• last_modified_on (str) –

  ISO 8601 timestamp of last modification.

• first_month (str) –

  First month in the budget (YYYY-MM-DD).

• last_month (str) –

  Last month in the budget (YYYY-MM-DD).

BudgetsResponse

Bases: BaseModel

Response wrapper for the GET /budgets endpoint.

Attributes:

• budgets (list[BudgetSummary]) –

  List of budget summaries.

Account

Bases: BaseModel

A YNAB account.

Attributes:

• id (str) –

  Account UUID.

• name (str) –

  Account display name.

• type (str) –

  Account type (checking, savings, etc.).

• on_budget (bool) –

  Whether account is on-budget.

• closed (bool) –

  Whether account is closed.

• balance (float) –

  Current balance in dollars (converted from milliunits).

• cleared_balance (float) –

  Cleared balance in dollars.

• uncleared_balance (float) –

  Uncleared balance in dollars.

• note (str | None) –

  Optional account note.

• transfer_payee_id (str | None) –

  Payee ID for transfers to this account.

• deleted (bool) –

  Whether account is deleted.

Category

Bases: BaseModel

A YNAB budget category.

Attributes:

• id (str) –

  Category UUID.

• category_group_id (str) –

  Parent category group UUID.

• category_group_name (str | None) –

  Parent category group name.

• name (str) –

  Category display name.

• hidden (bool) –

  Whether category is hidden.

• budgeted (float) –

  Budgeted amount in dollars.

• activity (float) –

  Activity amount in dollars.

• balance (float) –

  Balance in dollars.

• deleted (bool) –

  Whether category is deleted.

• note (str | None) –

  Optional category note.

• goal_type (str | None) –

  Goal type (TB, TBD, MF, NEED, DEBT).

• goal_target (float | None) –

  Goal target amount in dollars.

• goal_target_month (str | None) –

  Goal target month (YYYY-MM-DD).

• goal_percentage_complete (int | None) –

  Goal completion percentage.

• goal_months_to_budget (int | None) –

  Months remaining to reach goal.

• goal_under_funded (float | None) –

  Amount under-funded in dollars.

• goal_overall_funded (float | None) –

  Total funded toward goal in dollars.

• goal_overall_left (float | None) –

  Amount remaining for goal in dollars.

CategoryGroup

Bases: BaseModel

A YNAB category group.

Attributes:

• id (str) –

  Category group UUID.

• name (str) –

  Category group display name.

• hidden (bool) –

  Whether category group is hidden.

• deleted (bool) –

  Whether category group is deleted.

CategoryGroupWithCategories

Bases: CategoryGroup

A category group with its child categories.

Attributes:

• categories (list[Category]) –

  List of categories in this group.

SubTransaction

Bases: BaseModel

A YNAB sub-transaction (split transaction component).

Attributes:

• id (str) –

  Sub-transaction UUID.

• transaction_id (str) –

  Parent transaction UUID.

• amount (float) –

  Amount in dollars (converted from milliunits).

• deleted (bool) –

  Whether sub-transaction is deleted.

• payee_id (str | None) –

  Payee UUID.

• payee_name (str | None) –

  Payee display name.

• category_id (str | None) –

  Category UUID.

• category_name (str | None) –

  Category display name.

• memo (str | None) –

  Optional memo text.

• transfer_account_id (str | None) –

  Account UUID if this is a transfer.

• transfer_transaction_id (str | None) –

  Matching transfer transaction UUID.

TransactionDetail

Bases: BaseModel

A detailed YNAB transaction.

Attributes:

• id (str) –

  Transaction UUID.

• date (str) –

  Transaction date (YYYY-MM-DD).

• amount (float) –

  Amount in dollars (converted from milliunits).

• account_id (str) –

  Account UUID.

• account_name (str) –

  Account display name.

• approved (bool) –

  Whether transaction is approved.

• cleared (str) –

  Cleared status (cleared, uncleared, reconciled).

• deleted (bool) –

  Whether transaction is deleted.

• memo (str | None) –

  Optional memo text.

• payee_id (str | None) –

  Payee UUID.

• payee_name (str | None) –

  Payee display name.

• category_id (str | None) –

  Category UUID.

• category_name (str | None) –

  Category display name.

• transfer_account_id (str | None) –

  Account UUID if this is a transfer.

• transfer_transaction_id (str | None) –

  Matching transfer transaction UUID.

• matched_transaction_id (str | None) –

  Matched imported transaction UUID.

• import_id (str | None) –

  Import identifier for deduplication.

• import_payee_name (str | None) –

  Payee name from import source.

• import_payee_name_original (str | None) –

  Original payee name from import source.

• flag_color (str | None) –

  Transaction flag color.

• flag_name (str | None) –

  Transaction flag name.

• debt_transaction_type (str | None) –

  Debt transaction type (payment, etc.).

• subtransactions (list[SubTransaction]) –

  List of sub-transactions (splits).

ScheduledSubTransaction

Bases: BaseModel

A YNAB scheduled sub-transaction (split component).

Attributes:

• id (str) –

  Sub-transaction UUID.

• scheduled_transaction_id (str) –

  Parent scheduled transaction UUID.

• amount (float) –

  Amount in dollars (converted from milliunits).

• deleted (bool) –

  Whether sub-transaction is deleted.

• payee_id (str | None) –

  Payee UUID.

• payee_name (str | None) –

  Payee display name.

• category_id (str | None) –

  Category UUID.

• category_name (str | None) –

  Category display name.

• memo (str | None) –

  Optional memo text.

• transfer_account_id (str | None) –

  Account UUID if this is a transfer.

ScheduledTransactionDetail

Bases: BaseModel

A detailed YNAB scheduled transaction.

Attributes:

• id (str) –

  Scheduled transaction UUID.

• date_first (str) –

  First occurrence date (YYYY-MM-DD).

• date_next (str | None) –

  Next occurrence date (YYYY-MM-DD), None if completed.

• frequency (str) –

  Recurrence frequency (never, daily, weekly, etc.).

• amount (float) –

  Amount in dollars (converted from milliunits).

• account_id (str) –

  Account UUID.

• account_name (str) –

  Account display name.

• deleted (bool) –

  Whether scheduled transaction is deleted.

• payee_id (str | None) –

  Payee UUID.

• payee_name (str | None) –

  Payee display name.

• category_id (str | None) –

  Category UUID.

• category_name (str | None) –

  Category display name.

• memo (str | None) –

  Optional memo text.

• flag_color (str | None) –

  Flag color for the scheduled transaction.

• flag_name (str | None) –

  Flag name for the scheduled transaction.

• transfer_account_id (str | None) –

  Account UUID if this is a transfer.

• subtransactions (list[ScheduledSubTransaction]) –

  List of scheduled sub-transactions (splits).

Payee

Bases: BaseModel

A YNAB payee.

Attributes:

• id (str) –

  Payee UUID.

• name (str) –

  Payee display name.

• transfer_account_id (str | None) –

  Account UUID if this is a transfer payee.

• deleted (bool) –

  Whether payee is deleted.

PayeeLocation

Bases: BaseModel

A YNAB payee location (GPS data from mobile apps).

Attributes:

• id (str) –

  Payee location UUID.

• payee_id (str) –

  Parent payee UUID.

• latitude (float | None) –

  GPS latitude, or None if not set.

• longitude (float | None) –

  GPS longitude, or None if not set.

• deleted (bool) –

  Whether payee location is deleted.

MonthSummary

Bases: BaseModel

A YNAB budget month summary.

Attributes:

• month (str) –

  Month date string (YYYY-MM-DD).

• income (float) –

  Total income in dollars.

• budgeted (float) –

  Total budgeted in dollars.

• activity (float) –

  Total activity in dollars.

• to_be_budgeted (float) –

  Amount available to budget in dollars.

• age_of_money (int | None) –

  Age of money in days, or None.

• deleted (bool) –

  Whether month is deleted.

MonthDetail

Bases: BaseModel

A YNAB budget month with category breakdown.

Attributes:

• month (str) –

  Month date string (YYYY-MM-DD).

• income (float) –

  Total income in dollars.

• budgeted (float) –

  Total budgeted in dollars.

• activity (float) –

  Total activity in dollars.

• to_be_budgeted (float) –

  Amount available to budget in dollars.

• age_of_money (int | None) –

  Age of money in days, or None.

• categories (list[Category]) –

  List of categories for this month.

MoneyMovement

Bases: BaseModel

A YNAB money movement entry (per-category).

Attributes:

• category_name (str) –

  Category display name.

• category_group_name (str | None) –

  Category group name, or None.

• allocation (float) –

  Allocation amount in dollars.

• spent (float) –

  Spent amount in dollars.

• income (float) –

  Income amount in dollars.

MoneyMovementGroup

Bases: BaseModel

A YNAB money movement group entry (per-category-group).

Attributes:

• category_group_name (str) –

  Category group display name.

• allocation (float) –

  Allocation amount in dollars.

• spent (float) –

  Spent amount in dollars.

• income (float) –

  Income amount in dollars.

UserResponse

Bases: BaseModel

Response for the GET /user endpoint.

Attributes:

• id (str) –

  User UUID.