@mind-your-now/myn 0.8.1 → 0.8.3

package/skills/myn/references/ynab-api.md

@@ -0,0 +1,323 @@
+# YNAB API
+
+YNAB (You Need A Budget) integration for budget management, transactions, scheduled transactions, analytics, and category management.
+
+## Base Path
+
+`/api/v1/ynab`
+
+## Endpoints
+
+### Budget & Accounts
+
+#### Budget Overview
+
+```
+GET /api/v1/ynab/budget/overview
+```
+
+Returns the overall budget summary including ready-to-assign amount, total income, total budgeted, and total activity.
+
+#### List Categories
+
+```
+GET /api/v1/ynab/budget/categories
+```
+
+Returns all category groups and their categories with balances, budgeted amounts, and goal information.
+
+#### Category Balance (Search)
+
+```
+GET /api/v1/ynab/budget/categories/search?query={categoryName}
+```
+
+Fuzzy-searches for a category by name and returns its balance and details.
+
+#### Account Balances
+
+```
+GET /api/v1/ynab/budget/accounts
+```
+
+Returns all accounts grouped by type (checking, savings, creditCards, loans) with balances and transfer payee IDs.
+
+#### Set Budget Amount
+
+```
+PATCH /api/v1/ynab/budget/categories/{categoryId}/budget
+```
+
+**Body:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `budgetedDollars` | number | Amount in dollars to budget for the category |
+| `month` | string | Budget month in YYYY-MM format (defaults to current month) |
+
+#### Set Category Goal
+
+```
+PATCH /api/v1/ynab/budget/categories/{categoryId}/goal
+```
+
+**Body:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `goalType` | string | Goal type: `TB`, `TBD`, `MF`, `NEED` |
+| `goalTargetDollars` | number | Goal target in dollars |
+| `goalTargetMonth` | string | Target month YYYY-MM (for TBD goals, appends `-01` automatically) |
+
+#### Goal Progress
+
+```
+GET /api/v1/ynab/budget/categories
+```
+
+Same as list_categories; goal progress fields are included in category data.
+
+#### Budget Months
+
+```
+GET /api/v1/ynab/budget/months
+```
+
+Returns available budget months with summary data.
+
+#### Search Payees
+
+```
+GET /api/v1/ynab/budget/payees/search?query={payeeName}
+GET /api/v1/ynab/budget/payees
+```
+
+Search for payees by name (fuzzy match), or list all payees if no query is provided.
+
+### Transactions
+
+#### Create Transaction
+
+```
+POST /api/v1/ynab/transactions
+```
+
+**Body:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `accountId` | string | **Required.** YNAB account ID |
+| `amountMilliunits` | number | **Required.** Amount in milliunits (dollars * 1000, negative for expenses) |
+| `date` | string | **Required.** Date YYYY-MM-DD (defaults to today) |
+| `payeeName` | string | Payee name (required if no payeeId) |
+| `payeeId` | string | Payee ID (for transfers, use target account's transferPayeeId) |
+| `categoryId` | string | Category ID (resolved from categoryName by the tool) |
+| `memo` | string | Optional memo |
+| `cleared` | string | `cleared`, `uncleared`, or `reconciled` |
+
+The tool automatically performs duplicate detection by checking for existing transactions with the same amount and date.
+
+#### Create Transactions Bulk
+
+```
+POST /api/v1/ynab/transactions/bulk
+```
+
+**Body:** `{ transactions: [{ accountId, payeeName, amount, date, categoryId, memo? }] }`
+
+Amounts are in milliunits. Bypasses the single-transaction duplicate check.
+
+#### List Transactions
+
+```
+GET /api/v1/ynab/transactions
+GET /api/v1/ynab/transactions?sinceDate={YYYY-MM-DD}
+```
+
+Returns transactions, optionally filtered by date.
+
+#### Update Transaction
+
+```
+PUT /api/v1/ynab/transactions/{transactionId}
+```
+
+**Body:** Any combination of `accountId`, `payeeName`, `payeeId`, `amountMilliunits`, `date`, `memo`, `cleared`, `flagColor`, `categoryId`.
+
+#### Delete Transaction
+
+```
+DELETE /api/v1/ynab/transactions/{transactionId}
+```
+
+#### Split Transaction
+
+```
+PUT /api/v1/ynab/transactions/{transactionId}
+```
+
+Updates a transaction with `subtransactions` to split it across multiple categories. The tool validates that split amounts sum to the original transaction amount.
+
+**Body:** `{ subtransactions: [{ amount, categoryId, memo? }] }`
+
+### Scheduled Transactions & Subscriptions
+
+#### List Scheduled Transactions
+
+```
+GET /api/v1/ynab/scheduled-transactions
+```
+
+#### Create Scheduled Transaction
+
+```
+POST /api/v1/ynab/scheduled-transactions
+```
+
+**Body:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `accountId` | string | **Required.** YNAB account ID |
+| `payeeName` | string | **Required.** Payee name |
+| `amountMilliunits` | number | **Required.** Amount in milliunits |
+| `dateFirst` | string | **Required.** First occurrence date YYYY-MM-DD |
+| `dateNext` | string | Next occurrence date (defaults to dateFirst) |
+| `frequency` | string | **Required.** Recurrence: `never`, `daily`, `weekly`, `everyOtherWeek`, `twiceAMonth`, `every4Weeks`, `monthly`, `everyOtherMonth`, `every3Months`, `every4Months`, `twiceAYear`, `yearly`, `everyOtherYear` |
+| `categoryId` | string | Category ID |
+| `memo` | string | Optional memo |
+
+#### Update Scheduled Transaction
+
+```
+PUT /api/v1/ynab/scheduled-transactions/{transactionId}
+```
+
+**Body:** Any combination of `payeeName`, `amountMilliunits`, `dateNext`, `frequency`, `memo`, `categoryId`.
+
+#### Delete Scheduled Transaction
+
+```
+DELETE /api/v1/ynab/scheduled-transactions/{transactionId}
+```
+
+#### Subscriptions View
+
+```
+GET /api/v1/ynab/subscriptions
+```
+
+Returns a view of recurring scheduled transactions categorized as subscriptions.
+
+#### Upcoming Bills
+
+```
+GET /api/v1/ynab/scheduled?days={days}
+```
+
+Returns scheduled transactions due within the specified number of days (default: 7).
+
+### Analytics
+
+#### Spending Insights
+
+```
+GET /api/v1/ynab/analytics/spending?months={months}&category={categoryName}
+```
+
+Returns spending breakdown by category. Optional category filter for drilling into a specific category.
+
+#### Payee Analysis
+
+```
+GET /api/v1/ynab/analytics/payees?months={months}
+```
+
+Returns spending analysis by payee.
+
+#### Spending Trends
+
+```
+GET /api/v1/ynab/analytics/trends?months={months}
+```
+
+Returns month-over-month spending trends.
+
+#### Net Worth
+
+```
+GET /api/v1/ynab/analytics/net-worth
+```
+
+Returns net worth calculation across all accounts.
+
+#### Debt Tracking
+
+```
+GET /api/v1/ynab/analytics/debt
+```
+
+Returns debt tracking information for loan and credit card accounts.
+
+### Category Management
+
+#### Create Category Group
+
+```
+POST /api/v1/ynab/budget/category-groups
+```
+
+**Body:** `{ name: "Group Name" }`
+
+#### Create Category
+
+```
+POST /api/v1/ynab/budget/categories
+```
+
+**Body:** `{ name: "Category Name", categoryGroupId: "group-id", note?: "optional note" }`
+
+The `categoryGroupId` can be resolved from `groupName` by fuzzy match against existing groups.
+
+#### Rename Category
+
+```
+PATCH /api/v1/ynab/budget/categories/{categoryId}/details
+```
+
+**Body:** `{ name: "New Name" }`
+
+#### Move Category
+
+```
+PATCH /api/v1/ynab/budget/categories/{categoryId}/details
+```
+
+**Body:** `{ categoryGroupId: "target-group-id" }`
+
+Moves a category to a different category group.
+
+#### Rename Category Group
+
+```
+PATCH /api/v1/ynab/budget/category-groups/{groupId}
+```
+
+**Body:** `{ name: "New Group Name" }`
+
+### Connection
+
+#### Connection Status
+
+```
+GET /api/v1/ynab/status
+```
+
+Returns YNAB connection status.
+
+## Notes
+
+- All monetary amounts from the YNAB API are in milliunits (divide by 1000 for dollars). The tool automatically converts these to formatted dollar strings in responses.
+- The tool accepts amounts in dollars (e.g., `-45.50` for a $45.50 expense) and converts them to milliunits internally.
+- Category names are resolved via fuzzy search against existing categories. Always use `list_categories` first to find the correct name.
+- `categoryName` is required for all non-transfer transactions to prevent uncategorized entries in YNAB.