@lunch-money/v2-api-spec 2.11.0-preview.2 → 2.11.0-preview.20

package/lunch-money-api-v2.yaml

@@ -2,50 +2,40 @@ openapi: 3.0.2
 info:
   title: Lunch Money API - v2
   description: |-
-    Welcome to the documentation for the "next version" of the Lunch Money v2 API.This documentation includes proposed updates to the API design that have not yet been released.<p>
-    This documentation is for the **v2.11.0** release of the API.<p>
-    
-    See the [version history](https://lm-v2-api-next-a7fabcab8e9a.herokuapp.com/v2/version-history) for what is new in this release.
-    New functionality may only be available in the Mock Service until the release is finalized. <br><br>
-
-    The latest complete implementation of the spec is for the **v2.8.5** release and can be found [here](https://lm-v2-api-next-a7fabcab8e9a.herokuapp.com/v2/). <br><br>
-    Feedback on any of the API design is welcome, but we are particularly interested in getting feedback on most recent changes in the [version history](https://lm-v2-api-next-a7fabcab8e9a.herokuapp.com/v2/version-history).
-
-    ------------------------------------------------------------------------------------------------
-    Welcome to the Lunch Money v2 API.
+    ### Introduction
 
-    A working version of this API is now available through these docs, or directly at:
+    Welcome to the Lunch Money v2 API reference. This is the **v2.11.0** spec.
 
-    `https://api.lunchmoney.dev/v2`
+    The API is available at `https://api.lunchmoney.dev/v2`. Get your access token from the [Lunch Money developers page](https://my.lunchmoney.app/developers).
 
-    <span class="red-text"><strong>This is in alpha launch of a major API update. It is still subject to change during this alpha review 
-    period and bugs may still exist. We strongly encourage users to use the mock service or create a test budget with sample data as the first step to interacting with the v2 API.</strong></span>
-    See the [Getting Started Guide](https://lm-v2-api-next-a7fabcab8e9a.herokuapp.com/v2/getting-started) for more information on using a test budget.<p>
+    
+    **Try it from these docs**
 
-    If you are new to the v2 API, you may wish to review the [v2 API Overview of Changes](https://lm-v2-api-next-a7fabcab8e9a.herokuapp.com/v2/changelog).
+    These docs are interactive — use **Test request** on any endpoint to call the API from this page.
+    Choose a LIVE or MOCK service from the Server dropdown.
+    Requests sent to `https://api.lunchmoney.dev/v2` can <span class="red-text"><strong>change or delete</strong></span> your data and are <span class="red-text"><strong>permanent</strong></span>.
+    See the [Getting Started Guide](https://lunchmoney.dev/v2/getting-started) before using the live API.
+    
+    **Static mock server**
 
-    ### Static Mock Server
+    Explore without risk to real data. Select `http://mock.lunchmoney.dev/v2` in the Server dropdown to work with static mock data.
+    POST, PUT, and DELETE requests will return realistic responses, but do not change the mock data.
+    
 
-    You may also use these docs to explore the API using a static mock server endpoint.<p> 
-    This will allow you to become familiar with the API without having to create an access token, and eliminates the possibility of changing real data. <p>
-    To access this endpoint, select the second endpoint in the "Server" dropdown to the right. When selected, you should see "Static Mock v2 Lunch Money API Server".<br>
-    When using this server, set your Bearer token to any string with 11 or more characters.
+    **Client Libraries & SDKs**
 
-    ### Migrating from V1
+    An official TypeScript SDK is available on [NPM](https://www.npmjs.com/package/@lunch-money/v2-api-spec) and [GitHub](https://github.com/lunch-money/lunch-money-js-v2). For Python or other languages, see [lunchmoney-clients](https://github.com/juftin/lunchmoney-clients) or generate a client from [this OpenAPI spec](/v2/openapi).
 
-    The v2 API is NOT backwards compatible with the v1 API. We encourage developers to review the [Migration Guide](https://lm-v2-api-next-a7fabcab8e9a.herokuapp.com/v2/migration-guide) to understand the changes and plan their migration.
+    **Migrating from v1**
 
-    ### Acknowledgments
+    The v2 API is not backwards compatible with v1. See the [Migration Guide](https://lunchmoney.dev/v2/migration-guide) for details.
 
-    If you have provided feedback on the API during our ongoing design process, **THANK YOU**. We are thrilled that you can finally interact with the working API we built based on your feedback.
-    
-    ### Useful links:
-    - [Getting Started](https://lm-v2-api-next-a7fabcab8e9a.herokuapp.com/v2/getting-started)
-    - [v2 API Changelog](https://lm-v2-api-next-a7fabcab8e9a.herokuapp.com/v2/changelog)
-    - [Migration Guide](https://lm-v2-api-next-a7fabcab8e9a.herokuapp.com/v2/migration-guide)
-    - [Rate Limits](https://lm-v2-api-next-a7fabcab8e9a.herokuapp.com/v2/rate-limits)
-    - [Current v1 Lunch Money API Documentation](https://lunchmoney.dev)
-    - [Awesome Lunch Money Projects](https://github.com/lunch-money/awesome-lunchmoney?tab=readme-ov-file)
+    **Useful links**
+    - [Getting Started Guide](https://lunchmoney.dev/v2/getting-started)
+    - [v2 API Overview](https://lunchmoney.dev/v2/overview)
+    - [Version History](https://lunchmoney.dev/v2/version-history)
+    - [Migration Guide](https://lunchmoney.dev/v2/migration-guide)
+    - [Rate Limits](https://lunchmoney.dev/v2/rate-limits)
   termsOfService: https://lunchmoney.dev/#current-status
   contact:
     email: devsupport@lunchmoney.app
@@ -56,10 +46,9 @@ info:
 
 servers:
   - url: https://api.lunchmoney.dev/v2
-    description: v2 Lunch Money API Server - changes will affect real data!
-#  - url: https://mock.lunchmoney.dev/v2
-  - url: https://lm-v2-api-next-a7fabcab8e9a.herokuapp.com/v2/
-    description: Static mock version of the v2 Lunch Money API Server
+    description: ⚠ LIVE — changes real Lunch Money data
+  - url: http://mock.lunchmoney.dev/v2
+    description: MOCK — static demo data, no API key required
 
 tags:
   - name: me
@@ -90,7 +79,11 @@ tags:
       description: Learn more about crypto assets
       url: https://support.lunchmoney.app/setup/crypto
   - name: balance_history
-    description: View and update historical account balances. Balance history is what drives the [Net Worth](https://my.lunchmoney.app/net-worth) views in the Lunch Money app. Balance history is generated for each account's balance on the first day of each month and can be edited in the Lunch Money app or via the API.
+    description: >-
+      View and update monthly account balances used by the
+      [Net Worth](https://my.lunchmoney.app/net-worth) views in the Lunch Money app.
+      History is monthly. The current month may be calculated on demand when
+      requested.
   - name: recurring_items
     description: Work with recurring items
     externalDocs:
@@ -126,8 +119,10 @@ tags:
       description: Learn more about transactions
       url: https://support.lunchmoney.app/finances/transactions
   - name: budgets
-    description: View settings and modify budget amounts.<p> Use the
-      [/summary](#tag/summary) endpoint to view the budget details performance.
+    description: View settings and modify budget amounts.<p> Use
+      [/budgets/settings](#tag/budgets/GET/budgets/settings) to view budget
+      period settings.<p> Use the [/summary](#tag/summary) endpoint to view
+      the budget details performance.
     externalDocs:
       description: Learn more about budgets
       url: https://support.lunchmoney.app/finances/budgets
@@ -155,12 +150,12 @@ components:
         account_id:
           type: integer
           format: int64
-          description: Unique ID for the linked budgeting account
+          description: Unique ID for the current budgeting account
         budget_name:
           type: string
-          description: Name of the linked budgeting account
+          description: Name of the current budgeting account
         primary_currency:
-          description: Primary currency set in the user's settings
+          description: Primary currency for the current budgeting account
           allOf:
             - $ref: "#/components/schemas/currencyEnum"
         api_key_label:
@@ -679,7 +674,6 @@ components:
     cryptoManualObject:
       type: object
       title: manual crypto object
-      x-internal: true
       additionalProperties: false
       properties:
         id:
@@ -719,13 +713,22 @@ components:
           description: CoinGecko identifier associated with this balance
         to_base:
           type: number
-          description: Balance converted to the user's primary currency
+          nullable: true
+          description: Balance converted to the user's primary currency. May be null if no conversion was available.
         balance_as_of:
           type: string
           format: date-time
           nullable: true
-          description: Date/time the balance was last updated in ISO 8601
-            extended format
+          description: Date/time the manual balance record was last updated in
+            ISO 8601 extended format. This is currently based on the manual
+            crypto record's updated_at timestamp.
+        exchange_rate_as_of:
+          type: string
+          format: date-time
+          nullable: true
+          description: Date/time the exchange rate used to calculate to_base was
+            last updated in ISO 8601 extended format. Null when no exchange rate was
+            used or no conversion was available.
         created_by_name:
           type: string
           nullable: true
@@ -750,6 +753,7 @@ components:
         - coingecko_id
         - to_base
         - balance_as_of
+        - exchange_rate_as_of
         - created_by_name
         - created_at
         - updated_at
@@ -758,14 +762,18 @@ components:
     cryptoSyncedBalance:
       type: object
       title: synced crypto balance object
-      x-internal: true
       additionalProperties: false
       properties:
         name:
           type: string
           minLength: 1
           maxLength: 45
-          description: The name of the crypto asset
+          description: The asset name for this balance, typically the uppercased currency symbol (e.g. ETH).
+        display_name:
+          type: string
+          nullable: true
+          description: Optional display name for the synced crypto asset as set by the user. If `null`,
+            clients may derive a display name from syncedCryptoAccount's `provider` + `name`.
         balance:
           type: string
           pattern: ^-?\d+(\.\d{1,18})?$
@@ -783,13 +791,21 @@ components:
           description: CoinGecko identifier associated with this balance
         to_base:
           type: number
-          description: Balance converted to the user's primary currency
+          nullable: true
+          description: Balance converted to the user's primary currency. May be null if no conversion was available.
         balance_as_of:
           type: string
           format: date-time
           nullable: true
           description: Date/time the balance was last updated in ISO 8601
-            extended format
+            extended format.
+        exchange_rate_as_of:
+          type: string
+          format: date-time
+          nullable: true
+          description: Date/time the exchange rate used to calculate to_base was
+            last updated in ISO 8601 extended format. Null when no exchange rate was
+            used or no conversion was available.
         updated_at:
           type: string
           format: date-time
@@ -797,17 +813,18 @@ components:
             extended format
       required:
         - name
+        - display_name
         - balance
         - symbol
         - coingecko_id
         - to_base
         - balance_as_of
+        - exchange_rate_as_of
         - updated_at
 
     syncedCryptoAccount:
       type: object
       title: synced crypto account
-      x-internal: true
       additionalProperties: false
       properties:
         id:
@@ -974,16 +991,19 @@ components:
           example: Cold Wallet BTC
         display_name:
           type: string
+          nullable: true
           minLength: 1
           maxLength: 45
-          description: Optional display name for the manual crypto asset. If
-            omitted, clients may derive one from `institution_name` + `name`.
+          description: Display name for the manual crypto asset. If omitted or
+            `null`, clients may derive one from `institution_name` + `name`.
           example: Cold Storage
         institution_name:
           type: string
+          nullable: true
           minLength: 1
           maxLength: 50
-          description: Optional institution or wallet provider display name
+          description: Institution or wallet provider display name. If omitted
+            or `null`, no institution name is set.
           example: Ledger
         balance:
           oneOf:
@@ -1072,8 +1092,16 @@ components:
           type: string
           format: date-time
           nullable: true
-          description: System defined date/time the balance was last updated in
-            ISO 8601 extended format. Ignored if set
+          description: System defined date/time the manual balance record was
+            last updated in ISO 8601 extended format. Ignored if set
+          x-updatable: false
+        exchange_rate_as_of:
+          type: string
+          format: date-time
+          nullable: true
+          description: System defined date/time the exchange rate used to
+            calculate to_base was observed in ISO 8601 extended format. Ignored
+            if set
           x-updatable: false
         created_by_name:
           type: string
@@ -1231,15 +1259,19 @@ components:
           example: My Savings Account
         institution_name:
           type: string
+          nullable: true
           example: Bank of the West
-          description: Name of institution holding the manual account
+          description: Name of the institution holding the manual account. If
+            omitted or `null`, no institution name is set.
           minLength: 1
           maxLength: 50
         display_name:
           type: string
-          description: Display name of the manual account as set by user or
-            derived from the `institution_name` and `name` if not explicitly
-            set.<br> This must be unique for the budgeting account.
+          nullable: true
+          description: Display name of the manual account. If omitted or
+            `null`, it is derived from `institution_name` and `name`. An
+            explicitly set display name must be unique for the budgeting
+            account.
           example: Savings
         type:
           description: The type of manual account
@@ -1247,8 +1279,10 @@ components:
             - $ref: "#/components/schemas/accountTypeEnum"
         subtype:
           type: string
-          description: An optional manual account subtype. Examples include<br>
-            - retirement - checking - savings - prepaid credit card
+          nullable: true
+          description: Manual account subtype. If omitted or `null`, no subtype
+            is set. Examples include retirement, checking, savings, and prepaid
+            credit card.
           minLength: 1
           maxLength: 100
           example: prepaid credit card
@@ -1353,10 +1387,13 @@ components:
             - $ref: "#/components/schemas/accountTypeEnum"
         subtype:
           type: string
-          description: If set, an optional account subtype. Examples include<br>
+          nullable: true
+          description: If set, an optional account subtype. Set to `null` to clear it. 
+            Examples include<br>
             - retirement - checking - savings - prepaid credit card
           minLength: 1
           maxLength: 100
+          example: prepaid credit card
           x-updatable: true
         balance:
           oneOf:
@@ -1614,11 +1651,12 @@ components:
       type: object
       description: Source information for a manual account balance history entry.
       additionalProperties: false
+      x-internal: true
       properties:
         type:
           type: string
           enum: [manual]
-          description: Identifies this entry as belonging to a manually-managed account.
+          description: Identifies this entry as belonging to a manual account.
         manual_account_id:
           type: integer
           format: int32
@@ -1631,6 +1669,7 @@ components:
       type: object
       description: Source information for a Plaid-synced account balance history entry.
       additionalProperties: false
+      x-internal: true
       properties:
         type:
           type: string
@@ -1646,13 +1685,14 @@ components:
 
     balanceHistorySourceCryptoManual:
       type: object
-      description: Source information for a manually-tracked cryptocurrency balance history entry.
+      description: Source information for a manual cryptocurrency balance history entry.
       additionalProperties: false
+      x-internal: true
       properties:
         type:
           type: string
           enum: [crypto_manual]
-          description: Identifies this entry as belonging to a manually-tracked crypto account.
+          description: Identifies this entry as belonging to a manual crypto account.
         crypto_manual_id:
           type: integer
           format: int32
@@ -1695,10 +1735,11 @@ components:
       type: object
       x-internal: true
       description: >
-        Source information for a balance history entry whose account has since been deleted.
+        Source information for balance history whose account has since been deleted.
         Historical balances are preserved when a user chooses to keep history on account deletion.
         This object contains details that can be used to display the deleted account in the UI.
-        The `deleted_account_id` can be passed to `PUT /v2/balance_history/deleted/{account_id}/details`
+        The `deleted_account_id` can be passed to
+        [PUT /balance_history/deleted/{account_id}/details](#tag/balance-history/PUT/balance_history/deleted/{account_id}/details)
         to update the archived source metadata.
       additionalProperties: false
       properties:
@@ -1729,11 +1770,11 @@ components:
         subtype:
           type: string
           nullable: true
-          description: Archived `subtype`` of the deleted account source
+          description: Archived `subtype` of the deleted account source
         mask:
           type: string
           nullable: true
-          description: Archived account `mask` for a deleted plaid account source
+          description: Archived account `mask` for a deleted Plaid account source
         symbol:
           type: string
           nullable: true
@@ -1750,16 +1791,19 @@ components:
         - subtype
         - mask
         - symbol
+
     balanceHistoryAccountObject:
       type: object
-      title: balance history account object
+      title: balance history for an account object
       additionalProperties: false
-      description: Historical balance entries grouped under a single account source.
+      description: Monthly balance entries grouped under a single account source.
       properties:
         source:
           description: >
-            Identifies the account this balance entry belongs to. The shape varies by
-            `source.type`. Use `source.type` to determine which account id field is present.
+            Identifies the account these balance entries belong to. The shape varies by
+            `source.type`. Each source type exposes a type-specific account id field
+            (`manual_account_id`, `plaid_account_id`, `crypto_manual_id`,
+            `crypto_synced_id`, or `deleted_account_id`).
           oneOf:
             - $ref: "#/components/schemas/balanceHistorySourceManual"
             - $ref: "#/components/schemas/balanceHistorySourcePlaid"
@@ -1776,35 +1820,49 @@ components:
               deleted: "#/components/schemas/balanceHistorySourceDeleted"
         balances:
           type: array
-          description: One or more monthly balance history entries for the source account.
+          description: >
+            Monthly balance entries for this account source. A `historical` entry is
+            a stored snapshot of a past month and includes an `id`. A `current` entry
+            is an ephemeral snapshot based on the account's current balances and has
+            no balance-entry `id`. On PUT upsert responses, this array includes only
+            the `type: historical` entries modified by that request.
           items:
-            $ref: "#/components/schemas/balanceHistoryObject"
+            $ref: "#/components/schemas/balanceHistoryEntry"
       required:
         - source
         - balances
 
-    balanceHistoryObject:
+    historicalBalanceHistoryEntry:
       type: object
-      title: balance history entry object
+      title: historical balance history entry
       additionalProperties: false
-      description: A historical balance entry for a single account on a single date.
+      x-internal: true
+      description: >
+        A stored monthly balance for a past month. The `id` may be used with
+        balance history entry endpoints. The balance represents the account
+        balance at or around the end of `month`.
       properties:
+        type:
+          type: string
+          enum: [historical]
+          description: Identifies this entry as a stored snapshot of a past month.
         id:
           type: integer
           format: int32
-          description: Unique identifier of this historical balance entry.
-        date:
+          description: Unique identifier for this historical balance entry.
+        month:
           type: string
-          format: date
-          description: Date of this historical balance entry in YYYY-MM-DD format. This is always the first day of a month.
+          pattern: '^\d{4}-(0[1-9]|1[0-2])$'
+          description: Calendar month for this entry in YYYY-MM format.
+          example: "2026-06"
         balance:
           type: string
           pattern: ^-?\d+(\.\d{1,4})?$
-          description: Historical balance stored for this entry. For manual and Plaid accounts this is in the account currency. For crypto accounts this is in the user's primary currency.
+          description: Historical balance for this entry, as a numeric string with up to four decimal places. Trailing zeros and decimal places are not guaranteed in responses. For manual and Plaid accounts this is in the account currency. For crypto accounts this is in the user's primary currency.
         currency:
           allOf:
             - $ref: "#/components/schemas/currencyEnum"
-          description: Currency of the stored `balance`. For crypto entries this is the user's primary currency.
+          description: Currency of `balance`. For crypto entries this is the user's primary currency.
         to_base:
           type: number
           format: double
@@ -1813,19 +1871,82 @@ components:
           type: string
           nullable: true
           pattern: ^-?\d+(\.\d{1,18})?$
-          description: Crypto quantity stored for this balance entry, when available. This may be present for crypto or deleted-account entries and is `null` otherwise.
+          description: Crypto quantity for this balance entry, when available. This may be present for crypto or deleted-account entries and is `null` otherwise.
       required:
+        - type
         - id
-        - date
+        - month
         - balance
         - currency
         - to_base
         - crypto_balance
 
+    currentBalanceHistoryEntry:
+      type: object
+      title: current balance history entry
+      additionalProperties: false
+      x-internal: true
+      description: >
+        An ephemeral snapshot based on the account's current balances. It may
+        change between requests.
+      properties:
+        type:
+          type: string
+          enum: [current]
+          description: Identifies this entry as an ephemeral current-month snapshot.
+        month:
+          type: string
+          pattern: '^\d{4}-(0[1-9]|1[0-2])$'
+          description: Calendar month for this entry in YYYY-MM format. For current entries this is the current month.
+          example: "2026-07"
+        balance:
+          type: string
+          pattern: ^-?\d+(\.\d{1,4})?$
+          description: Calculated balance for the current month, as a numeric string with up to four decimal places. Trailing zeros and decimal places are not guaranteed in responses. For manual and Plaid accounts this is in the account currency. For crypto accounts this is in the user's primary currency.
+        currency:
+          allOf:
+            - $ref: "#/components/schemas/currencyEnum"
+          description: Currency of the calculated `balance`. For crypto entries this is the user's primary currency.
+        to_base:
+          type: number
+          format: double
+          description: Calculated balance converted to the user's primary currency. When the entry currency is the user's primary currency, this is the numeric value of `balance`.
+        crypto_balance:
+          type: string
+          nullable: true
+          pattern: ^-?\d+(\.\d{1,18})?$
+          description: Crypto quantity for this calculated entry, when available. This may be present for crypto entries and is `null` otherwise.
+      required:
+        - type
+        - month
+        - balance
+        - currency
+        - to_base
+        - crypto_balance
+
+    balanceHistoryEntry:
+      title: balance history entry
+      x-internal: true
+      description: >
+        A monthly balance history entry. Discriminated by `type`. `historical`
+        entries are stored snapshots of past months with an `id`. `current`
+        entries are ephemeral snapshots with no balance-entry `id`.
+      oneOf:
+        - $ref: "#/components/schemas/historicalBalanceHistoryEntry"
+        - $ref: "#/components/schemas/currentBalanceHistoryEntry"
+      discriminator:
+        propertyName: type
+        mapping:
+          historical: "#/components/schemas/historicalBalanceHistoryEntry"
+          current: "#/components/schemas/currentBalanceHistoryEntry"
+
     balanceHistoryListResponseObject:
       type: object
       additionalProperties: false
       x-internal: true
+      description: >
+        List response for balance history GET endpoints. Entries are grouped by
+        account source under `balance_history`.
       properties:
         balance_history:
           type: array
@@ -1838,31 +1959,39 @@ components:
       type: object
       x-internal: true
       additionalProperties: false
+      description: >
+        A single monthly balance entry to upsert. Request bodies use this shape.
+        Responses return `type: historical` entries instead.
       properties:
         id:
           type: integer
           format: int32
           description: System-defined balance history entry id. Ignored if set.
           x-updatable: false
-        date:
+        month:
           type: string
-          format: date
-          description: Month to update, in YYYY-MM-DD format. This must be the first day of a month and must not be in the future.
+          pattern: '^\d{4}-(0[1-9]|1[0-2])$'
+          description: >
+            Calendar month to upsert, in YYYY-MM format. Must be a past month.
+            The current month cannot be written through PUT endpoints.
+          example: "2026-06"
         balance:
           oneOf:
             - type: number
               format: double
             - type: string
               pattern: ^-?\d+(\.\d{1,4})?$
-          description: Numeric value of the historical balance, up to four decimal places, as a number or string. For manual and Plaid accounts this is typically in the account currency. For crypto and deleted accounts this is typically in the user's primary currency. Do not include any special characters aside from a decimal point.
+          description: Numeric value of the historical balance, up to four decimal places, as a number or string. For manual and Plaid accounts this is in the account currency. For crypto and deleted accounts this is in the user's primary currency. Do not include any special characters aside from a decimal point.
         symbol:
           type: string
           nullable: true
           minLength: 1
           maxLength: 25
-          description: Optional for crypto balances, but if set it must match the account's symbol.
-            Tolerated for deleted-account balances. Do not provide this for manual or Plaid balances.
-            If provided when using the synced crypto path-based endpoint, this must match the symbol in the path.
+          description: >
+            Optional for crypto balances. If set, it must match the account's
+            symbol. Tolerated for deleted-account balances. Do not provide this
+            for manual or Plaid balances. On the synced crypto path endpoint, if
+            provided it must match the `symbol` path parameter.
           x-updatable: true
         crypto_balance:
           type: string
@@ -1878,10 +2007,10 @@ components:
         to_base:
           type: number
           format: double
-          description: System-defined historical balance converted to the user's primary currency. Ignored if set. Use `balance` to update the stored historical balance.
+          description: System-defined historical balance converted to the user's primary currency. Ignored if set. Use `balance` to update the historical balance.
           x-updatable: false
       required:
-        - date
+        - month
         - balance
 
     upsertBalanceHistoryRequestObject:
@@ -1892,43 +2021,16 @@ components:
         balances:
           type: array
           minItems: 1
-          description: One or more monthly balance history entries to upsert
+          description: >
+            One or more monthly balance history entries to upsert. Each entry uses
+            `month` (YYYY-MM) and `balance`. Do not include response-only fields such
+            as `type`. PUT responses return only the `type: historical` entries
+            modified by the request.
           items:
             $ref: "#/components/schemas/balanceHistoryUpdateItemObject"
       required:
         - balances
 
-    balanceHistoryUpdateErrorObject:
-      type: object
-      x-internal: true
-      additionalProperties: true
-      properties:
-        request_balances_index:
-          type: integer
-          format: int32
-          description: Zero-based index into the `balances` request array
-        message:
-          type: string
-          description: Error message describing why the row could not be updated
-      required:
-        - request_balances_index
-        - message
-
-    upsertBalanceHistoryResponseObject:
-      type: object
-      x-internal: true
-      additionalProperties: false
-      properties:
-        updated_balance_history:
-          $ref: "#/components/schemas/balanceHistoryAccountObject"
-        errors:
-          type: array
-          items:
-            $ref: "#/components/schemas/balanceHistoryUpdateErrorObject"
-      required:
-        - updated_balance_history
-        - errors
-
     updateBalanceHistoryDetailsRequestObject:
       type: object
       x-internal: true
@@ -1938,51 +2040,58 @@ components:
         name:
           type: string
           nullable: true
-          description: New archived account name for the deleted account source.
+          description: New archived account name for the deleted account source
         institution_name:
           type: string
           nullable: true
-          description: New archived institution name for the deleted account source.
+          description: New archived institution name for the deleted account source
         display_name:
           type: string
           nullable: true
-          description: New display name for the deleted account source.
+          description: New display name for the deleted account source
         account_type:
           type: string
           nullable: true
-          description: New archived account type for the deleted account source.
+          description: New archived account type for the deleted account source
         subtype:
           type: string
           nullable: true
-          description: New archived subtype for the deleted account source.
+          description: New archived subtype for the deleted account source
         mask:
           type: string
           nullable: true
-          description: New archived account mask for the deleted account source.
+          description: New archived account mask for the deleted account source
 
     updateBalanceHistoryDetailsResponseObject:
       type: object
       x-internal: true
       additionalProperties: false
+      description: Updated archived metadata for a deleted balance history source
       properties:
         name:
           type: string
           nullable: true
+          description: Archived account name for the deleted account source
         institution_name:
           type: string
           nullable: true
+          description: Archived institution name for the deleted account source
         display_name:
           type: string
           nullable: true
+          description: Archived display name for the deleted account source
         account_type:
           type: string
           nullable: true
+          description: Archived account type for the deleted account source
         subtype:
           type: string
           nullable: true
+          description: Archived subtype for the deleted account source
         mask:
           type: string
           nullable: true
+          description: Archived account mask for the deleted account source
       required:
         - name
         - institution_name
@@ -2467,14 +2576,9 @@ components:
         external_id:
           type: string
           nullable: true
-          description: A user-defined external ID for any transaction that was
-            added via csv import, `POST /transactions` API call, or manually
-            added via the Lunch Money app. No external ID exists for
-            transactions associated with synced accounts, and they cannot be
-            added. For transactions associated with manual accounts, the
-            external ID must be unique as attempts to add a subsequent
-            transaction with the same external_id and manual_account_id will be
-            flagged as duplicates and fail.
+          description: A user-defined external ID associated with the transaction. 
+            For transactions belonging to manual accounts, the
+            external ID must be unique for each transaction associated with the account.
           minLength: 0
           maxLength: 75
         tag_ids:
@@ -2495,8 +2599,6 @@ components:
             Any transaction notes set by the user or by 
             a matched recurring item. This will match the value 
             displayed in notes field on the transactions page in the Lunch Money app.
-          minLength: 0
-          maxLength: 350
         status:
           type: string
           # description: >
@@ -2732,8 +2834,6 @@ components:
             Any transaction notes set by the user or by 
             a matched recurring item. This will match the value 
             displayed in notes field on the transactions page in the Lunch Money app.
-          minLength: 0
-          maxLength: 350
         status:
           type: string
           description: >
@@ -2875,14 +2975,9 @@ components:
         external_id:
           type: string
           nullable: true
-          description: A user-defined external ID for any transaction that was
-            added via csv import, `POST /transactions` API call, or manually
-            added via the Lunch Money app. No external ID exists for
-            transactions associated with synced accounts, and they cannot be
-            added. For transactions associated with manual accounts, the
-            external ID must be unique as attempts to add a subsequent
-            transaction with the same external_id and manual_account_id will be
-            flagged as duplicates and fail.
+          description: A user-defined external ID associated with the transaction. 
+            For transactions belonging to manual accounts, the
+            external ID must be unique for each transaction associated with the account.
           minLength: 0
           maxLength: 75
         plaid_metadata:
@@ -2952,7 +3047,7 @@ components:
         currency:
           description: Three-letter lowercase currency code of the transaction
             in ISO 4217 format. Must match one of the [supported
-            currencies](https://lm-v2-api-next-a7fabcab8e9a.herokuapp.com/v2/currencies). If not set
+            currencies](https://lunchmoney.dev/v2/currencies). If not set
             defaults to the user account's primary currency.
           allOf:
             - $ref: "#/components/schemas/currencyEnum"
@@ -2978,8 +3073,6 @@ components:
             Any transaction notes set by the user or by 
             a matched recurring item. This will match the value 
             displayed in notes field on the transactions page in the Lunch Money app.
-          minLength: 0
-          maxLength: 350
         manual_account_id:
           type: integer
           format: int32
@@ -3099,6 +3192,7 @@ components:
           description: |
             The new payee for the transaction.
           minLength: 0
+          x-updatable: true
         original_name:
           type: string
           nullable: true
@@ -3117,8 +3211,6 @@ components:
           description: >
             New notes for the transaction. Set this to an empty string to clear
             the existing notes.
-          minLength: 0
-          maxLength: 350
           x-updatable: true
         manual_account_id:
           type: integer
@@ -3301,6 +3393,7 @@ components:
             amount.
         payee:
           type: string
+          minLength: 0
           description: The payee for the child transaction. Will inherit the
             original payee from the parent if not defined.
         date:
@@ -3311,9 +3404,10 @@ components:
         category_id:
           type: integer
           format: int32
-          description: Unique identifier for associated category_id. Category
-            must already exist for the account. Will inherit category from the
-            parent if not defined.
+          nullable: true
+          description: Category ID for the child transaction. The category must
+            already exist for the account. If omitted, the child inherits the
+            parent category. If `null`, the child has no category.
         tag_ids:
           type: array
           description: The IDs of any tags to apply to this split child
@@ -3323,8 +3417,10 @@ components:
             format: int32
         notes:
           type: string
-          maxLength: 350
-          description: Will inherit notes from parent if not defined.
+          nullable: true
+          description: Notes for the child transaction. If omitted, the child
+            inherits the parent notes. If `null` or an empty string, the child
+            has no notes.
       required:
         - amount
 
@@ -3633,10 +3729,11 @@ components:
 
     # Response body for GET /budgets/settings (200)
     budgetSettingsResponseObject:
-      x-internal: true
       type: object
+      title: budget settings object
       additionalProperties: false
-      description: Budget period and display settings
+      description: Budget period and display settings for the current budgeting
+        account.
       properties:
         budget_period_granularity:
           type: string
@@ -3648,8 +3745,8 @@ components:
           - twice a month
           description: Budget period granularity
         budget_period_quantity:
-          type: number
-          format: double
+          type: integer
+          format: int32
           description: The number of `granularity` units that make up a single
             budgeting period.
         budget_period_anchor_date:
@@ -4005,7 +4102,9 @@ components:
             while processing the request.<br> If multiple errors were
             encountered, the list will contain multiple objects.<br> Each
             `error` object is guaranteed to have an `errMsg`, but it may also
-            contain other error specific properties.
+            contain other error-specific properties such as `code` (for example
+            `VALIDATION_ERROR`), or other properties that are useful to map
+             the error to the relevant part of the request.
           type: array
           items:
             type: object
@@ -4114,6 +4213,7 @@ components:
       #   - `cad`: Canadian Dollar
       #   - `cdf`: Congolese Franc
       #   - `chf`: Swiss Franc
+      #   - `clf`: Chilean Unit of Account (UF)
       #   - `clp`: Chilean Peso
       #   - `cny`: Chinese Yuan
       #   - `cop`: Colombian Peso
@@ -4129,6 +4229,7 @@ components:
       #   - `egp`: Egyptian Pound
       #   - `ern`: Eritrean Nakfa
       #   - `etb`: Ethiopian Birr
+      #   - `eth`: Ethereum
       #   - `eur`: Euro
       #   - `fjd`: Fijian Dollar
       #   - `fkp`: Falkland Islands Pound
@@ -4236,6 +4337,7 @@ components:
       #   - `uyu`: Uruguayan Peso
       #   - `uzs`: Uzbekistan Som
       #   - `vef`: Venezuelan Bolívar
+      #   - `ves`: Venezuelan Bolívar Sotiemas
       #   - `vnd`: Vietnamese Dong
       #   - `vuv`: Vanuatu Vatu
       #   - `wst`: Samoan Tala
@@ -4279,6 +4381,7 @@ components:
         - cad
         - cdf
         - chf
+        - clf
         - clp
         - cny
         - cop
@@ -4294,6 +4397,7 @@ components:
         - egp
         - ern
         - etb
+        - eth
         - eur
         - fjd
         - fkp
@@ -4401,6 +4505,7 @@ components:
         - uyu
         - uzs
         - vef
+        - ves
         - vnd
         - vuv
         - wst
@@ -4458,22 +4563,10 @@ components:
   securitySchemes:
     bearerSecurity:
       type: http
-      # TODO Make this shorter?
-      # description: The Lunch Money API uses API keys to authenticate requests. To use
-      #   the v1 API you can view and manage your API keys on the [developers page
-      #   in the Lunch Money app](https://my.lunchmoney.app/developers). <p> To
-      #   interact with the Static Mock Server simply enter an API key of 11
-      #   characters or more. <p> To interact with the v2 service implemented on
-      #   top of the v1 API paste in a real API token associated with a Lunch
-      #   Money Budget.
-      description: To interact with the Static Mock Server simply enter an API
-        key of 11 characters or more.
+      description: >-
+        Required for the LIVE server. Optional for MOCK.
       scheme: bearer
       bearerFormat: JWT
-    cookieAuth:
-      type: apiKey
-      in: cookie
-      name: _lm_access_token
 
 paths:
   /me:
@@ -5753,12 +5846,9 @@ paths:
       tags:
         - crypto-manual
       summary: Get all supported cryptocurrencies
-      description: >
+      description: |-
         Retrieve the list of cryptocurrencies currently supported for manual tracking.<p>
-
-        When creating a new manual crypto balance via `POST /crypto/manual`, the
-        `symbol` you specify must match the `symbol` of one of the entries
-        returned by this endpoint.
+        When creating a new manual crypto balance via `POST /crypto/manual`, the `symbol` you specify must match the `symbol` of one of the entries returned by this endpoint.
       operationId: getAllCryptocurrencies
       responses:
         "200":
@@ -5796,16 +5886,9 @@ paths:
         - crypto-manual
       summary: Add a new supported cryptocurrency
       operationId: createCryptocurrency
-      description: >-
+      description: |-
         Adds a new cryptocurrency to the supported manual-crypto list.<br><br>
-
-        Lunch Money uses [CoinGecko](https://www.coingecko.com/us/coins/ethereum)
-        to convert crypto balances to the user's primary currency. Users add a
-        new supported cryptocurrency by submitting a CoinGecko coin-page URL.
-        The server validates the URL, extracts the id from `/coins/{id}`,
-        checks for an existing supported `coingecko_id`, validates the id
-        against CoinGecko, then confirms the resolved symbol is not already
-        supported before creating the new entry.
+        Lunch Money uses [CoinGecko](https://www.coingecko.com/us/coins/ethereum) to convert crypto balances to the user's primary currency. Users add a new supported cryptocurrency by submitting a CoinGecko coin-page URL. The server validates the URL, extracts the id from `/coins/{id}`, checks for an existing supported `coingecko_id`, validates the id against CoinGecko, then confirms the resolved symbol is not already supported before creating the new entry.
       requestBody:
         required: true
         content:
@@ -5884,8 +5967,8 @@ paths:
       tags:
         - crypto-manual
       summary: Get all manual crypto balances
-      description: Retrieve all manually managed crypto balances associated with
-        the user's account.
+      description: |-
+        Retrieve all manually managed crypto balances associated with the user's account.
       operationId: getAllCryptoManual
       responses:
         "200":
@@ -5905,6 +5988,7 @@ paths:
                     coingecko_id: bitcoin
                     to_base: 53124.72
                     balance_as_of: "2026-02-25T14:22:10.000Z"
+                    exchange_rate_as_of: "2026-02-25T14:10:00.000Z"
                     created_by_name: User 1
                     created_at: "2025-11-12T20:14:32.000Z"
                     updated_at: "2026-02-25T14:22:10.000Z"
@@ -5918,11 +6002,9 @@ paths:
       tags:
         - crypto-manual
       summary: Create a manual crypto balance
-      description: >-
+      description: |-
         Create a manually managed crypto asset.<br><br>
-
-        If `display_name` is `null`, clients may derive one from
-        `institution_name` + `name`.
+        If `display_name` is `null`, clients may derive one from `institution_name` + `name`.
       operationId: createCryptoManual
       requestBody:
         required: true
@@ -5962,6 +6044,7 @@ paths:
                 coingecko_id: ethereum
                 to_base: 28998.44
                 balance_as_of: "2026-03-01T09:20:41.000Z"
+                exchange_rate_as_of: "2026-03-01T09:15:00.000Z"
                 created_by_name: User 1
                 created_at: "2026-03-01T09:20:41.000Z"
                 updated_at: "2026-03-01T09:20:41.000Z"
@@ -5974,11 +6057,22 @@ paths:
               examples:
                 missing required properties:
                   value:
-                    message: Request Validation Failure
+                    message: Invalid Request Body
                     errors:
                       - errMsg: "Missing required property 'name' in request body."
                       - errMsg: "Missing required property 'balance' in request body."
                       - errMsg: "Missing required property 'symbol' in request body."
+                invalid balance:
+                  value:
+                    message: Invalid Request Body
+                    errors:
+                      - errMsg: "Invalid value for property 'balance'. 'abc' cannot be converted to a number"
+                      - errMsg: "Invalid value for property 'balance'. Invalid input"
+                invalid property:
+                  value:
+                    message: Invalid Request Body
+                    errors:
+                      - errMsg: "Invalid property 'coingecko_id' in request body."
                 unsupported symbol:
                   value:
                     message: Request Validation Failure
@@ -5995,7 +6089,8 @@ paths:
       tags:
         - crypto-manual
       summary: Get a single manual crypto balance
-      description: Retrieve a single manually managed crypto balance by ID.
+      description: |-
+        Retrieve a single manually managed crypto balance by ID.
       operationId: getCryptoManualById
       parameters:
         - name: id
@@ -6029,6 +6124,7 @@ paths:
                 coingecko_id: bitcoin
                 to_base: 53124.72
                 balance_as_of: "2026-02-25T14:22:10.000Z"
+                exchange_rate_as_of: "2026-02-25T14:10:00.000Z"
                 created_by_name: User 1
                 created_at: "2025-11-12T20:14:32.000Z"
                 updated_at: "2026-02-25T14:22:10.000Z"
@@ -6062,11 +6158,9 @@ paths:
       tags:
         - crypto-manual
       summary: Update a manual crypto balance
-      description: >-
+      description: |-
         Modify a manually managed crypto balance.<br><br>
-
-        You may submit the response from `GET /crypto/manual/{id}` as the request body. System-defined properties
-        are accepted according to the `x-updatable` metadata in the update schema.
+        You may submit the response from `GET /crypto/manual/{id}` as the request body. System-defined properties are accepted according to the `x-updatable` metadata in the update schema.
       operationId: updateCryptoManual
       parameters:
         - name: id
@@ -6106,6 +6200,7 @@ paths:
                   coingecko_id: bitcoin
                   to_base: 56011.12
                   balance_as_of: "2026-03-01T09:41:18.000Z"
+                  exchange_rate_as_of: "2026-03-01T09:35:00.000Z"
                   created_by_name: User 1
                   created_at: "2025-11-12T20:14:32.000Z"
                   updated_at: "2026-02-25T14:22:10.000Z"
@@ -6126,6 +6221,7 @@ paths:
                 coingecko_id: bitcoin
                 to_base: 56011.12
                 balance_as_of: "2026-03-01T09:41:18.000Z"
+                exchange_rate_as_of: "2026-03-01T09:35:00.000Z"
                 created_by_name: User 1
                 created_at: "2025-11-12T20:14:32.000Z"
                 updated_at: "2026-03-01T09:41:18.000Z"
@@ -6161,10 +6257,8 @@ paths:
       tags:
         - crypto-manual
       summary: Delete a manual crypto balance
-      description: Delete a single manually managed crypto asset by ID.<p> If
-        this crypto asset has a balance history, and you do not explicitly set
-        the query parameter`keep_history`, a 422 response will be returned
-        requesting you to explicitly set `keep_history` to `true` or `false`.
+      description: |-
+        Delete a single manually managed crypto asset by ID.<p> If this crypto asset has a balance history, and you do not explicitly set the query parameter`keep_history`, a 422 response will be returned requesting you to explicitly set `keep_history` to `true` or `false`.
       operationId: deleteCryptoManual
       parameters:
         - name: id
@@ -6229,8 +6323,8 @@ paths:
       tags:
         - crypto-synced
       summary: Get all synced crypto accounts
-      description: Retrieves all synced crypto accounts
-        associated with the user's account.
+      description: |-
+        Retrieves all synced crypto accounts associated with the user's account.
       operationId: getAllCryptoSynced
       responses:
         "200":
@@ -6255,6 +6349,7 @@ paths:
                         coingecko_id: ethereum
                         to_base: 28998.44
                         balance_as_of: "2026-02-25T14:25:00.000Z"
+                        exchange_rate_as_of: "2026-02-25T14:20:00.000Z"
                         updated_at: "2026-02-25T14:25:01.000Z"
                       - name: BTC
                         balance: "0.100020003000400050"
@@ -6262,6 +6357,7 @@ paths:
                         coingecko_id: bitcoin
                         to_base: 6231.28
                         balance_as_of: "2026-02-25T14:25:00.000Z"
+                        exchange_rate_as_of: "2026-02-25T14:20:00.000Z"
                         updated_at: "2026-02-25T14:25:01.000Z"
                   - id: 33005
                     provider: kraken
@@ -6277,6 +6373,7 @@ paths:
                         coingecko_id: ripple
                         to_base: 1287.50
                         balance_as_of: "2026-02-26T07:22:30.000Z"
+                        exchange_rate_as_of: "2026-02-26T07:10:00.000Z"
                         updated_at: "2026-02-26T07:22:30.000Z"
         "401":
           $ref: "#/components/responses/unauthorizedToken"
@@ -6289,8 +6386,8 @@ paths:
       tags:
         - crypto-synced
       summary: Get a single synced crypto account
-      description: Retrieves the synced crypto account and all nested balances
-        for the specified synced crypto account ID.
+      description: |-
+        Retrieves the synced crypto account and all nested balances for the specified synced crypto account ID.
       operationId: getCryptoSyncedById
       parameters:
         - name: id
@@ -6329,6 +6426,7 @@ paths:
                     coingecko_id: ethereum
                     to_base: 28998.44
                     balance_as_of: "2026-02-25T14:25:00.000Z"
+                    exchange_rate_as_of: "2026-02-25T14:20:00.000Z"
                     updated_at: "2026-02-25T14:25:01.000Z"
                   - name: BTC
                     balance: "0.100020003000400050"
@@ -6336,6 +6434,7 @@ paths:
                     coingecko_id: bitcoin
                     to_base: 6231.28
                     balance_as_of: "2026-02-25T14:25:00.000Z"
+                    exchange_rate_as_of: "2026-02-25T14:20:00.000Z"
                     updated_at: "2026-02-25T14:25:01.000Z"
         "400":
           description: Bad Request
@@ -6368,8 +6467,8 @@ paths:
       tags:
         - crypto-synced
       summary: Get a synced crypto balance by symbol
-      description: Retrieves a single balance from the specified synced crypto
-        account using the crypto symbol.
+      description: |-
+        Retrieves a single balance from the specified synced crypto account using the crypto symbol.
       operationId: getCryptoSyncedBalanceBySymbol
       parameters:
         - name: id
@@ -6401,6 +6500,7 @@ paths:
                 coingecko_id: ethereum
                 to_base: 28998.44
                 balance_as_of: "2026-02-25T14:25:00.000Z"
+                exchange_rate_as_of: "2026-02-25T14:20:00.000Z"
                 updated_at: "2026-02-25T14:25:01.000Z"
         "400":
           description: Bad Request
@@ -6447,8 +6547,8 @@ paths:
       tags:
         - crypto-synced
       summary: Refresh balances for a synced crypto account
-      description: Trigger a balance refresh for the specified synced crypto
-        account. Returns the refreshed synced crypto account.
+      description: |-
+        Trigger a balance refresh for the specified synced crypto account. Returns the refreshed synced crypto account.
       operationId: refreshCryptoSynced
       parameters:
         - name: id
@@ -6486,6 +6586,7 @@ paths:
                     coingecko_id: ethereum
                     to_base: 28998.44
                     balance_as_of: "2026-02-25T14:25:00.000Z"
+                    exchange_rate_as_of: "2026-02-25T14:20:00.000Z"
                     updated_at: "2026-02-25T14:25:01.000Z"
                   - name: BTC
                     balance: "0.100020003000400050"
@@ -6493,6 +6594,7 @@ paths:
                     coingecko_id: bitcoin
                     to_base: 6231.28
                     balance_as_of: "2026-02-25T14:25:00.000Z"
+                    exchange_rate_as_of: "2026-02-25T14:20:00.000Z"
                     updated_at: "2026-02-25T14:25:01.000Z"
         "401":
           $ref: "#/components/responses/unauthorizedToken"
@@ -6515,51 +6617,55 @@ paths:
       tags:
         - balance_history
       summary: Get balance history
-      description: >-
-        Retrieve historical balance entries.<br><br>
-
-        Balance history is monthly. When `start_date` and `end_date` are both provided,
-        they must be first-of-month dates. `start_date` must not be in the future,
-        while `end_date` may be in the future. If one of `start_date` or `end_date`
-        is provided, the other is required. If neither is provided, all available
-        balance history is returned.<br><br>
-
-        The response groups entries by source account. Each item in
-        `balance_history` contains a `source` object plus a `balances` array
-        containing one balance entry per month in the requested range, or all
-        stored entries when no range is provided.<br><br>
-
-        Historical entries for accounts that have been deleted may still
-        be returned. These entries use `source.type: deleted` and include
-        `deleted_account_id`, archived display fields, and account metadata on the
-        `source` object.
+      description: |-
+        Retrieve monthly balance history for all account sources.<br><br>
+        Balance history is monthly. Each entry represents the account balance at or around the end of the specified month. System-generated entries are generally captured near the boundary between months.<br><br>
+        Query with optional `start_month` and `end_month` in YYYY-MM format. The range is inclusive. If either parameter is provided, both are required. `start_month` must not be in the future. `end_month` may not be earlier than `start_month` and must not be in the future. Values must be valid calendar months in exact YYYY-MM format. A full date such as `2026-06-01` is invalid. If neither is provided, all available balance history is returned, including an ephemeral `current` entry for the current month when applicable.<br><br>
+        The response groups entries by source account. Each item in `balance_history` contains a `source` object plus a `balances` array. Within a requested range (or across all history when no range is provided), the array includes only months that have data — months with no data are omitted. A `current` entry is also included when the requested range includes the current month.<br><br>
+        Each balance entry has a `type`:<br>
+        - `historical`: stored snapshot of a past month for an active or deleted account. Includes an `id` that can be used with balance history entry endpoints<br>
+        - `current`: snapshot based on the account's current balances. It is ephemeral and may change between requests. To inspect the underlying account, use the type-specific source id for the `source.type` values:<br>
+        &nbsp;&nbsp;&nbsp;&nbsp;- `manual`: `source.manual_account_id` with [GET /manual_accounts/{id}](#tag/manual-accounts/GET/manual_accounts/{id})<br>
+        &nbsp;&nbsp;&nbsp;&nbsp;- `plaid`: `source.plaid_account_id` with [GET /plaid_accounts/{id}](#tag/plaid-accounts/GET/plaid_accounts/{id})<br>
+        &nbsp;&nbsp;&nbsp;&nbsp;- `crypto_manual`: `source.crypto_manual_id` with [GET /crypto/manual/{id}](#tag/crypto-manual/GET/crypto/manual/{id})<br>
+        &nbsp;&nbsp;&nbsp;&nbsp;- `crypto_synced`: `source.crypto_synced_id` and `source.symbol` with [GET /crypto/synced/{id}/{symbol}](#tag/crypto-synced/GET/crypto/synced/{id}/{symbol})
       operationId: getBalanceHistory
       parameters:
-        - name: start_date
+        - name: start_month
           in: query
-          description: Optional start date for the requested history range in YYYY-MM-DD format. If set, `end_date` is also required. This must be the first day of a month and must not be in the future.
+          description: >-
+            Optional start of the requested history range as a calendar month in
+            YYYY-MM format (for example `2026-06`). If set, `end_month` is also
+            required. The range is inclusive. `start_month` must not be in the
+            future. A full date such as `2026-06-01` is invalid.
           required: false
           schema:
             type: string
-            format: date
+            pattern: '^\d{4}-(0[1-9]|1[0-2])$'
           examples:
             range start:
-              summary: Start date
-              value: "2026-01-01"
-        - name: end_date
+              summary: Start month
+              value: "2026-01"
+        - name: end_month
           in: query
-          description: Optional end date for the requested history range in YYYY-MM-DD format. If set, `start_date` is also required. This must be the first day of a month. For a single month, set this to the same first-of-month date as `start_date`.
+          description: >-
+            Optional end of the requested history range as a calendar month in
+            YYYY-MM format (for example `2026-06`). If set, `start_month` is also
+            required. The range is inclusive. `end_month` may not be earlier than
+            `start_month` and must not be in the future. A full date such as
+            `2026-06-01` is invalid. For a single month, set this to the same
+            value as `start_month`.
           required: false
           schema:
             type: string
-            format: date
+            pattern: '^\d{4}-(0[1-9]|1[0-2])$'
           examples:
             range end:
-              summary: End date
-              value: "2026-03-01"
+              summary: End month
+              value: "2026-03"
       responses:
         "200":
-          description: Historical balance entries for the requested date range
+          description: Monthly balance history for the requested month range
           content:
             application/json:
               schema:
@@ -6572,14 +6678,16 @@ paths:
                           type: manual
                           manual_account_id: 119807
                         balances:
-                          - id: 101
-                            date: "2026-01-01"
+                          - type: historical
+                            id: 101
+                            month: "2026-01"
                             balance: "41000.0000"
                             currency: usd
                             to_base: 41000
                             crypto_balance: null
-                          - id: 102
-                            date: "2026-02-01"
+                          - type: historical
+                            id: 102
+                            month: "2026-02"
                             balance: "41211.8000"
                             currency: usd
                             to_base: 41211.8
@@ -6588,8 +6696,9 @@ paths:
                           type: plaid
                           plaid_account_id: 119808
                         balances:
-                          - id: 103
-                            date: "2026-01-01"
+                          - type: historical
+                            id: 103
+                            month: "2026-01"
                             balance: "5498.2800"
                             currency: usd
                             to_base: 5498.28
@@ -6599,8 +6708,9 @@ paths:
                           crypto_manual_id: 22001
                           symbol: btc
                         balances:
-                          - id: 104
-                            date: "2026-01-01"
+                          - type: historical
+                            id: 104
+                            month: "2026-01"
                             balance: "53124.7200"
                             currency: usd
                             to_base: 53124.72
@@ -6610,8 +6720,9 @@ paths:
                           crypto_synced_id: 33004
                           symbol: btc
                         balances:
-                          - id: 105
-                            date: "2026-01-01"
+                          - type: historical
+                            id: 105
+                            month: "2026-01"
                             balance: "6231.2800"
                             currency: usd
                             to_base: 6231.28
@@ -6627,12 +6738,34 @@ paths:
                           mask: "1234"
                           symbol: null
                         balances:
-                          - id: 106
-                            date: "2026-01-01"
+                          - type: historical
+                            id: 106
+                            month: "2026-01"
                             balance: "1250.0000"
                             currency: usd
                             to_base: 1250
                             crypto_balance: null
+                historical and current:
+                  summary: Historical month plus ephemeral current month
+                  value:
+                    balance_history:
+                      - source:
+                          type: manual
+                          manual_account_id: 162003
+                        balances:
+                          - type: historical
+                            id: 7437356
+                            month: "2026-06"
+                            balance: "62.8"
+                            currency: usd
+                            to_base: 62.8
+                            crypto_balance: null
+                          - type: current
+                            month: "2026-07"
+                            balance: "71.2"
+                            currency: usd
+                            to_base: 71.2
+                            crypto_balance: null
                 manual account history:
                   value:
                     balance_history:
@@ -6640,14 +6773,16 @@ paths:
                           type: manual
                           manual_account_id: 119807
                         balances:
-                          - id: 201
-                            date: "2026-01-01"
+                          - type: historical
+                            id: 201
+                            month: "2026-01"
                             balance: "41000.0000"
                             currency: usd
                             to_base: 41000
                             crypto_balance: null
-                          - id: 202
-                            date: "2026-02-01"
+                          - type: historical
+                            id: 202
+                            month: "2026-02"
                             balance: "41211.8000"
                             currency: usd
                             to_base: 41211.8
@@ -6659,8 +6794,9 @@ paths:
                           type: plaid
                           plaid_account_id: 119808
                         balances:
-                          - id: 301
-                            date: "2026-02-01"
+                          - type: historical
+                            id: 301
+                            month: "2026-02"
                             balance: "5498.2800"
                             currency: usd
                             to_base: 5498.28
@@ -6673,8 +6809,9 @@ paths:
                           crypto_synced_id: 33004
                           symbol: btc
                         balances:
-                          - id: 401
-                            date: "2026-02-01"
+                          - type: historical
+                            id: 401
+                            month: "2026-02"
                             balance: "6231.2800"
                             currency: usd
                             to_base: 6231.28
@@ -6693,8 +6830,9 @@ paths:
                           mask: "1234"
                           symbol: null
                         balances:
-                          - id: 501
-                            date: "2026-01-01"
+                          - type: historical
+                            id: 501
+                            month: "2026-01"
                             balance: "1250.0000"
                             currency: usd
                             to_base: 1250
@@ -6706,26 +6844,31 @@ paths:
               schema:
                 $ref: "#/components/schemas/errorResponseObject"
               examples:
-                missing paired date:
+                missing paired month:
                   value:
                     message: Request Validation Failure
                     errors:
-                      - errMsg: "`start_date` and `end_date` must either both be provided or both be omitted."
+                      - errMsg: "`start_month` and `end_month` must either both be provided or both be omitted."
                 invalid range:
                   value:
                     message: Request Validation Failure
                     errors:
-                      - errMsg: "`start_date` must be less than or equal to `end_date`."
-                not first of month:
+                      - errMsg: "`end_month` may not be earlier than `start_month`."
+                invalid month format:
+                  value:
+                    message: Invalid Request Parameters
+                    errors:
+                      - errMsg: "Invalid value for parameter: 'start_month'. '2026-06-01' is not a valid month in YYYY-MM format."
+                future start month:
                   value:
                     message: Request Validation Failure
                     errors:
-                      - errMsg: "`start_date` and `end_date` must both be the first day of a month."
-                future start date:
+                      - errMsg: "`start_month` must not be in the future."
+                future end month:
                   value:
                     message: Request Validation Failure
                     errors:
-                      - errMsg: "`start_date` must not be in the future."
+                      - errMsg: "`end_month` must not be in the future."
         "401":
           $ref: "#/components/responses/unauthorizedToken"
         "429":
@@ -6737,23 +6880,16 @@ paths:
       tags:
         - balance_history
       summary: Get balance history for an account
-      description: >-
-        Retrieve historical balance entries for one manual, Plaid, manual crypto,
-        or deleted account.  Crypto synced accounts require an additional `symbol` path parameter.<br><br>
-
-        The `account_type` path parameter identifies the type of account and the
-        `account_id` path parameter identifies the specific id for that account type.<br><br>
-
-        When `start_date` and `end_date` are both provided, they must be first-of-month
-        dates. `start_date` must not be in the future, while `end_date` may be in the future.
-        If one of `start_date` or `end_date` is provided, the other is required. If neither is
-        provided, all available history for the source is returned.
+      description: |-
+        Retrieve monthly balance history for one manual, Plaid, manual crypto, or deleted account. For synced crypto symbol streams, use [GET /balance_history/crypto_synced/{account_id}/{symbol}](#tag/balance-history/GET/balance_history/crypto_synced/{account_id}/{symbol}).<br><br>
+        The `account_type` path parameter identifies the account family (`manual`, `plaid`, `crypto_manual`, or `deleted`) and `account_id` identifies the account within that family.<br><br>
+        `start_month`, `end_month`, and current-month entries behave as described in [GET /balance_history](#tag/balance-history/GET/balance_history).
       operationId: getBalanceHistoryForAccount
       parameters:
         - name: account_type
           in: path
           required: true
-          description: Source family to retrieve. Use `manual`, `plaid`, `crypto_manual`, or `deleted`.
+          description: Account family to retrieve. Use `manual`, `plaid`, `crypto_manual`, or `deleted`.
           schema:
             type: string
             enum: [manual, plaid, crypto_manual, deleted]
@@ -6764,23 +6900,27 @@ paths:
           schema:
             type: integer
             format: int32
-        - name: start_date
+        - name: start_month
           in: query
-          description: Optional start date for the requested history range in YYYY-MM-DD format. If set, `end_date` is also required. This must be the first day of a month and must not be in the future.
+          description: >-
+            Optional. Same format and constraints as `start_month` on
+            [GET /balance_history](#tag/balance-history/GET/balance_history).
           required: false
           schema:
             type: string
-            format: date
-        - name: end_date
+            pattern: '^\d{4}-(0[1-9]|1[0-2])$'
+        - name: end_month
           in: query
-          description: Optional end date for the requested history range in YYYY-MM-DD format. If set, `start_date` is also required. This must be the first day of a month.
+          description: >-
+            Optional. Same format and constraints as `end_month` on
+            [GET /balance_history](#tag/balance-history/GET/balance_history).
           required: false
           schema:
             type: string
-            format: date
+            pattern: '^\d{4}-(0[1-9]|1[0-2])$'
       responses:
         "200":
-          description: Historical balance entries for the requested source
+          description: Monthly balance history for the requested source
           content:
             application/json:
               schema:
@@ -6793,14 +6933,16 @@ paths:
                           type: manual
                           manual_account_id: 119807
                         balances:
-                          - id: 201
-                            date: "2026-01-01"
+                          - type: historical
+                            id: 201
+                            month: "2026-01"
                             balance: "41000.0000"
                             currency: usd
                             to_base: 41000
                             crypto_balance: null
-                          - id: 202
-                            date: "2026-02-01"
+                          - type: historical
+                            id: 202
+                            month: "2026-02"
                             balance: "41211.8000"
                             currency: usd
                             to_base: 41211.8
@@ -6819,8 +6961,9 @@ paths:
                           mask: "1234"
                           symbol: null
                         balances:
-                          - id: 501
-                            date: "2026-01-01"
+                          - type: historical
+                            id: 501
+                            month: "2026-01"
                             balance: "1250.0000"
                             currency: usd
                             to_base: 1250
@@ -6832,16 +6975,16 @@ paths:
               schema:
                 $ref: "#/components/schemas/errorResponseObject"
               examples:
-                missing paired date:
+                missing paired month:
                   value:
                     message: Request Validation Failure
                     errors:
-                      - errMsg: "`start_date` and `end_date` must either both be provided or both be omitted."
-                invalid range:
+                      - errMsg: "`start_month` and `end_month` must either both be provided or both be omitted."
+                invalid month format:
                   value:
-                    message: Request Validation Failure
+                    message: Invalid Request Parameters
                     errors:
-                      - errMsg: "`start_date` must be less than or equal to `end_date`."
+                      - errMsg: "Invalid value for parameter: 'start_month'. '2026-06-01' is not a valid month in YYYY-MM format."
         "401":
           $ref: "#/components/responses/unauthorizedToken"
         "404":
@@ -6860,7 +7003,7 @@ paths:
                   value:
                     message: Not Found
                     errors:
-                      - errMsg: "There is no deleted balance history source with the id: 99999999."
+                      - errMsg: "Deleted balance history source 99999999 was not found."
         "429":
           $ref: "#/components/responses/rateLimited"
         "500":
@@ -6869,37 +7012,20 @@ paths:
       tags:
         - balance_history
       summary: Upsert balance history for an account
-      description: >-
-        Upsert one or more historical balance entries for a single manual, Plaid,
-        manual crypto, or deleted acount. Crypto synced accounts require an additional `symbol` path parameter.<br><br>
-
-        The `account_type` path parameter identifies the the type of account and the
-        `account_id` path parameter identifies the specific id for that account type.<br><br>
-
-        Submit one or more entries in the `balances` array. Each entry must specify
-        a `date` and `balance` value.<br><br>
-
-        Balance history is monthly. Each entry's `date` must be the first day of
-        a month and must not be in the future.<br><br>
-
-        `currency` may be provided for any balance entry. If omitted, it defaults
-        to the account currency for manual/Plaid accounts, or the user's primary
-        currency for crypto/deleted accounts.<br><br>
-
-        `symbol` is optional for `crypto_manual` accounts, tolerated for `deleted`
-        accounts, and invalid for `manual` or `plaid` accounts.<br><br>
-
-        `crypto_balance` may be provided for `crypto_manual` and `deleted` accounts,
-        and is invalid for `manual` or `plaid` accounts.<br><br>
-
-        Use `PUT /v2/balance_history/deleted/{account_id}/details` to update
-        deleted-source metadata.
+      description: |-
+        Upsert one or more historical balance entries for a single manual, Plaid, manual crypto, or deleted account. For synced crypto symbol streams, use [PUT /balance_history/crypto_synced/{account_id}/{symbol}](#tag/balance-history/PUT/balance_history/crypto_synced/{account_id}/{symbol}).<br><br>
+        The `account_type` path parameter identifies the account family (`manual`, `plaid`, `crypto_manual`, or `deleted`) and `account_id` identifies the account within that family.<br><br>
+        Submit one or more entries in the `balances` array. Each entry must specify a `month` (YYYY-MM) and `balance` value. `month` must be a past calendar month. The current month cannot be written through this endpoint.<br><br>
+        `currency` may be provided for any balance entry. If omitted, it defaults to the account currency for manual/Plaid accounts, or the user's primary currency for crypto/deleted accounts.<br><br>
+        `symbol` may be set for `crypto_manual` (optional) and `deleted` (tolerated) accounts. Do not provide it for `manual` or `plaid` accounts.<br><br>
+        `crypto_balance` may be provided for `crypto_manual` and `deleted` accounts. It is invalid for `manual` or `plaid` accounts.<br><br>
+        The response contains only the `type: historical` balance entries that were submitted in this request.
       operationId: upsertBalanceHistoryForAccount
       parameters:
         - name: account_type
           in: path
           required: true
-          description: Source family to update. Use `manual`, `plaid`, `crypto_manual`, or `deleted`.
+          description: Account family to update. Use `manual`, `plaid`, `crypto_manual`, or `deleted`.
           schema:
             type: string
             enum: [manual, plaid, crypto_manual, deleted]
@@ -6920,88 +7046,105 @@ paths:
               manual account bulk upsert:
                 value:
                   balances:
-                    - date: "2026-03-01"
+                    - month: "2026-03"
                       balance: "41500.0000"
-                    - date: "2026-04-01"
+                    - month: "2026-04"
                       balance: "41625.5000"
               crypto manual balance with symbol:
                 value:
                   balances:
-                    - date: "2026-03-01"
+                    - month: "2026-03"
                       balance: "56011.1200"
                       symbol: btc
                       crypto_balance: "0.852341920145782301"
               deleted account bulk upsert:
                 value:
                   balances:
-                    - date: "2026-03-01"
+                    - month: "2026-03"
                       symbol: btc
                       crypto_balance: "0.020000000000000000"
                       currency: usd
-                      balance: "1255.0000"
+                      balance: "1255"
               get-shaped balance entry input:
                 value:
                   balances:
                     - id: 601
-                      date: "2026-03-01"
+                      month: "2026-03"
                       balance: "41500.0000"
                       currency: usd
                       to_base: 41500
                       crypto_balance: null
-              partial success request:
-                value:
-                  balances:
-                    - date: "2026-03-01"
-                      balance: "41500.0000"
-                    - date: "2026-04-01"
-                      balance: "41625.5000"
-                      symbol: btc
       responses:
         "200":
-          description: One or more balance history entries were processed
+          description: >-
+            Returns only the `type: historical` entries modified by this request.
+            Other historical entries for the account are omitted from `balances`.
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/upsertBalanceHistoryResponseObject"
+                $ref: "#/components/schemas/balanceHistoryAccountObject"
               examples:
-                balances updated:
+                manual account bulk upsert:
+                  summary: Two upserted entries returned (not full account history)
                   value:
-                    updated_balance_history:
-                      source:
-                        type: manual
-                        manual_account_id: 119807
-                      balances:
-                        - id: 601
-                          date: "2026-03-01"
-                          balance: "41500.0000"
-                          currency: usd
-                          to_base: 41500
-                          crypto_balance: null
-                        - id: 602
-                          date: "2026-04-01"
-                          balance: "41625.5000"
-                          currency: usd
-                          to_base: 41625.5
-                          crypto_balance: null
-                    errors: []
-                partial success:
-                  value:
-                    updated_balance_history:
-                      source:
-                        type: manual
-                        manual_account_id: 119807
-                      balances:
-                        - id: 601
-                          date: "2026-03-01"
-                          balance: "41500.0000"
-                          currency: usd
-                          to_base: 41500
-                          crypto_balance: null
-                    errors:
-                      - request_balances_index: 1
-                        message: "`symbol` may not be set when `account_type` is `manual` or `plaid`."
+                    source:
+                      type: manual
+                      manual_account_id: 119807
+                    balances:
+                      - type: historical
+                        id: 601
+                        month: "2026-03"
+                        balance: "41500.0000"
+                        currency: usd
+                        to_base: 41500
+                        crypto_balance: null
+                      - type: historical
+                        id: 602
+                        month: "2026-04"
+                        balance: "41625.5000"
+                        currency: usd
+                        to_base: 41625.5
+                        crypto_balance: null
+                crypto manual balance with symbol:
+                  summary: Single upserted entry returned
+                  value:
+                    source:
+                      type: crypto_manual
+                      crypto_manual_id: 22001
+                      symbol: btc
+                    balances:
+                      - type: historical
+                        id: 603
+                        month: "2026-03"
+                        balance: "56011.1200"
+                        currency: usd
+                        to_base: 56011.12
+                        crypto_balance: "0.852341920145782301"
+                deleted account bulk upsert:
+                  summary: Single upserted entry returned
+                  value:
+                    source:
+                      type: deleted
+                      deleted_account_id: 91
+                      name: Savings
+                      institution_name: Old Bank
+                      display_name: Closed Savings
+                      account_type: savings
+                      subtype: savings
+                      mask: "1234"
+                      symbol: btc
+                    balances:
+                      - type: historical
+                        id: 504
+                        month: "2026-03"
+                        balance: "1255"
+                        currency: usd
+                        to_base: 1255
+                        crypto_balance: "0.020000000000000000"
         "400":
-          description: Bad Request
+          description: >-
+            Bad Request. If any entry in `balances` fails validation, the entire
+            request is rejected and no entries are updated.
           content:
             application/json:
               schema:
@@ -7012,26 +7155,45 @@ paths:
                     message: Invalid Request Body
                     errors:
                       - errMsg: "Missing required property 'balances' in request body."
+                empty balances array:
+                  value:
+                    message: Invalid Request Body
+                    errors:
+                      - errMsg: "Invalid value for property 'balances'. Array must contain at least 1 element(s)"
                 invalid property:
                   value:
                     message: Invalid Request Body
                     errors:
                       - errMsg: "Invalid property 'foo' in request body."
-                invalid date:
+                invalid month format:
+                  value:
+                    message: Invalid Request Body
+                    errors:
+                      - errMsg: "Invalid value for property 'balances.0.month'. '2026-06-01' is not a valid month in YYYY-MM format."
+                current month:
                   value:
                     message: Request Validation Failure
                     errors:
-                      - errMsg: "`date` must be the first day of a month."
-                future date:
+                      - errMsg: "`month` must not be the current month."
+                        request_balances_index: 0
+                future month:
                   value:
                     message: Request Validation Failure
                     errors:
-                      - errMsg: "`date` must not be in the future."
+                      - errMsg: "`month` must not be in the future."
+                        request_balances_index: 1
                 crypto balance not allowed:
                   value:
                     message: Request Validation Failure
                     errors:
                       - errMsg: "`crypto_balance` may only be set when `account_type` is `crypto_manual` or `deleted`."
+                        request_balances_index: 0
+                invalid entry in bulk request:
+                  value:
+                    message: Request Validation Failure
+                    errors:
+                      - errMsg: "`symbol` may only be set when `account_type` is `crypto_manual` or `deleted`."
+                        request_balances_index: 1
         "401":
           $ref: "#/components/responses/unauthorizedToken"
         "404":
@@ -7052,15 +7214,14 @@ paths:
       tags:
         - balance_history
       summary: Delete all balance history for an account
-      description: >-
-        Delete all historical balance entries for a single manual, Plaid,
-        manual crypto, or deleted account. Crypto synced accounts require an additional `symbol` path parameter.
+      description: |-
+        Delete all historical balance entries for a single manual, Plaid, manual crypto, or deleted account. For synced crypto symbol streams, use [DELETE /balance_history/crypto_synced/{account_id}/{symbol}](#tag/balance-history/DELETE/balance_history/crypto_synced/{account_id}/{symbol}).
       operationId: deleteBalanceHistoryForAccount
       parameters:
         - name: account_type
           in: path
           required: true
-          description: Source family to delete. Use `manual`, `plaid`, `crypto_manual`, or `deleted`.
+          description: Account family to delete. Use `manual`, `plaid`, `crypto_manual`, or `deleted`.
           schema:
             type: string
             enum: [manual, plaid, crypto_manual, deleted]
@@ -7097,16 +7258,10 @@ paths:
       tags:
         - balance_history
       summary: Get balance history for a synced crypto symbol
-      description: >-
-        Retrieve historical balance entries for a single synced crypto symbol stream.<br><br>
-
-        Use the `crypto_synced` account id together with a `symbol` path parameter
-        to select one balance stream within that synced crypto account.<br><br>
-
-        When `start_date` and `end_date` are both provided, they must be first-of-month
-        dates. `start_date` must not be in the future, while `end_date` may be in the future.
-        If one of `start_date` or `end_date` is provided, the other is required. If neither is
-        provided, all available history for the symbol stream is returned.
+      description: |-
+        Retrieve monthly balance history for a single synced crypto symbol stream.<br><br>
+        The path selects one balance stream with a synced crypto account id and `symbol`.<br><br>
+        `start_month`, `end_month`, and current-month entries behave as described in [GET /balance_history](#tag/balance-history/GET/balance_history).
       operationId: getBalanceHistoryForCryptoSynced
       parameters:
         - name: account_id
@@ -7124,23 +7279,27 @@ paths:
             type: string
             minLength: 1
             maxLength: 25
-        - name: start_date
+        - name: start_month
           in: query
-          description: Optional start date for the requested history range in YYYY-MM-DD format. If set, `end_date` is also required. This must be the first day of a month and must not be in the future.
+          description: >-
+            Optional. Same format and constraints as `start_month` on
+            [GET /balance_history](#tag/balance-history/GET/balance_history).
           required: false
           schema:
             type: string
-            format: date
-        - name: end_date
+            pattern: '^\d{4}-(0[1-9]|1[0-2])$'
+        - name: end_month
           in: query
-          description: Optional end date for the requested history range in YYYY-MM-DD format. If set, `start_date` is also required. This must be the first day of a month.
+          description: >-
+            Optional. Same format and constraints as `end_month` on
+            [GET /balance_history](#tag/balance-history/GET/balance_history).
           required: false
           schema:
             type: string
-            format: date
+            pattern: '^\d{4}-(0[1-9]|1[0-2])$'
       responses:
         "200":
-          description: Historical balance entries for the synced crypto symbol stream
+          description: Monthly balance history for the synced crypto symbol stream
           content:
             application/json:
               schema:
@@ -7152,8 +7311,9 @@ paths:
                       crypto_synced_id: 33004
                       symbol: btc
                     balances:
-                      - id: 401
-                        date: "2026-02-01"
+                      - type: historical
+                        id: 401
+                        month: "2026-02"
                         balance: "6231.2800"
                         currency: usd
                         to_base: 6231.28
@@ -7165,16 +7325,16 @@ paths:
               schema:
                 $ref: "#/components/schemas/errorResponseObject"
               examples:
-                missing paired date:
+                missing paired month:
                   value:
                     message: Request Validation Failure
                     errors:
-                      - errMsg: "`start_date` and `end_date` must either both be provided or both be omitted."
-                invalid range:
+                      - errMsg: "`start_month` and `end_month` must either both be provided or both be omitted."
+                invalid month format:
                   value:
-                    message: Request Validation Failure
+                    message: Invalid Request Parameters
                     errors:
-                      - errMsg: "`start_date` must be less than or equal to `end_date`."
+                      - errMsg: "Invalid value for parameter: 'start_month'. '2026-06-01' is not a valid month in YYYY-MM format."
         "401":
           $ref: "#/components/responses/unauthorizedToken"
         "404":
@@ -7193,7 +7353,7 @@ paths:
                   value:
                     message: Not Found
                     errors:
-                      - errMsg: "There is no synced crypto balance history stream for symbol 'doge' on account id: 33004."
+                      - errMsg: "There is no balance history for symbol 'doge' on this account."
         "429":
           $ref: "#/components/responses/rateLimited"
         "500":
@@ -7202,24 +7362,14 @@ paths:
       tags:
         - balance_history
       summary: Upsert balance history for a synced crypto symbol
-      description: >-
-        Upsert one or more historical balance entries for a single synced crypto
-        symbol stream.<br><br>
-
+      description: |-
+        Upsert one or more historical balance entries for a single synced crypto symbol stream.<br><br>
         The path identifies both the synced crypto account and the symbol being updated.<br><br>
-
-        Submit one or more entries in the `balances` array. Each entry must specify
-        a `date` and `balance` value.<br><br>
-
-        Balance history is monthly. Each entry's `date` must be the first day of
-        a month and must not be in the future.<br><br>
-
-        The request body must not include `symbol`; the symbol is supplied by the path.<br><br>
-
-        `currency` may be provided for any balance entry. If omitted, it defaults
-        to the user's primary currency for synced crypto balances.<br><br>
-
-        `crypto_balance` may be provided for synced crypto balances.
+        Submit one or more entries in the `balances` array. Each entry must specify a `month` (YYYY-MM) and `balance` value. `month` must be a past calendar month. The current month cannot be written through this endpoint.<br><br>
+        The request body may include an optional `symbol` on each balance entry. If provided, it must match the `symbol` path parameter. Omit `symbol` to use the path value.<br><br>
+        `currency` may be provided for any balance entry. If omitted, it defaults to the user's primary currency for synced crypto balances.<br><br>
+        `crypto_balance` may be provided for synced crypto balances.<br><br>
+        The response contains only the `type: historical` balance entries that were submitted in this request.
       operationId: upsertBalanceHistoryForCryptoSynced
       parameters:
         - name: account_id
@@ -7247,68 +7397,49 @@ paths:
               synced crypto bulk upsert:
                 value:
                   balances:
-                    - date: "2026-03-01"
+                    - month: "2026-03"
                       balance: "6400.0000"
                       crypto_balance: "0.100020003000400050"
-                    - date: "2026-04-01"
+                    - month: "2026-04"
                       balance: "6500.0000"
                       crypto_balance: "0.100020003000400050"
-              partial success request:
-                value:
-                  balances:
-                    - date: "2026-03-01"
-                      balance: "6400.0000"
-                      crypto_balance: "0.100020003000400050"
-                    - date: "2026-04-01"
-                      balance: "not-a-number"
       responses:
         "200":
-          description: One or more balance history entries were processed
+          description: >-
+            Returns only the `type: historical` entries modified by this request.
+            Other historical entries for the symbol stream are omitted from
+            `balances`.
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/upsertBalanceHistoryResponseObject"
+                $ref: "#/components/schemas/balanceHistoryAccountObject"
               examples:
-                balances updated:
+                synced crypto bulk upsert:
+                  summary: Two upserted entries returned (not full symbol history)
                   value:
-                    updated_balance_history:
-                      source:
-                        type: crypto_synced
-                        crypto_synced_id: 33004
-                        symbol: btc
-                      balances:
-                        - id: 604
-                          date: "2026-03-01"
-                          balance: "6400.0000"
-                          currency: usd
-                          to_base: 6400
-                          crypto_balance: "0.100020003000400050"
-                        - id: 605
-                          date: "2026-04-01"
-                          balance: "6500.0000"
-                          currency: usd
-                          to_base: 6500
-                          crypto_balance: "0.100020003000400050"
-                    errors: []
-                partial success:
-                  value:
-                    updated_balance_history:
-                      source:
-                        type: crypto_synced
-                        crypto_synced_id: 33004
-                        symbol: btc
-                      balances:
-                        - id: 604
-                          date: "2026-03-01"
-                          balance: "6400.0000"
-                          currency: usd
-                          to_base: 6400
-                          crypto_balance: "0.100020003000400050"
-                    errors:
-                      - request_balances_index: 1
-                        message: "`balance` must be a valid numeric string or number."
+                    source:
+                      type: crypto_synced
+                      crypto_synced_id: 33004
+                      symbol: btc
+                    balances:
+                      - type: historical
+                        id: 604
+                        month: "2026-03"
+                        balance: "6400.0000"
+                        currency: usd
+                        to_base: 6400
+                        crypto_balance: "0.100020003000400050"
+                      - type: historical
+                        id: 605
+                        month: "2026-04"
+                        balance: "6500.0000"
+                        currency: usd
+                        to_base: 6500
+                        crypto_balance: "0.100020003000400050"
         "400":
-          description: Bad Request
+          description: >-
+            Bad Request. If any entry in `balances` fails validation, the entire
+            request is rejected and no entries are updated.
           content:
             application/json:
               schema:
@@ -7319,16 +7450,40 @@ paths:
                     message: Invalid Request Body
                     errors:
                       - errMsg: "Missing required property 'balances' in request body."
-                invalid date:
+                empty balances array:
+                  value:
+                    message: Invalid Request Body
+                    errors:
+                      - errMsg: "Invalid value for property 'balances'. Array must contain at least 1 element(s)"
+                invalid month format:
+                  value:
+                    message: Invalid Request Body
+                    errors:
+                      - errMsg: "Invalid value for property 'balances.0.month'. '2026-06-01' is not a valid month in YYYY-MM format."
+                current month:
                   value:
                     message: Request Validation Failure
                     errors:
-                      - errMsg: "`date` must be the first day of a month."
-                future date:
+                      - errMsg: "`month` must not be the current month."
+                        request_balances_index: 0
+                future month:
                   value:
                     message: Request Validation Failure
                     errors:
-                      - errMsg: "`date` must not be in the future."
+                      - errMsg: "`month` must not be in the future."
+                        request_balances_index: 1
+                symbol mismatch:
+                  value:
+                    message: Request Validation Failure
+                    errors:
+                      - errMsg: "`symbol` in request body (doge) does not match the path symbol (eth)."
+                        request_balances_index: 0
+                invalid entry in bulk request:
+                  value:
+                    message: Invalid Request Body
+                    errors:
+                      - errMsg: "`balance` must be a valid numeric string or number."
+                        request_balances_index: 1
         "401":
           $ref: "#/components/responses/unauthorizedToken"
         "404":
@@ -7347,7 +7502,7 @@ paths:
                   value:
                     message: Not Found
                     errors:
-                      - errMsg: "There is no synced crypto balance history stream for symbol 'doge' on account id: 33004."
+                      - errMsg: "There is no balance history for symbol 'doge' on this account."
         "429":
           $ref: "#/components/responses/rateLimited"
         "500":
@@ -7356,11 +7511,9 @@ paths:
       tags:
         - balance_history
       summary: Delete all balance history for a synced crypto symbol
-      description: >-
+      description: |-
         Delete all historical balance entries for a single synced crypto symbol stream.<br><br>
-
-        The path identifies both the synced crypto account and the symbol whose
-        history should be deleted.
+        The path identifies both the synced crypto account and the symbol whose history should be deleted.
       operationId: deleteBalanceHistoryForCryptoSynced
       parameters:
         - name: account_id
@@ -7392,7 +7545,7 @@ paths:
               example:
                 message: Not Found
                 errors:
-                  - errMsg: "There is no synced crypto balance history stream for symbol 'doge' on account id: 33004."
+                  - errMsg: "There is no balance history for symbol 'doge' on this account."
         "429":
           $ref: "#/components/responses/rateLimited"
         "500":
@@ -7402,20 +7555,30 @@ paths:
       tags:
         - balance_history
       summary: Delete a balance history entry
-      description: >-
-        Delete a single monthly balance history entry by its id.
+      description: |-
+        Delete a single stored (`type: historical`) monthly balance history entry by its id. Ephemeral `current` entries cannot be deleted this way.
       operationId: deleteBalanceHistoryEntry
       parameters:
         - name: id
           in: path
           required: true
-          description: Balance history row identifier to delete.
+          description: Historical balance entry identifier to delete.
           schema:
             type: integer
             format: int32
       responses:
         "204":
           description: The balance history entry was deleted
+        "400":
+          description: Bad Request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/errorResponseObject"
+              example:
+                message: Invalid Path Parameters
+                errors:
+                  - errMsg: "Invalid value type for path parameter: 'id'. Expected 'number', received 'string'."
         "401":
           $ref: "#/components/responses/unauthorizedToken"
         "404":
@@ -7437,12 +7600,9 @@ paths:
       tags:
         - balance_history
       summary: Update details for a deleted account
-      description: >-
+      description: |-
         Update archived metadata for a deleted balance history source.<br><br>
-
-        Pass the `deleted` source id returned on `source.deleted_account_id`.
-        This endpoint updates the stored deleted-source metadata used for all
-        historical entries associated with that deleted source.
+        Pass the `deleted_account_id` from a `source.type: deleted` entry. The update applies to all historical entries associated with that deleted source.
       operationId: updateBalanceHistoryDetails
       parameters:
         - name: account_id
@@ -7490,7 +7650,7 @@ paths:
               example:
                 message: Invalid Request Body
                 errors:
-                  - errMsg: "Request body must include at least one of: name, institution_name, display_name, account_type, subtype, mask."
+                  - errMsg: "At least one property must be provided: name, institution_name, display_name, account_type, subtype, mask."
         "401":
           $ref: "#/components/responses/unauthorizedToken"
         "404":
@@ -7502,7 +7662,7 @@ paths:
               example:
                 message: Not Found
                 errors:
-                  - errMsg: "There is no deleted balance history source with the id: 99999999."
+                  - errMsg: "Deleted balance history source 99999999 was not found."
         "429":
           $ref: "#/components/responses/rateLimited"
         "500":
@@ -8516,19 +8676,19 @@ paths:
           description: Sets the maximum number of transactions to return. If
             more match the filter criteria, the response will include a
             `has_more` attribute set to `true`. See
-            [Pagination](https://lm-v2-api-next-a7fabcab8e9a.herokuapp.com/v2/pagination)
+            [Pagination](https://lunchmoney.dev/v2/pagination)
         - name: offset
           in: query
           schema:
             type: integer
           description: Sets the offset for the records returned. This is
             typically set automatically in the header. See
-            [Pagination](https://lm-v2-api-next-a7fabcab8e9a.herokuapp.com/v2/pagination)
+            [Pagination](https://lunchmoney.dev/v2/pagination)
       responses:
         "200":
           description: Returns an array of transactions. <br><br>The `has_more`
             property is set to `true` if more transactions are available. See
-            [Pagination](https://lm-v2-api-next-a7fabcab8e9a.herokuapp.com/v2/pagination)
+            [Pagination](https://lunchmoney.dev/v2/pagination)
           content:
             application/json:
               schema:
@@ -10194,7 +10354,7 @@ paths:
                   description: |
                     The payee for the new grouped transaction.
                   minLength: 0
-                  maxLength: 1000
+
                 category_id:
                   type: integer
                   format: int64
@@ -10209,8 +10369,6 @@ paths:
                   nullable: true
                   description: |
                     Notes for the grouped transaction.
-                  minLength: 0
-                  maxLength: 350
                 status:
                   type: string
                   description: If set, must be either `reviewed` or
@@ -10754,9 +10912,8 @@ paths:
         - transactions (files)
       summary: Attach a file to a transaction
       operationId: attachFileToTransaction
-      description: >-
-        Attaches a file to a transaction. The file must be less than 10MB in size.<br><br>
-        The file will be attached to the transaction and can be downloaded from the link returned by a `GET /transactions/attachments/{file_id}` request.
+      description: |-
+        Attaches a file to a transaction. The file must be less than 10MB in size.<br><br> The file will be attached to the transaction and can be downloaded from the link returned by a `GET /transactions/attachments/{file_id}` request.
       parameters:
         - name: transaction_id
           in: path
@@ -10839,8 +10996,8 @@ paths:
   /transactions/attachments/{file_id}:
     get:
       summary: Get a url to download a file attachment
-      description: Returns a signed url that can be used to download the file
-        attachment.
+      description: |-
+        Returns a signed url that can be used to download the file attachment.
       operationId: getTransactionAttachmentUrl
       tags:
         - transactions (files)
@@ -11573,12 +11730,15 @@ paths:
     get:
       tags:
         - budgets
-      summary: Get budget settings
-      description: Returns the budget-related settings for the user's account.
+      summary: Get budget period settings
+      description: |-
+        Returns budget period and display settings for the budget
+        associated with this API token.<p> These control how budget **periods** are calculated
+        (granularity, anchor date, rollover, and related options).
       operationId: getBudgetSettings
       responses:
         "200":
-          description: Budget settings for the account
+          description: Budget period settings for the current budget
           content:
             application/json:
               schema:
@@ -11601,7 +11761,7 @@ paths:
         Note that `start_date` **must** be a valid budget period start for the account (based on the account's
         budget period settings). If an invalid `start_date` is provided, the request will fail with an error that indicates what the previous and next valid start dates are.<p>
 
-        Use the [budgets/settings](#tag/budgets/GET/budgets/settings) endpoint to view the account's budget settings.<br>
+        Use the [/budgets/settings](#tag/budgets/GET/budgets/settings) endpoint to view the budget period settings for the account.<br>
         To view details for existing budgets, use the [summary](#tag/summary) endpoint.
       operationId: upsertBudget
       requestBody:
@@ -11672,7 +11832,7 @@ paths:
         period settings). If an invalid `start_date` is provided, the request
         will fail with an error that indicates what the previous and next valid
         start dates are.<p> Use the
-        [budgets/settings](#tag/budgets/GET/budgets/settings) endpoint to view
+        [/budgets/settings](#tag/budgets/GET/budgets/settings) endpoint to view
         the account's budget settings.<br> To view details for existing budgets,
         use the [summary](#tag/summary) endpoint.
       operationId: deleteBudget
@@ -11730,4 +11890,3 @@ paths:
 
 security:
   - bearerSecurity: []
-  - cookieAuth: []