@lunch-money/developer-docs 2.11.0-preview.9 → 2.11.1-docs.1

package/v2/docs/AGENTS.md

@@ -0,0 +1,48 @@
+# V2 documentation instructions
+
+Follow these rules when editing files under `v2/docs` or documenting changes to `v2/spec/lunch-money-api-v2.yaml`.
+
+## Version history
+
+For every consumer-visible spec change, update `v2/docs/version-history.md` under the version being prepared.
+
+Keep entries brief and high level. The version history records what changed; the OpenAPI endpoint documentation describes how to use it.
+
+Include:
+
+- New, renamed, deprecated, or removed endpoints
+- Changes to path or query parameters
+- Changes to request-body properties
+- Changes to response-body properties or shapes
+- Changed status codes, accepted values, defaults, limits, or validation behavior
+- Breaking changes
+
+Do not include:
+
+- Product or implementation rationale
+- Internal implementation details
+- Detailed usage instructions or examples
+- Full schema descriptions
+- Testing, rollout, or cross-repository implementation details
+- Editorial changes that do not alter the documented API contract
+
+### Style
+
+- Name endpoints using the HTTP method and path, such as `GET /balance_history`.
+- Format endpoints, parameter names, property names, schema names, and literal values with backticks.
+- Start bullets with a present-tense verb such as `Add`, `Change`, `Remove`, `Rename`, or `Deprecate`.
+- Prefer one concise bullet for each logical change.
+- Use nested bullets only to list endpoints or closely related property changes.
+- Do not explain why the change was made or provide instructions for adapting to it.
+- Keep unreleased versions marked `TBD`; do not assign a release date without confirmation.
+- Clearly label breaking changes.
+
+## Other documentation
+
+- Do not routinely update `v2/docs/migration-guide.md` or `v2/docs/intro-to-v2.md` for individual spec changes.
+- Determine whether a spec change makes an existing guide factually incorrect, including guides in the shared `docs` directory.
+- Correct an existing guide when it would otherwise contradict the spec.
+- Consider broader documentation only for a reusable cross-endpoint concept that cannot be documented adequately on the affected endpoints.
+- If broader documentation might be useful but is not required for correctness, identify the candidate page and ask the user before expanding it or adding a page.
+- Prefer endpoint descriptions over general guides for endpoint-specific behavior.
+- Do not add detail to the migration guide merely because V2 differs from V1.

package/v2/docs/intro-to-v2.md

@@ -1,4 +1,4 @@
-# v2 API Overview
+# v2 API overview
 
 Welcome to the Lunch Money v2 API. This page covers the core concepts you need to work with the API effectively — authentication, response shapes, naming conventions, error handling, and more. If you're migrating from v1, see the [Migration Guide](./migration-guide.md).
 
@@ -10,7 +10,7 @@ All API requests require a Bearer token in the `Authorization` header:
 Authorization: Bearer YOUR_ACCESS_TOKEN
 ```
 
-Get your access token from the <a href="https://my.lunchmoney.app/developers" target="_blank" rel="noopener noreferrer">Lunch Money developers page</a>. See the [Getting Started guide](/v2/getting-started) for a step-by-step walkthrough including how to create a test budget.
+Get your access token from the <a href="https://my.lunchmoney.app/developers" target="_blank" rel="noopener noreferrer">Lunch Money Developers page</a>. See the [Getting started guide](/getting-started) for a step-by-step walkthrough including how to create a test budget.
 
 ## Base URL
 
@@ -18,7 +18,7 @@ Get your access token from the <a href="https://my.lunchmoney.app/developers" ta
 https://api.lunchmoney.dev/v2
 ```
 
-## Response Shapes
+## Response shapes
 
 The v2 API uses consistent HTTP status codes and response bodies across all endpoints.
 
@@ -39,7 +39,7 @@ All errors return an appropriate 4XX status code — the v2 API never returns an
 | `401` | Unauthorized — missing or invalid Bearer token |
 | `404` | Not Found — the requested object does not exist |
 | `422` | Unprocessable Content — request is valid but cannot be fulfilled (e.g., deleting a category with dependents) |
-| `429` | Too Many Requests — rate limit exceeded; response includes a `Retry-After` header. See the [Rate Limiting guide](/v2/rate-limits). |
+| `429` | Too Many Requests — rate limit exceeded; response includes a `Retry-After` header. See the [Rate limiting guide](/rate-limits). |
 
 All error responses share a consistent body format:
 
@@ -52,7 +52,7 @@ All error responses share a consistent body format:
 }
 ```
 
-> [!NOTE] Atomic Operations
+> [!NOTE] Atomic operations
 > When a request fails, no part of it is applied to your data. For example, if one transaction in a bulk insert has a validation error, none of the transactions in that request are inserted. Fix the errors and retry — you don't need to worry about partial duplicates.
 >
 > If a request has multiple validation errors, the response will attempt to list as many as possible, but it is not guaranteed to catch all errors in a single response.
@@ -61,7 +61,7 @@ All error responses share a consistent body format:
 
 The v2 API validates all requests strictly. A `400` is returned if the request includes unexpected parameters, missing required fields, fields with invalid values, or unexpected properties in the request body. This makes it easier to catch mistakes during development.
 
-## Naming Conventions
+## Naming conventions
 
 Object properties follow consistent rules across the entire API:
 
@@ -72,11 +72,11 @@ Object properties follow consistent rules across the entire API:
 - Child objects of the same type are always in a `children` property
 - All `id` fields are `integer` type (not `number`)
 
-## Amounts, Balances & Sign Convention
+## Amounts, balances & sign convention
 
-The v2 API uses a consistent set of properties — `amount`, `balance`, `currency`, and `to_base` — across all objects that deal with money. See the [Amounts & Balances guide](/v2/amounts-and-balances) for a full explanation of how these properties work, including the sign convention and multi-currency support.
+The v2 API uses a consistent set of properties — `amount`, `balance`, `currency`, and `to_base` — across all objects that deal with money. See the [Amounts & balances guide](/amounts-and-balances) for a full explanation of how these properties work, including the sign convention and multi-currency support.
 
-## Hydrated vs. Non-Hydrated Responses
+## Hydrated vs. non-hydrated responses
 
 In v1, some endpoints returned "hydrated" objects — related object details were embedded directly in the response alongside their IDs. For example, a transaction included `category_name`, `asset_name`, and an array of full tag objects.
 
@@ -93,17 +93,17 @@ In v2, responses are **non-hydrated**: related objects are returned as IDs only.
 
 This improves response times and keeps the API consistent. For apps that need related object details frequently, maintaining a local cache of categories, accounts, and tags is the recommended pattern.
 
-## Updating Objects (PUT)
+## Updating objects (PUT)
 
 Most objects in the v2 API are updatable via `PUT /endpoint/{id}`. The rules are consistent:
 
 - Request bodies may contain any mix of **user-definable** properties (will be updated) and **system-defined** properties like `id` or `created_at` (accepted but ignored).
 - Any unexpected property that is neither user-definable nor system-defined will fail validation and return `400`.
 
-> [!WARNING] Overwrite Behavior
+> [!WARNING] Overwrite behavior
 > Complex properties — objects and arrays — are **replaced entirely** by whatever is in the request body. To add a tag to a transaction without removing existing tags, first fetch the transaction, add the new tag ID to the existing `tag_ids` array, then PUT the full updated array.
 
-> [!TIP] Recommended Pattern
+> [!TIP] Recommended pattern
 > Because system-defined properties are tolerated in PUT requests, you can safely GET an object, modify the properties you want to change, and PUT the whole thing back without stripping system fields first.
 
 ## Versioning

package/v2/docs/migration-guide.md

@@ -99,7 +99,7 @@ One change worth noting: all `id` fields are now explicitly `integer` type (not
 
 #### New Properties
 
-- `debits_as_negative`: A user preference shown in the Lunch Money app. This no longer changes how transaction amounts are represented in the v2 API, but apps may use this setting to display amounts and balances in the way the user prefers. See the [Amounts & Balances guide](/v2/amounts-and-balances) for details.
+- `debits_as_negative`: A user preference shown in the Lunch Money app. This no longer changes how transaction amounts are represented in the v2 API, but apps may use this setting to display amounts and balances in the way the user prefers. See the [Amounts & balances guide](/amounts-and-balances) for details.
 
 <a href="./changelog-visual#user-object-row" target="_blank" rel="noopener noreferrer">View v1/v2 differences</a>
 
@@ -386,7 +386,7 @@ GET /v2/transactions
 > [!WARNING] Behavior Change
 > In the v1 API the optional `debit_as_negative` query parameter could change how transaction amounts were represented. In the v2 API, transaction amount signs are fixed: positive values are debits and negative values are credits. Existing applications that assume positive values are credits need to be updated.
 
-See the [Amounts & Balances guide](/v2/amounts-and-balances) for the full sign convention and how `to_base` works for multi-currency accounts.
+See the [Amounts & balances guide](/amounts-and-balances) for the full sign convention and how `to_base` works for multi-currency accounts.
 
 
 > [!TIP] Migration Tip

package/v2/docs/version-history.md

@@ -5,25 +5,34 @@ The Lunch Money API spec uses a modified version of SEMVER for its versioning me
 - The minor version represents the number of main endpoints the current version of the spec supports.  For example, a version of the API that supports the /me, /categories, and /transactions endpoints would have a minor version of 3.
 - The revision number represents the number of updates since the last endpoint was added.  For example, each time changes are made to one of the existing three APIs as described above, the revision number will be bumped.
 
-## v2.11.0 - TBD
-- Add `GET /balance_history`
-- Add `GET /balance_history/{account_type}/{account_id}`
-- Add `GET /balance_history/crypto_synced/{account_id}/{symbol}`
-- Add `PUT /balance_history/{account_type}/{account_id}`
-- Add `PUT /balance_history/crypto_synced/{account_id}/{symbol}`
-- Add `DELETE /balance_history/entries/{id}`
-- Add `DELETE /balance_history/{account_type}/{account_id}`
-- Add `DELETE /balance_history/crypto_synced/{account_id}/{symbol}`
-- Add `PUT /balance_history/deleted/{account_id}/details`
-- Remove `rollover_pool` from the category object returned in the summary response. It is in the main summary response.
-- It is now possible to set an external_id on any transaction, including those that belong to a Plaid account.
-
-## v2.10.0 - TBD
-- Add v2 crypto endpoints which support:
-  - Discovering the currently supported currencies for manually managed crypto assets
-  - Managing the complete lifecycle of manually managed crypto assets (create, read, update, delete)
-  - Viewing the balances for currencies associated with both manually managed crypto assets and those that are synced via a synced crypto account (ie: coinbase, kraken, ethereum wallet)
-  - Refreshing synced crypto account balances
+## v2.11.1 - Sep 28, 2026
+- Add `GET /me/account/settings` and `PUT /me/account/settings` for account-level settings
+- Add `GET /me/user/settings` and `PUT /me/user/settings` for user-level display and formatting preferences
+- Add `GET /me/user/account/settings` and `PUT /me/user/account/settings` for settings specific to a user and budget account
+- Add `include_pending_in_totals` to `GET /me/account/settings` and `PUT /me/account/settings`
+- Add `default_manual_account_id` to `GET /me/user/account/settings` and `PUT /me/user/account/settings`
+- Document `GET /budgets/settings` response schema publicly; change `budget_period_quantity` to integer
+
+## v2.11.0 - Jul 31, 2026
+- Add `/balance_history` endpoints:
+  - `GET /balance_history`
+  - `GET /balance_history/{account_type}/{account_id}`
+  - `GET /balance_history/crypto_synced/{account_id}/{symbol}`
+  - `PUT /balance_history/{account_type}/{account_id}`
+  - `PUT /balance_history/crypto_synced/{account_id}/{symbol}`
+  - `DELETE /balance_history/entries/{id}`
+  - `DELETE /balance_history/{account_type}/{account_id}`
+  - `DELETE /balance_history/crypto_synced/{account_id}/{symbol}`
+  - `PUT /balance_history/deleted/{account_id}/details`
+- Remove `rollover_pool` from category objects in the `GET /summary` response
+- Allow setting `external_id` on Plaid-account transactions
+- Allow `null` for `category_id` and `notes` on split children to clear those values instead of inheriting from the parent
+
+## v2.10.0 - Jul 31, 2026
+- Add crypto endpoints:
+  - `GET /cryptocurrencies`
+  - `GET /crypto/manual`, `POST /crypto/manual`, `GET /crypto/manual/{id}`, `PUT /crypto/manual/{id}`, `DELETE /crypto/manual/{id}`
+  - `GET /crypto/synced`, `GET /crypto/synced/{id}`, `GET /crypto/synced/{id}/{symbol}`, `POST /crypto/synced/{id}/refresh`
 
 ## v2.9.4 - May 23, 2026
 - Increase allowable length for transaction `notes`.

package/v2/spec/AGENTS.md

@@ -0,0 +1,75 @@
+# Repository instructions
+
+## V2 OpenAPI conventions
+
+Follow these rules whenever editing `v2/spec/lunch-money-api-v2.yaml`:
+
+### Component schemas
+
+- Define request and response object payloads as named schemas under `components.schemas`.
+- Reference those component schemas from path operations with `$ref`; do not define object payload schemas inline under `paths`.
+- Give every property in a referenced component schema a description, including wrapper properties, nested objects, array properties, and properties whose shape is supplied by `$ref`.
+- Use a property's description to explain its role in the containing object; do not assume the referenced schema's description provides that context.
+- Give every schema displayed in Scalar's Models section a top-level description.
+- A schema hidden from the Models section does not require a top-level description when its purpose is already clear at every reference site. Add one when it defines reusable semantics or constraints not explained by the referencing property, request body, or response.
+- Remove unreferenced component schemas unless they are intentionally retained for a documented reason.
+
+### Scalar model visibility
+
+`x-internal: true` hides a component schema from Scalar's Models section. It does not mean the endpoint, payload, or data is private.
+
+- Keep primary response-body schemas public by omitting `x-internal` or setting it to `false`.
+- Set `x-internal: true` on request-only schemas and supporting schemas that are not useful as independently browsable models.
+- Keep a shared schema public when it is a useful response model, even if requests or other schemas also reference it.
+- Decide visibility from how the schema is used, not from its name.
+
+### Endpoint documentation
+
+- Give every operation a concise `summary` and a `description`.
+- Give every path, query, and header parameter a description.
+- Give every response entry a meaningful description.
+- Document endpoint-specific behavior, defaults, side effects, and request or response semantics on the operation or relevant field rather than in a general guide.
+
+### Description style
+
+- Use direct, neutral, present-tense language from the API consumer's perspective.
+- Use a sentence fragment for a short label or noun phrase, without a terminal period.
+- Use complete sentences for behavior or semantics, with terminal punctuation.
+- When a description contains multiple sentences, punctuate every sentence.
+- Use backticks for property names, parameter names, enum values, and literal values such as `true`, `false`, and `null`.
+- Do not repeat type information unless it clarifies a format, unit, constraint, or semantic detail.
+- Add links when they materially help consumers discover a related endpoint or relevant guide.
+- Do not add links that merely restate obvious navigation.
+
+### Examples
+
+Examples are selective documentation aids, not a required artifact for every spec change.
+
+- Audit affected examples whenever an endpoint, schema, or behavior changes, but edit them only when they become invalid, inaccurate, or misleading.
+- Add an example when it illustrates a new endpoint, a materially different payload shape, or behavior not already clear from the schema and descriptions.
+- Do not add examples mechanically for changes that widen accepted values, such as allowing an optional property to be `null`, when existing examples remain valid and the schema and description explain the behavior.
+- Changes to a type, format, enum, requiredness, default, or representation require examining every affected example. Edit only examples that use or imply the old contract.
+- A new endpoint should normally include a minimal valid request example when it accepts a JSON body and a representative success example when it returns a JSON body. Ask the user before omitting examples when the reason is unclear.
+- When uncertain whether a change benefits from a new example, ask the user rather than adding one speculatively.
+- Put request examples under the request media type, response examples under the applicable status code and media type, and parameter examples on the parameter.
+- Use schema-property examples sparingly for unusual formats or values that are difficult to infer.
+- Use `example` for one representative scenario and `examples` for materially different scenarios.
+- Keep examples concise, fictional, internally consistent, and valid against the applicable schema.
+- Include required properties. Include optional properties only when they help explain the scenario.
+- Give named examples concise, accurate scenario keys. Add a `summary` or `description` only when it contributes information beyond the key and payload.
+- Add endpoint-specific error examples only when the error shape or behavior differs meaningfully from shared standard errors.
+
+#### Paired request and response examples
+
+Pair request and response examples when seeing the result helps explain a synchronous create or update operation.
+
+- Use the same scenario key under the request and corresponding response.
+- Carry submitted values through consistently; use the response to show generated IDs, timestamps, defaults, conversions, inherited values, or other returned fields.
+- Pair invalid request examples with the applicable error response using the same scenario key.
+- Do not pair every request scenario. Add a pair only when the response teaches something useful.
+- Treat singular request and response `example` blocks as an implicit pair and keep shared values consistent.
+- Do not pair examples when the response has no body, processing is asynchronous, or the result does not directly correspond to the submitted payload.
+
+When planning or reviewing a spec change, identify the affected schemas, verify their Scalar visibility and descriptions, and audit related request, response, parameter, and error examples. Record example changes only when existing examples become inaccurate or a new scenario materially improves the documentation. When in doubt, ask the user.
+
+Before finishing a consumer-visible spec change, follow `../docs/AGENTS.md` to add a concise version-history entry and check whether an existing guide has become factually incorrect.