npm - @lunch-money/v2-api-spec - Versions diffs - 2.11.0-preview.1 → 2.11.0-preview.10 - Mend

@lunch-money/v2-api-spec 2.11.0-preview.1 → 2.11.0-preview.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/README.md +10 -73
package/lunch-money-api-v2.yaml +300 -250
package/package.json +11 -5
package/version-history.md +9 -1
package/README.md.backup +0 -217
package/update-urls.sh +0 -135

package/lunch-money-api-v2.yaml CHANGED Viewed

@@ -2,50 +2,33 @@ 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.
+    Welcome to the Lunch Money v2 API reference. This is the **v2.11.0** spec.
-    A working version of this API is now available through these docs, or directly at:
+    ### Introduction
-    `https://api.lunchmoney.dev/v2`
+    The API is available at `https://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>
+    API calls can <span class="red-text"><strong>change or delete</strong></span> your data. Any changes you make are <span class="red-text"><strong>permanent</strong></span>, just like they would be if you made changes using the web or mobile app.   Please refer to the [Getting Started Guide](https://lunchmoney.dev/v2/getting-started) before using the API.
-    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).
+    **Static Mock Server**
-    ### Static Mock Server
+    Explore the API without an access token or risk to real data. Select **"Static Mock v2 Lunch Money API Server"** from the Server dropdown, then set your Bearer token to any string with 11 or more characters.
-    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**
+    - [Developer Portal](https://lunchmoney.dev/v2/introduction)
+    - [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
@@ -57,8 +40,8 @@ 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/
+#  - url: https://lunchmoney.dev/v2
+  - url: https://lunchmoney.dev/v2
     description: Static mock version of the v2 Lunch Money API Server
 tags:
@@ -126,8 +109,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 +140,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 +664,6 @@ components:
     cryptoManualObject:
       type: object
       title: manual crypto object
-      x-internal: true
       additionalProperties: false
       properties:
         id:
@@ -719,13 +703,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 +743,7 @@ components:
         - coingecko_id
         - to_base
         - balance_as_of
+        - exchange_rate_as_of
         - created_by_name
         - created_at
         - updated_at
@@ -758,14 +752,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 +781,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 +803,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:
@@ -1072,8 +1079,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
@@ -1353,10 +1368,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,6 +1632,7 @@ components:
       type: object
       description: Source information for a manual account balance history entry.
       additionalProperties: false
+      x-internal: true
       properties:
         type:
           type: string
@@ -1631,6 +1650,7 @@ components:
       type: object
       description: Source information for a Plaid-synced account balance history entry.
       additionalProperties: false
+      x-internal: true
       properties:
         type:
           type: string
@@ -1648,6 +1668,7 @@ components:
       type: object
       description: Source information for a manually-tracked cryptocurrency balance history entry.
       additionalProperties: false
+      x-internal: true
       properties:
         type:
           type: string
@@ -1750,9 +1771,10 @@ 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.
       properties:
@@ -1776,7 +1798,10 @@ components:
               deleted: "#/components/schemas/balanceHistorySourceDeleted"
         balances:
           type: array
-          description: One or more monthly balance history entries for the source account.
+          description: >
+            Monthly balance history entries for the source account. On GET responses,
+            this includes all entries in the requested range. On PUT upsert responses,
+            this includes only the entries modified by that request.
           items:
             $ref: "#/components/schemas/balanceHistoryObject"
       required:
@@ -1787,6 +1812,7 @@ components:
       type: object
       title: balance history entry object
       additionalProperties: false
+      x-internal: true
       description: A historical balance entry for a single account on a single date.
       properties:
         id:
@@ -1800,7 +1826,7 @@ components:
         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 stored 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"
@@ -1847,7 +1873,7 @@ components:
         date:
           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.
+          description: Month to update, in YYYY-MM-DD format. This must be the first day of a month and must be in a past month.
         balance:
           oneOf:
             - type: number
@@ -1898,37 +1924,6 @@ components:
       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
@@ -2467,14 +2462,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 +2485,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 +2720,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 +2861,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 +2933,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 +2959,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
@@ -3117,8 +3096,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 +3278,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:
@@ -3323,7 +3301,6 @@ components:
             format: int32
         notes:
           type: string
-          maxLength: 350
           description: Will inherit notes from parent if not defined.
       required:
         - amount
@@ -3633,10 +3610,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 +3626,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 +3983,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 +4094,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 +4110,7 @@ components:
       #   - `egp`: Egyptian Pound
       #   - `ern`: Eritrean Nakfa
       #   - `etb`: Ethiopian Birr
+      #   - `eth`: Ethereum
       #   - `eur`: Euro
       #   - `fjd`: Fijian Dollar
       #   - `fkp`: Falkland Islands Pound
@@ -4236,10 +4218,13 @@ 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
       #   - `xaf`: CFA Franc BEAC
+      #   - `xag`: Silver (troy ounce)
+      #   - `xau`: Gold (troy ounce)
       #   - `xcd`: East Caribbean Dollar
       #   - `xof`: CFA Franc BCEAO
       #   - `xpf`: CFP Franc
@@ -4277,6 +4262,7 @@ components:
         - cad
         - cdf
         - chf
+        - clf
         - clp
         - cny
         - cop
@@ -4292,6 +4278,7 @@ components:
         - egp
         - ern
         - etb
+        - eth
         - eur
         - fjd
         - fkp
@@ -4399,10 +4386,13 @@ components:
         - uyu
         - uzs
         - vef
+        - ves
         - vnd
         - vuv
         - wst
         - xaf
+        - xag
+        - xau
         - xcd
         - xof
         - xpf
@@ -5901,6 +5891,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"
@@ -5958,6 +5949,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"
@@ -5970,11 +5962,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
@@ -6025,6 +6028,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"
@@ -6102,6 +6106,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"
@@ -6122,6 +6127,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"
@@ -6251,6 +6257,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"
@@ -6258,6 +6265,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
@@ -6273,6 +6281,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"
@@ -6325,6 +6334,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"
@@ -6332,6 +6342,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
@@ -6397,6 +6408,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
@@ -6482,6 +6494,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"
@@ -6489,6 +6502,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"
@@ -6711,7 +6725,7 @@ paths:
                   value:
                     message: Request Validation Failure
                     errors:
-                      - errMsg: "`start_date` must be less than or equal to `end_date`."
+                      - errMsg: "`start_date` must be before or equal to `end_date`."
                 not first of month:
                   value:
                     message: Request Validation Failure
@@ -6837,7 +6851,7 @@ paths:
                   value:
                     message: Request Validation Failure
                     errors:
-                      - errMsg: "`start_date` must be less than or equal to `end_date`."
+                      - errMsg: "`start_date` must be before or equal to `end_date`."
         "401":
           $ref: "#/components/responses/unauthorizedToken"
         "404":
@@ -6856,7 +6870,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":
@@ -6867,29 +6881,29 @@ paths:
       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>
+        manual crypto, or deleted account. Crypto synced accounts require an additional `symbol` path parameter.<br><br>
-        The `account_type` path parameter identifies the the type of account and the
+        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>
         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>
+        a month and must be in a past month.<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>
+        `symbol` may only be set when `account_type` is `crypto_manual` or
+        `crypto_synced`. It is optional for `crypto_manual` accounts and tolerated
+        for `deleted` accounts.<br><br>
-        `crypto_balance` may be provided for `crypto_manual` and `deleted` accounts,
-        and is invalid for `manual` or `plaid` accounts.<br><br>
+        `crypto_balance` may be provided for `crypto_manual`, `crypto_synced`, 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.
+        The response contains only the balance entries that were submitted in this request.
       operationId: upsertBalanceHistoryForAccount
       parameters:
         - name: account_type
@@ -6934,7 +6948,7 @@ paths:
                       symbol: btc
                       crypto_balance: "0.020000000000000000"
                       currency: usd
-                      balance: "1255.0000"
+                      balance: "1255"
               get-shaped balance entry input:
                 value:
                   balances:
@@ -6944,60 +6958,71 @@ paths:
                       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 the modified balance entries only. 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 rows 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:
+                      - 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
+                crypto manual balance with symbol:
+                  summary: Single upserted row returned
+                  value:
+                    source:
+                      type: crypto_manual
+                      crypto_manual_id: 22001
+                      symbol: btc
+                    balances:
+                      - id: 603
+                        date: "2026-03-01"
+                        balance: "56011.1200"
+                        currency: usd
+                        to_base: 56011.12
+                        crypto_balance: "0.852341920145782301"
+                deleted account bulk upsert:
+                  summary: Single upserted row 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:
+                      - id: 504
+                        date: "2026-03-01"
+                        balance: "1255"
+                        currency: usd
+                        to_base: 1255
+                        crypto_balance: "0.020000000000000000"
         "400":
-          description: Bad Request
+          description: Bad Request. The entire request is rejected if any row in
+            `balances` fails validation; no rows are updated.
           content:
             application/json:
               schema:
@@ -7008,6 +7033,11 @@ 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
@@ -7018,16 +7048,26 @@ paths:
                     message: Request Validation Failure
                     errors:
                       - errMsg: "`date` must be the first day of a month."
+                        request_balances_index: 0
+                        code: VALIDATION_ERROR
                 future date:
                   value:
                     message: Request Validation Failure
                     errors:
-                      - errMsg: "`date` must not be in the future."
+                      - errMsg: "`date` must be in a past month."
+                        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`."
+                      - errMsg: "`crypto_balance` may only be set when `account_type` is `crypto_manual`, `crypto_synced`, or `deleted`."
+                        request_balances_index: 0
+                invalid row in bulk request:
+                  value:
+                    message: Request Validation Failure
+                    errors:
+                      - errMsg: "`symbol` may only be set when `account_type` is `crypto_manual` or `crypto_synced`."
+                        request_balances_index: 1
         "401":
           $ref: "#/components/responses/unauthorizedToken"
         "404":
@@ -7170,7 +7210,7 @@ paths:
                   value:
                     message: Request Validation Failure
                     errors:
-                      - errMsg: "`start_date` must be less than or equal to `end_date`."
+                      - errMsg: "`start_date` must be before or equal to `end_date`."
         "401":
           $ref: "#/components/responses/unauthorizedToken"
         "404":
@@ -7189,7 +7229,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":
@@ -7208,14 +7248,18 @@ paths:
         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>
+        a month and must be in a past month.<br><br>
-        The request body must not include `symbol`; the symbol is supplied by the path.<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.
+        `crypto_balance` may be provided for synced crypto balances.<br><br>
+        The response contains only the balance entries that were submitted in this request.
       operationId: upsertBalanceHistoryForCryptoSynced
       parameters:
         - name: account_id
@@ -7249,62 +7293,38 @@ paths:
                     - date: "2026-04-01"
                       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 the modified balance entries only. 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 rows 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:
+                      - 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"
         "400":
-          description: Bad Request
+          description: Bad Request. The entire request is rejected if any row in
+            `balances` fails validation; no rows are updated.
           content:
             application/json:
               schema:
@@ -7315,16 +7335,35 @@ 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 date:
                   value:
                     message: Request Validation Failure
                     errors:
                       - errMsg: "`date` must be the first day of a month."
+                        request_balances_index: 0
                 future date:
                   value:
                     message: Request Validation Failure
                     errors:
-                      - errMsg: "`date` must not be in the future."
+                      - errMsg: "`date` must be in a past month."
+                        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 row in bulk request:
+                  value:
+                    message: Request Validation Failure
+                    errors:
+                      - errMsg: "`balance` must be a valid numeric string or number."
+                        request_balances_index: 1
         "401":
           $ref: "#/components/responses/unauthorizedToken"
         "404":
@@ -7343,7 +7382,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":
@@ -7388,7 +7427,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":
@@ -7412,6 +7451,16 @@ paths:
       responses:
         "204":
           description: The balance history entry was deleted
+        "400":
+          description: Bad Request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/errorResponseObject"
+              example:
+                message: Request Validation Failure
+                errors:
+                  - errMsg: "Invalid value type for path parameter: 'id'. Expected 'number', received 'string'."
         "401":
           $ref: "#/components/responses/unauthorizedToken"
         "404":
@@ -7486,7 +7535,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":
@@ -7498,7 +7547,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":
@@ -8512,19 +8561,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:
@@ -10190,7 +10239,7 @@ paths:
                   description: |
                     The payee for the new grouped transaction.
                   minLength: 0
-                  maxLength: 1000
                 category_id:
                   type: integer
                   format: int64
@@ -10205,8 +10254,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
@@ -11569,12 +11616,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:
@@ -11597,7 +11647,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:
@@ -11668,7 +11718,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