@lunch-money/developer-docs 2.11.1-preview.8 → 2.11.1

package/docs/STYLE_GUIDE.md

@@ -0,0 +1,84 @@
+# Documentation style guide
+
+Use this guide for hand-written Markdown in `docs/` and `v2/docs/`. Preserve
+intentional conventions in generated pages, the v1 Slate reference, and version
+history entries.
+
+## Voice and structure
+
+- Address the reader as “you” and use direct, practical language.
+- Start with the reader's goal before introducing protocol or API details.
+- Use one H1 per page and keep heading levels in logical order.
+- Use sentence case for prose headings. Preserve official names, initialisms,
+  endpoint paths, property names, and exact UI labels.
+- Add a next step when a guide belongs to a longer reader journey. Use
+  `## Need help?` only when the page provides support options.
+
+## Terminology
+
+- Use “Lunch Money” for the product and “Lunchbag Labs, Inc.” only when the
+  legal company name is required.
+- Use “Developer Portal,” “Developers page,” and “API reference” consistently.
+  Preserve different capitalization only for an exact UI label.
+- Write “v1” and “v2” in prose. Use “V2 API” only where it is an established
+  proper label, such as the rendered reference title.
+- Distinguish authentication from authorization, personal access tokens from
+  OAuth access tokens, and applications from their registered OAuth clients.
+
+## Code and placeholders
+
+- Format endpoints, properties, headers, status codes, commands, filenames,
+  scope names, and literal values as code.
+- Use `YOUR_ACCESS_TOKEN` as the generic access-token placeholder. Environment
+  variable examples may use `LUNCH_MONEY_ACCESS_TOKEN`.
+- For equivalent multi-language examples, order tabs as JavaScript/Node.js,
+  Python, then cURL. Comparison tabs may follow the order that best teaches the
+  difference.
+- Keep examples fictional and never include or request real credentials.
+
+## Callouts
+
+Use the supported blockquote form:
+
+```markdown
+> [!NOTE] Optional title
+> Supporting content.
+```
+
+- Use `NOTE` for context that affects understanding.
+- Use `TIP` for optional advice or a more effective workflow.
+- Use `WARNING` for credible security, privacy, data-loss, breaking-change, or
+  operational risk.
+- Use sentence case for optional callout titles. Do not use HTML line breaks to
+  separate callout paragraphs.
+
+## Tabs
+
+Use tabs when equivalent examples in multiple languages or a focused comparison
+are easier to understand together:
+
+```markdown
+:::tabs
+@tab JavaScript/Node.js
+JavaScript example
+
+@tab Python
+Python example
+:::
+```
+
+Use an `@tab` label for each panel and close the container with `:::`. For
+equivalent language examples, order tabs as JavaScript/Node.js, Python, then
+cURL. Comparison tabs may use the order that best teaches the difference.
+
+## Links and presentation
+
+- Use canonical documentation paths from `manifest.json`. Keep aliases only for
+  compatibility; do not introduce new links to aliases.
+- Use normal Markdown links for internal navigation. Keep HTML only when it adds
+  behavior Markdown cannot express, such as opening an external link in a new
+  tab.
+- Avoid deeply nested headings, very wide tables, and long unbroken text that is
+  difficult to use in the constrained content column.
+- Remove trailing whitespace and use blank lines, not `<br>`, for Markdown
+  structure unless a verified rendering requirement needs HTML.

package/docs/amounts-and-balances.md

@@ -1,4 +1,4 @@
-# Amounts & Balances
+# Amounts & balances
 
 The Lunch Money API uses four properties — `amount`, `balance`, `currency`, and `to_base` — consistently across all objects that deal with money. Understanding how they work will help you build accurate, multi-currency-aware integrations.
 
@@ -24,7 +24,7 @@ Like `amount`, `balance` is always in the `currency` of the same object and foll
 
 ## `currency`
 
-`currency` is an ISO 4217 currency code (e.g., `"usd"`, `"eur"`, `"gbp"`). It is present on every object that carries an `amount` or `balance` and tells you what currency those values are in. See the [Supported Currencies guide](/v2/currencies) for the full list.
+`currency` is an ISO 4217 currency code (e.g., `"usd"`, `"eur"`, `"gbp"`). It is present on every object that carries an `amount` or `balance` and tells you what currency those values are in. See the [Supported currencies guide](/currencies) for the full list.
 
 ## `to_base`
 
@@ -42,7 +42,7 @@ Like `amount`, `balance` is always in the `currency` of the same object and foll
 - Display amounts and balances in a single consistent currency across a multi-currency account
 - Perform arithmetic across transactions or accounts in different currencies
 
-## Sign Convention
+## Sign convention
 
 ### Transaction amounts
 
@@ -70,10 +70,10 @@ A negative balance indicates the reversed state for that account type:
 - A savings account in overdraft has a negative `balance`
 - A credit card where the issuer owes you money (e.g., after a refund or overpayment) has a negative `balance`
 
-> [!NOTE] App Display Setting
+> [!NOTE] App display setting
 > The Lunch Money app has a setting — **"Show Debits as Negative, Credits as Positive"** — that can flip how amounts are displayed in the UI. This setting is exposed in the API as `debits_as_negative` on the User object. **It has no effect on the API.** The API always returns positive values for debits and negative values for credits regardless of this setting. Apps may read `debits_as_negative` to match the user's preferred display format when showing amounts in their own UI.
 
-## Exception: Budget and Summary Amounts
+## Exception: budget and summary amounts
 
 Budget objects and summary response objects don't use the transaction sign convention. Direction is conveyed by the **structure of the response** rather than the sign of the value — amounts are always positive magnitudes, and the object type or category flag tells you whether that activity is income or expense.
 

package/docs/branding-your-app.md

@@ -1,9 +1,9 @@
-# Branding your App
+# Branding your app
 
 Building a tool, plugin, or integration on top of Lunch Money? Use the official **Powered by Lunch Money** badge to credit the connection clearly — without implying that your app *is* Lunch Money.
 
 <a href="https://lunchmoney.app/assets/images/media-kit/powered-by-lunch-money-badge.png" download="powered-by-lunch-money-badge.png" target="_blank" rel="noopener noreferrer" title="Download Powered by Lunch Money badge">
-  <img src="/v2/images/powered-by-lunch-money-badge.png" alt="Powered by Lunch Money badge" />
+  <img src="/v2/images/powered-by-lunch-money-badge.png" alt="Powered by Lunch Money badge" width="320" />
 </a>
 
 > [!TIP]

package/docs/currencies.md

@@ -1,15 +1,15 @@
-# Supported Currencies
+# Supported currencies
 
 Lunch Money supports a wide range of currencies for transactions and accounts. All currency values in the API use three-letter lowercase currency codes in ISO 4217 format.
 
-## Currency Code Format
+## Currency code format
 
 Currency codes must be:
 - Three letters
 - Lowercase
 - Valid ISO 4217 currency codes
 
-## Supported Currencies
+## Supported currencies
 
 The following currencies are currently supported in Lunch Money:
 
@@ -183,7 +183,7 @@ The following currencies are currently supported in Lunch Money:
 | `zmw` | Zambian Kwacha |
 | `zwl` | Zimbabwean Dollar |
 
-## Using Currencies in the API
+## Using currencies in the API
 
 When creating or updating transactions, accounts, or other resources that include currency information, use the three-letter lowercase currency code:
 
@@ -247,11 +247,11 @@ curl -X POST 'https://api.lunchmoney.dev/v2/transactions' \
 ```
 :::
 
-## Default Currency
+## Default currency
 
 If you don't specify a currency when creating a transaction or account, Lunch Money will default to your account's primary currency. You can check your primary currency by calling the `GET /v2/me` endpoint.
 
-## Currency Validation
+## Currency validation
 
 The API validates that currency codes match the supported list. If you provide an unsupported currency code, you'll receive a validation error:
 
@@ -268,10 +268,9 @@ The API validates that currency codes match the supported list. If you provide a
 }
 ```
 
-## Requesting New Currencies
+## Requesting new currencies
 
 If your currency is missing from the supported list, please let us know via email at [support@lunchmoney.app](mailto:support@lunchmoney.app) and we'll work on getting it added.
 
-> [!NOTE] Currency Support
+> [!NOTE] Currency support
 > Currency support is continuously expanding. If you need a currency that's not currently listed, reach out to our support team and we'll prioritize adding it.
-

package/docs/getting-started.md

@@ -1,14 +1,14 @@
-# Getting Started with the API
+# Getting started with the API
 
 Welcome to the Lunch Money developer API! This API has enabled the Lunch Money user community to build a broad set of tools and plug-ins to complement their Lunch Money experience and help other users. This guide will help you get started using the Lunch Money API.
 
 Most users interact with their Lunch Money data using the official web or mobile app. Making API calls is another way to interact with your Lunch Money data. You can make API calls that **get** your data for you, allowing you to do other things with it, like generating your own charts or simply archiving your data. You can also make API calls that **change** or **delete** your data. Any changes you make are permanent, just like they would be if you made changes using the web or mobile app.
 
 > [!WARNING]
-> Changes made via the API are permanent and cannot be undone!<br> Always use a test budget when getting started.
+> Changes made via the API are permanent and cannot be undone. Always use a test budget when getting started.
 
 
-## Create a Test Budgeting Account
+## Create a test budgeting account
 
 Since changes to your data made by the API are permanent, the best way to begin interacting with the API is to <a href="https://support.lunchmoney.app/miscellaneous/unlimited-budgeting-accounts" target="_blank" rel="noopener noreferrer">create a new test budgeting account</a> in your existing Lunch Money account. As you start using the API, you can interact with this test account and ensure that your real data is not modified.
 
@@ -49,7 +49,7 @@ After you do this, the web page will show you a long alphanumeric string. This i
 Congratulations! You've got an access token and are ready to make an API request! Later, when you are more comfortable with the API, you can repeat this process to create a new access token associated with your real budget.
 
 > [!WARNING]
-> Treat your access tokens like passwords.<br>Don't share them with anyone that you don't trust. 
+> Treat your access tokens like passwords. Don't share them with anyone you don't trust.
 
 If you ever worry that your access token has been compromised, you can always come back to the Developers page and hit the Revoke button.
 
@@ -63,21 +63,21 @@ When you start to write code that makes API calls, you will need to include this
 
 ```bash
 curl --location 'https://api.lunchmoney.dev/v2/me' \
---header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>'
+--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
 ```
 
-If this doesn't make sense yet, that's OK! 
+If this doesn't make sense yet, that's OK!
 
-There is an easier way to use your access token to make requests. Head over to the [API Reference Documentation](/v2/docs). 
+There is an easier way to use your access token to make requests. Head over to the [API Reference Documentation](/v2/docs).
 
 :::tabs
 
 @tab 1. Supply Your Token
-Paste your new token into the box that says "Bearer Token" in the server configuration in the upper right hand corner. 
+Paste your new token into the box that says "Bearer Token" in the server configuration in the upper right hand corner.
 ![Bearer Token](/images/PasteBearer.png)
 
 @tab 2. Make a Test Request
-Scroll down to the section called "Get Current User" and hit the "Test Request" button. 
+Scroll down to the section called "Get Current User" and hit the "Test Request" button.
 ![TestRequest.png](/images/TestRequest.png)
 :::
 
@@ -85,14 +85,14 @@ This will pop up a dialog box that you can use to send an API request. This is a
 
 From here, you can explore the rest of the Lunch Money API and start thinking about what you might do with it.
 
-## What Can You Build?
+## What can you build?
 
 The Lunch Money community has already built a wide variety of tools — automations, importers, dashboards, and more. Check out the <a href="https://lunchmoney.app/developers#community-projects" target="_blank" rel="noopener noreferrer">Developer Tools & Community Projects</a> list for inspiration, or drop by the <a href="https://discord.com/channels/842337014556262411/1134597088504729780" target="_blank" rel="noopener noreferrer">Show and Tell channel</a> on Discord to see what others are sharing.
 
 > [!NOTE]
 > Built something with the API? Let us know and we'll add it to the list!
 
-## I still need help!
+## Need help?
 
 If you still aren't sure how to get started, we have other resources to help.
 

package/docs/introduction.md

@@ -2,7 +2,7 @@
 
 Welcome to the Lunch Money developer documentation. This site covers the **v2 API** — the current generation of the Lunch Money API — along with guides, a reference for the legacy v1 API, and tools for exploring the API without touching real data.
 
-## Getting Started
+## Getting started
 
 The v2 API is available at:
 
@@ -16,9 +16,9 @@ Get your access token from the <a href="https://my.lunchmoney.app/developers" ta
 Authorization: Bearer YOUR_ACCESS_TOKEN
 ```
 
-See the [Getting Started guide](/v2/getting-started) for a full walkthrough, including how to create a test budget and make your first request.
+See the [Getting started guide](/getting-started) for a full walkthrough, including how to create a test budget and make your first request.
 
-## Trying the API Without Real Data
+## Trying the API without real data
 
 The <a href="/v2/docs">interactive API reference</a> lets you make live API requests directly from the documentation — including a **static mock server** you can use to explore the API without an access token or any risk to real data.
 
@@ -34,7 +34,7 @@ Set your Bearer Token to any string of **11 or more characters** — no real tok
 
 :::
 
-## Client Libraries & SDKs
+## Client libraries & SDKs
 
 An official **TypeScript SDK** is available:
 - NPM: <a href="https://www.npmjs.com/package/@lunch-money/v2-api-spec" target="_blank" rel="noopener noreferrer">`@lunch-money/v2-api-spec`</a>
@@ -58,6 +58,6 @@ Join the conversation in the <a href="https://lunchmoney.app/discord" target="_b
 
 **Useful links:**
 - <a href="/v2/docs">Interactive API Reference</a>
-- [Getting Started Guide](/v2/getting-started)
+- [Getting started guide](/getting-started)
 - <a href="https://github.com/lunch-money/awesome-lunchmoney" target="_blank" rel="noopener noreferrer">Awesome Lunch Money Projects</a>
 - [Contact: devsupport@lunchmoney.app](mailto:devsupport@lunchmoney.app)

package/docs/locales.md

@@ -1,4 +1,4 @@
-# Supported Locales
+# Supported locales
 
 Lunch Money uses locale tags to format numbers and currency amounts in the web
 and mobile apps. Date presentation is controlled separately by the user-level
@@ -10,14 +10,14 @@ currency symbol or code placement and rendering. It does not change the
 account's selected currency, numeric values, or the representation of dates,
 numbers, and amounts in API responses.
 
-## Locale Tag Format
+## Locale tag format
 
 Each supported value combines a language code and a region code, separated by a
 hyphen. For example, `en-US` selects English formatting conventions for the
 United States, while `en-GB` selects English formatting conventions for the
 United Kingdom.
 
-## Supported Locales
+## Supported locales
 
 The examples format `123456789` as USD. An account's primary currency determines
 the currency symbol and number of fraction digits. Exact spacing and symbol
@@ -111,7 +111,7 @@ implementation.
 | `uk-UA` | Ukrainian | Ukraine | `123 456 789,00 USD` |
 | `vi-VN` | Vietnamese | Vietnam | `123.456.789,00 US$` |
 
-## Legacy Locale Tags
+## Legacy locale tags
 
 The supported list retains two legacy language codes for compatibility:
 

package/docs/pagination.md

@@ -6,10 +6,10 @@ The Lunch Money API uses offset-based pagination for the `GET /transactions` end
 
 When retrieving transactions using `GET /transactions`, the API supports pagination through the `limit` and `offset` query parameters. By default, the endpoint returns up to 1000 transactions per request. If more transactions match your filter criteria, the response includes a `has_more` property set to `true`, indicating that additional pages are available.
 
-> [!NOTE] Pagination Scope
+> [!NOTE] Pagination scope
 > Pagination works with all filter parameters including date ranges, account IDs, categories, tags, and status filters. The pagination applies to the filtered result set.
 
-## How Pagination Works
+## How pagination works
 
 ### Parameters
 
@@ -24,13 +24,13 @@ When retrieving transactions using `GET /transactions`, the API supports paginat
   - Minimum: `0`
   - Use this to fetch subsequent pages of results
 
-### Response Property
+### Response property
 
 - **`has_more`**: A boolean property in the response indicating whether more transactions are available
   - `true`: More transactions match your filter criteria and are available on subsequent pages
   - `false`: All matching transactions have been returned
 
-### Basic Pagination Flow
+### Basic pagination flow
 
 1. Make your first request (optionally with `limit` specified, defaults to 1000)
 2. Check the `has_more` property in the response
@@ -39,7 +39,7 @@ When retrieving transactions using `GET /transactions`, the API supports paginat
 
 ## Examples
 
-### Basic Pagination
+### Basic pagination
 
 Here's how to fetch transactions page by page:
 
@@ -61,10 +61,10 @@ async function getAllTransactions(accessToken, limit = 1000) {
 
     const data = await response.json();
     allTransactions.push(...data.transactions);
-    
+
     hasMore = data.has_more;
     offset += limit;
-    
+
     console.log(`Fetched ${data.transactions.length} transactions (total: ${allTransactions.length})`);
   }
 
@@ -84,22 +84,22 @@ def get_all_transactions(access_token, limit=1000):
     all_transactions = []
     offset = 0
     has_more = True
-    
+
     headers = {
         'Authorization': f'Bearer {access_token}'
     }
-    
+
     while has_more:
         url = f'https://api.lunchmoney.dev/v2/transactions?limit={limit}&offset={offset}'
         response = requests.get(url, headers=headers)
         data = response.json()
-        
+
         all_transactions.extend(data['transactions'])
         has_more = data['has_more']
         offset += limit
-        
+
         print(f"Fetched {len(data['transactions'])} transactions (total: {len(all_transactions)})")
-    
+
     return all_transactions
 
 # Usage
@@ -119,18 +119,18 @@ ALL_TRANSACTIONS="[]"
 
 while [ "$HAS_MORE" = "true" ]; do
   echo "Fetching transactions with offset=$OFFSET, limit=$LIMIT..."
-  
+
   RESPONSE=$(curl -s -X GET \
     "https://api.lunchmoney.dev/v2/transactions?limit=$LIMIT&offset=$OFFSET" \
     -H "Authorization: Bearer $ACCESS_TOKEN")
-  
+
   TRANSACTIONS=$(echo $RESPONSE | jq -r '.transactions')
   HAS_MORE=$(echo $RESPONSE | jq -r '.has_more')
-  
+
   # Merge transactions (simplified - in practice you'd want proper JSON merging)
   COUNT=$(echo $TRANSACTIONS | jq 'length')
   echo "Fetched $COUNT transactions"
-  
+
   OFFSET=$((OFFSET + LIMIT))
 done
 
@@ -138,7 +138,7 @@ echo "All transactions fetched"
 ```
 :::
 
-### Pagination with Date Filters
+### Pagination with date filters
 
 Pagination works seamlessly with date range filters:
 
@@ -166,7 +166,7 @@ async function getTransactionsByDateRange(accessToken, startDate, endDate) {
 
     const data = await response.json();
     allTransactions.push(...data.transactions);
-    
+
     hasMore = data.has_more;
     offset += limit;
   }
@@ -192,9 +192,9 @@ def get_transactions_by_date_range(access_token, start_date, end_date):
     offset = 0
     has_more = True
     limit = 1000
-    
+
     headers = {'Authorization': f'Bearer {access_token}'}
-    
+
     while has_more:
         params = {
             'start_date': start_date,
@@ -202,15 +202,15 @@ def get_transactions_by_date_range(access_token, start_date, end_date):
             'limit': limit,
             'offset': offset
         }
-        
+
         url = f"https://api.lunchmoney.dev/v2/transactions?{urlencode(params)}"
         response = requests.get(url, headers=headers)
         data = response.json()
-        
+
         all_transactions.extend(data['transactions'])
         has_more = data['has_more']
         offset += limit
-    
+
     return all_transactions
 
 # Usage: Get all transactions for January 2024
@@ -236,17 +236,17 @@ while [ "$HAS_MORE" = "true" ]; do
   RESPONSE=$(curl -s -X GET \
     "https://api.lunchmoney.dev/v2/transactions?start_date=$START_DATE&end_date=$END_DATE&limit=$LIMIT&offset=$OFFSET" \
     -H "Authorization: Bearer $ACCESS_TOKEN")
-  
+
   HAS_MORE=$(echo $RESPONSE | jq -r '.has_more')
   COUNT=$(echo $RESPONSE | jq -r '.transactions | length')
   echo "Fetched $COUNT transactions (offset=$OFFSET)"
-  
+
   OFFSET=$((OFFSET + LIMIT))
 done
 ```
 :::
 
-### Handling the `has_more` Flag
+### Handling the `has_more` flag
 
 Always check the `has_more` property to determine if you need to fetch more pages:
 
@@ -262,7 +262,7 @@ async function fetchTransactionsPage(accessToken, limit = 1000, offset = 0) {
   });
 
   const data = await response.json();
-  
+
   return {
     transactions: data.transactions,
     hasMore: data.has_more,
@@ -288,10 +288,10 @@ import requests
 def fetch_transactions_page(access_token, limit=1000, offset=0):
     url = f'https://api.lunchmoney.dev/v2/transactions?limit={limit}&offset={offset}'
     headers = {'Authorization': f'Bearer {access_token}'}
-    
+
     response = requests.get(url, headers=headers)
     data = response.json()
-    
+
     return {
         'transactions': data['transactions'],
         'has_more': data['has_more'],
@@ -335,9 +335,9 @@ fi
 ```
 :::
 
-## Best Practices
+## Best practices
 
-### 1. Use Appropriate Limit Values
+### 1. Use appropriate limit values
 
 Choose a `limit` value that balances performance and number of requests:
 
@@ -353,7 +353,7 @@ const response = await fetch('/v2/transactions?limit=1000');
 const response = await fetch('/v2/transactions?limit=500');
 ```
 
-### 2. Always Check `has_more`
+### 2. Always check `has_more`
 
 Don't assume you've received all results. Always check the `has_more` property:
 
@@ -375,7 +375,7 @@ while (hasMore) {
 }
 ```
 
-### 3. Combine with Date Ranges When Possible
+### 3. Combine with date ranges when possible
 
 If you know the date range you need, use `start_date` and `end_date` parameters to reduce the result set size:
 
@@ -387,12 +387,12 @@ const response = await fetch(
 
 // ❌ Less efficient: Fetches all transactions then filters client-side
 const allTransactions = await fetchAllTransactions();
-const janTransactions = allTransactions.filter(t => 
+const janTransactions = allTransactions.filter(t =>
   t.date >= '2024-01-01' && t.date <= '2024-01-31'
 );
 ```
 
-### 4. Handle Edge Cases
+### 4. Handle edge cases
 
 - **Empty results**: The `transactions` array will be empty, and `has_more` will be `false`
 - **Exact page boundary**: If the number of results is exactly divisible by your limit, `has_more` will be `false` on the last page
@@ -406,24 +406,24 @@ async function safeFetchTransactions(accessToken, limit = 1000, offset = 0) {
       headers: { 'Authorization': `Bearer ${accessToken}` }
     }
   );
-  
+
   if (!response.ok) {
     throw new Error(`API error: ${response.status}`);
   }
-  
+
   const data = await response.json();
-  
+
   // Handle empty results
   if (data.transactions.length === 0 && !data.has_more) {
     console.log('No transactions found');
     return [];
   }
-  
+
   return data;
 }
 ```
 
-### 5. Implement Rate Limit Awareness
+### 5. Implement rate limit awareness
 
 When paginating through many pages, be mindful of rate limits. Consider adding delays between requests:
 
@@ -439,7 +439,7 @@ async function getAllTransactionsWithRateLimit(accessToken) {
     allTransactions.push(...data.transactions);
     hasMore = data.has_more;
     offset += limit;
-    
+
     // Small delay to avoid hitting rate limits
     if (hasMore) {
       await new Promise(resolve => setTimeout(resolve, 100));
@@ -452,7 +452,7 @@ async function getAllTransactionsWithRateLimit(accessToken) {
 
 ## Troubleshooting
 
-### Common Issues
+### Common issues
 
 **Issue**: Getting duplicate transactions across pages
 
@@ -506,7 +506,7 @@ const data = await fetch('/v2/transactions?start_date=2024-01-01&end_date=2024-0
 // data.transactions.length might be 200, and has_more will be false
 ```
 
-## Need Help?
+## Need help?
 
 If you're experiencing pagination issues that can't be resolved through the techniques described above:
 
@@ -514,4 +514,3 @@ If you're experiencing pagination issues that can't be resolved through the tech
 - Verify that you're checking the `has_more` property on each response
 - Consider using date range filters to reduce the result set size
 - [Email our developer advocate](mailto:jp@lunchmoney.app) if you need assistance with pagination implementation
-

package/docs/rate-limiting.md

@@ -1,4 +1,4 @@
-# Rate Limiting
+# Rate limiting
 
 The Lunch Money API implements rate limiting to ensure fair usage and prevent abuse of API resources. This guide explains how rate limiting works and how to monitor your rate limit status using response headers.
 
@@ -9,20 +9,20 @@ Rate limiting is applied to all requests to the `/v1/` and `/v2/` endpoints and
 
 If you exceed this limit, you will receive a `429 Too Many Requests` response.
 
-> [!NOTE] Rate Limit Scope
+> [!NOTE] Rate limit scope
 > Rate limiting is applied per IP address. Requests from the same IP address share the same rate limit quotas.
 
-## Rate Limit Response
+## Rate limit response
 
 When you exceed a rate limit, the API returns a `429 Too Many Requests` response:
 
-### HTTP Status Code
+### HTTP status code
 
 ```
 429 Too Many Requests
 ```
 
-### Response Body
+### Response body
 
 The response body follows the standard v2 error format:
 
@@ -37,11 +37,11 @@ The response body follows the standard v2 error format:
 }
 ```
 
-### Response Headers
+### Response headers
 
 The API includes rate limit information in response headers for all requests (both successful and rate-limited). You can inspect these headers to monitor your current rate limit status and determine when you can make additional requests.
 
-#### Standard Headers (RFC Draft 7)
+#### Standard headers (RFC Draft 7)
 
 The API includes standard rate limit headers in all responses:
 
@@ -56,12 +56,12 @@ RateLimit-Remaining: 3
 RateLimit-Reset: 1704067200
 ```
 
-#### Legacy Headers
+#### Legacy headers
 
 For backward compatibility, the API also includes legacy `X-RateLimit-*` headers:
 
 - **`X-RateLimit-Limit`**: The maximum number of requests allowed per window
-- **`X-RateLimit-Remaining`**: The number of requests remaining in the current window  
+- **`X-RateLimit-Remaining`**: The number of requests remaining in the current window
 - **`X-RateLimit-Reset`**: The time (in seconds since Unix epoch) when the rate limit window resets
 
 Example headers:
@@ -71,7 +71,7 @@ X-RateLimit-Remaining: 3
 X-RateLimit-Reset: 1704067200
 ```
 
-#### Retry-After Header
+#### `Retry-After` header
 
 When you receive a `429 Too Many Requests` response, the API includes a `Retry-After` header indicating how many seconds you should wait before retrying:
 
@@ -81,12 +81,12 @@ Retry-After: 45
 
 This value represents the time until the rate limit window resets (rounded up to the nearest second).
 
-> [!TIP] Using Retry-After
+> [!TIP] Using `Retry-After`
 > Always respect the `Retry-After` header value when implementing retry logic. Waiting for the specified duration ensures you don't waste requests on premature retries.
 
-## Monitoring Rate Limits
+## Monitoring rate limits
 
-### Reading Rate Limit Headers
+### Reading rate limit headers
 
 You can monitor your rate limit status by inspecting the headers in every API response, even successful ones. This allows you to proactively slow down your request rate before hitting the limit.
 
@@ -95,12 +95,12 @@ You can monitor your rate limit status by inspecting the headers in every API re
 ```javascript
 async function makeRequest(url, options) {
   const response = await fetch(url, options);
-  
+
   // Check rate limit status from headers
   const remaining = parseInt(response.headers.get('X-RateLimit-Remaining') || '0');
   const limit = parseInt(response.headers.get('X-RateLimit-Limit') || '0');
   const resetTime = parseInt(response.headers.get('X-RateLimit-Reset') || '0');
-  
+
   if (remaining < 5) {
     console.warn(`Rate limit warning: ${remaining}/${limit} requests remaining`);
     const waitTime = resetTime - Math.floor(Date.now() / 1000);
@@ -108,13 +108,13 @@ async function makeRequest(url, options) {
       console.log(`Rate limit resets in ${waitTime} seconds`);
     }
   }
-  
+
   if (response.status === 429) {
     const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
     console.error(`Rate limited! Retry after ${retryAfter} seconds`);
     throw new Error(`Rate limited: retry after ${retryAfter}s`);
   }
-  
+
   return response;
 }
 ```
@@ -126,23 +126,23 @@ import time
 
 def make_request(url, headers):
     response = requests.get(url, headers=headers)
-    
+
     # Check rate limit status
     remaining = int(response.headers.get('X-RateLimit-Remaining', 0))
     limit = int(response.headers.get('X-RateLimit-Limit', 0))
     reset_time = int(response.headers.get('X-RateLimit-Reset', 0))
-    
+
     if remaining < 5:
         print(f"Rate limit warning: {remaining}/{limit} requests remaining")
         wait_time = reset_time - int(time.time())
         if wait_time > 0:
             print(f"Rate limit resets in {wait_time} seconds")
-    
+
     if response.status_code == 429:
         retry_after = int(response.headers.get('Retry-After', 60))
         print(f"Rate limited! Retry after {retry_after} seconds")
         raise Exception(f"Rate limited: retry after {retry_after}s")
-    
+
     return response
 ```
 
@@ -150,7 +150,7 @@ def make_request(url, headers):
 ```bash
 # Make a request and capture headers
 response=$(curl -s -D /tmp/headers.txt -o /tmp/body.txt -w "%{http_code}" \
-  -H "Authorization: Bearer YOUR_TOKEN" \
+-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
   "https://api.lunchmoney.dev/v2/me")
 
 # Extract rate limit headers
@@ -170,7 +170,7 @@ fi
 ```
 :::
 
-### Implementing Exponential Backoff
+### Implementing exponential backoff
 
 When you receive a `429` response, implement exponential backoff with jitter to avoid overwhelming the API:
 
@@ -178,28 +178,28 @@ When you receive a `429` response, implement exponential backoff with jitter to
 async function makeRequestWithRetry(url, options, maxRetries = 3) {
   for (let attempt = 0; attempt < maxRetries; attempt++) {
     const response = await fetch(url, options);
-    
+
     if (response.status !== 429) {
       return response;
     }
-    
+
     // Get retry-after header or use exponential backoff
     const retryAfter = parseInt(response.headers.get('Retry-After') || '0');
-    const waitTime = retryAfter > 0 
+    const waitTime = retryAfter > 0
       ? retryAfter * 1000  // Convert seconds to milliseconds
       : Math.min(1000 * Math.pow(2, attempt) + Math.random() * 1000, 30000);
-    
+
     console.log(`Rate limited. Waiting ${waitTime}ms before retry ${attempt + 1}/${maxRetries}`);
     await new Promise(resolve => setTimeout(resolve, waitTime));
   }
-  
+
   throw new Error('Max retries exceeded due to rate limiting');
 }
 ```
 
-## Best Practices
+## Best practices
 
-### 1. Monitor Headers Proactively
+### 1. Monitor headers proactively
 
 Don't wait for a `429` response. Check rate limit headers on every request and adjust your request rate accordingly:
 
@@ -211,7 +211,7 @@ if (remaining < threshold) {
 }
 ```
 
-### 2. Implement Request Queuing
+### 2. Implement request queuing
 
 For applications that need to make many requests, implement a queue system that respects rate limits:
 
@@ -222,14 +222,14 @@ class RateLimitedQueue {
     this.remaining = 100; // Start with max
     this.resetTime = Date.now() + (15 * 60 * 1000);
   }
-  
+
   async enqueue(requestFn) {
     return new Promise((resolve, reject) => {
       this.queue.push({ requestFn, resolve, reject });
       this.processQueue();
     });
   }
-  
+
   async processQueue() {
     if (this.queue.length === 0 || this.remaining <= 0) {
       if (this.remaining <= 0 && this.resetTime > Date.now()) {
@@ -238,15 +238,15 @@ class RateLimitedQueue {
       }
       return;
     }
-    
+
     const { requestFn, resolve, reject } = this.queue.shift();
     try {
       const response = await requestFn();
-      
+
       // Update rate limit status from headers
       this.remaining = parseInt(response.headers.get('X-RateLimit-Remaining') || '0');
       this.resetTime = parseInt(response.headers.get('X-RateLimit-Reset') || '0') * 1000;
-      
+
       resolve(response);
       this.processQueue(); // Process next item
     } catch (error) {
@@ -256,7 +256,7 @@ class RateLimitedQueue {
 }
 ```
 
-### 3. Cache Responses When Possible
+### 3. Cache responses when possible
 
 Reduce the number of API calls by caching responses locally:
 
@@ -267,24 +267,24 @@ const CACHE_TTL = 5 * 60 * 1000; // 5 minutes
 async function getCachedRequest(url, options) {
   const cacheKey = `${url}:${JSON.stringify(options)}`;
   const cached = cache.get(cacheKey);
-  
+
   if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
     return cached.data;
   }
-  
+
   const response = await fetch(url, options);
   const data = await response.json();
-  
+
   cache.set(cacheKey, {
     data,
     timestamp: Date.now()
   });
-  
+
   return data;
 }
 ```
 
-### 4. Batch Operations When Available
+### 4. Batch operations when available
 
 Use bulk endpoints when available to reduce the number of requests:
 
@@ -309,7 +309,7 @@ await fetch('/v2/categories', {
 ```
 :::
 
-### 5. Limit Crypto Refresh Polling
+### 5. Limit crypto refresh polling
 
 Crypto refresh requests can be bursty if you poll too often. For `POST /v2/crypto/synced/{id}/refresh`:
 
@@ -319,14 +319,14 @@ Crypto refresh requests can be bursty if you poll too often. For `POST /v2/crypt
 
 ## Troubleshooting
 
-### Common Issues
+### Common issues
 
 **Issue**: Rate limits resetting unexpectedly
 
 **Solution**: Rate limits are tracked per IP address. If you're behind a proxy or load balancer, multiple clients may share the same IP and exhaust the shared quota.
 
 
-## Need Help?
+## Need help?
 
 If you're experiencing rate limiting issues that can't be resolved through the techniques described above:
 

package/docs/using-with-ai.md

@@ -73,7 +73,7 @@ const token = process.env.LUNCH_MONEY_ACCESS_TOKEN;
 > [!WARNING]
 > Avoid pasting your access token directly into an AI chat window. Treat it like a password — store it in an environment variable, a `.env` file excluded from source control, or your operating system's secret store.
 
-## Best Practices
+## Best practices
 
 1. **Start with a test budget** — API changes are permanent. Use a test budget while you're learning so your real data stays safe. See the [Getting Started guide](/getting-started) for instructions.
 
@@ -97,7 +97,7 @@ If you want to experiment, here are a few low-risk starting points:
 
 Start small, and use a test budget while you're learning.
 
-## Need Help?
+## Need help?
 
 - Join the <a href="https://lunchmoney.app/discord" target="_blank" rel="noopener noreferrer">Lunch Money Discord</a> and ask in the **#developer-api** channel
 - [Email our developer advocate](mailto:jp@lunchmoney.app)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunch-money/developer-docs",
-  "version": "2.11.1-preview.8",
+  "version": "2.11.1",
   "description": "Developer documentation content for Lunch Money APIs",
   "exports": {
     ".": "./package.json",

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,11 +5,10 @@ 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.1 - TBD
+## 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 budgeting account
-from `GET /me/account/settings` and `PUT /me/account/settings` to `GET /me/user/account/settings` and `PUT /me/user/account/settings`
 - 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