@lunch-money/developer-docs 2.11.0-preview.10

package/README.md

@@ -0,0 +1,65 @@
+# @lunch-money/developer-docs
+
+Documentation content for the [Lunch Money](https://lunchmoney.app) developer APIs —
+the guides, v1/v2 reference docs, images, and doc-routing manifest that power the
+[Lunch Money developer portal](https://lunchmoney.dev).
+
+Most API consumers want the OpenAPI spec instead: **[`@lunch-money/v2-api-spec`](https://www.npmjs.com/package/@lunch-money/v2-api-spec)**
+is the canonical machine-readable API contract. This package is the human-facing docs
+content, primarily for the docs server that renders the portal.
+
+## What's in the package
+
+Shipped verbatim at the package root:
+
+- `docs/` — version-independent guides (getting started, pagination, rate limiting, …)
+- `v1/` — v1 API reference markdown
+- `v2/` — v2 guides, images, and a **convenience copy** of the OpenAPI YAML under
+  `v2/spec/` (non-canonical; the canonical spec is `@lunch-money/v2-api-spec`)
+- `manifest.json` — doc routes, redirects, and sidebar structure
+
+## Consuming the content
+
+Resolve the package root, then read content files relative to it:
+
+```js
+const path = require('path');
+const fs = require('fs');
+
+const docsRoot = path.dirname(require.resolve('@lunch-money/developer-docs/package.json'));
+const intro = fs.readFileSync(path.join(docsRoot, 'docs/getting-started.md'), 'utf8');
+```
+
+`manifest.json` describes every page the docs server renders:
+
+```jsonc
+{
+  "pages": [
+    {
+      "path": "/amounts-and-balances",        // canonical URL
+      "file": "docs/amounts-and-balances.md",  // path within this package
+      "title": "Amounts & Balances",
+      "section": "GUIDES",                     // sidebar grouping
+      "type": "markdown",                      // "markdown" | "html" | "v1-slate"
+      "aliases": ["/v2/amounts-and-balances"]  // legacy URLs → 301 to path
+    }
+  ],
+  "redirects": [ /* { from, to, status } */ ],
+  "sidebar": { "docs": [ /* … */ ], "v1": [ /* … */ ] }
+}
+```
+
+## Versioning
+
+The package version tracks the newest API version this content documents (e.g. `2.11.x`
+documents the v2.11 API). Pin an exact version in server deployments so docs are
+deterministic.
+
+## Contributing
+
+Guides, spec, and the routing manifest are edited in the public
+[`developer-docs` repository](https://github.com/lunch-money/developer-docs) — see its
+README for how to add or move a page. This npm package is a published build of that
+content.
+
+_ISC licensed._

package/docs/README.md

@@ -0,0 +1,16 @@
+# Version-Independent Documentation
+
+This directory contains documentation that applies across all API versions.
+
+## Current Documents
+
+- `pagination.md` - Pagination guidelines
+- (To be added) Other version-independent documentation
+
+## Version-Specific Documentation
+
+Version-specific documentation is located in:
+- `v2/docs/` - Version 2 API documentation
+
+
+

package/docs/amounts-and-balances.md

@@ -0,0 +1,85 @@
+# 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.
+
+## `amount`
+
+`amount` is a string representation of a monetary value, precise to up to four decimal places. It appears on transactions, child transactions, recurring items, budget objects, and rollover pool adjustments.
+
+```json
+"amount": "12.5000"
+```
+
+`amount` is always expressed in the currency specified by the companion `currency` property on the same object. Amounts are never rounded or converted.
+
+## `balance`
+
+`balance` is a string representation of an account's running balance, also precise to up to four decimal places. It appears on manual accounts, Plaid accounts, crypto accounts, and balance history entries.
+
+```json
+"balance": "1500.0000"
+```
+
+Like `amount`, `balance` is always in the `currency` of the same object and follows the same sign convention.
+
+## `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.
+
+## `to_base`
+
+`to_base` is a floating-point number that represents the `amount` or `balance` converted to the user's **primary currency**. It is present on transactions, account objects, balance history entries, budget objects, and summary responses.
+
+```json
+"amount": "12.5000",
+"currency": "eur",
+"to_base": 13.62
+```
+
+`to_base` is calculated by the API at response time and is **read-only** — it is never accepted on `POST` or `PUT` requests.
+
+`to_base` is the recommended property to use when you need to:
+- 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
+
+### Transaction amounts
+
+For `amount` and `to_base` on transaction objects, the API uses standard accounting convention (the bank ledger perspective):
+
+| Value | Meaning |
+|-------|---------|
+| **Positive** | Money going **out** — debits, expenses |
+| **Negative** | Money coming **in** — credits, income |
+
+For example:
+
+- A $5 coffee purchase has `"amount": "5.0000"`
+- A $1,200 paycheck deposit has `"amount": "-1200.0000"`
+
+### Account balances
+
+For `balance` on account objects (manual accounts, Plaid accounts, crypto), the sign reflects the account's current standing from the institution's perspective. Positive is the normal direction for both asset and liability accounts:
+
+- A savings account with $5,000 has `"balance": "5000.0000"` — positive, you hold that amount
+- A credit card with $800 owed has `"balance": "800.0000"` — positive, you owe that amount
+
+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
+> 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
+
+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.
+
+- **Budget objects**: `amount` is the positive budgeted value for a category. Whether that represents an income or expense budget is determined by the linked category's `is_income` flag.
+- **Summary category totals**: fields like `other_activity` and `recurring_activity` are always positive. The associated category's `is_income` flag tells you which direction the activity flows.
+- **Summary top-level totals**: activity is split into separate `inflow` and `outflow` objects, each containing positive magnitudes — so direction is explicit in the structure.
+
+> [!TIP]
+> When reading amounts from budget or summary objects, treat all values as positive magnitudes. Check the category's `is_income` flag or the parent object (`inflow` vs `outflow`) to determine the direction of the activity.

package/docs/currencies.md

@@ -0,0 +1,277 @@
+# 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 codes must be:
+- Three letters
+- Lowercase
+- Valid ISO 4217 currency codes
+
+## Supported Currencies
+
+The following currencies are currently supported in Lunch Money:
+
+| Code | Currency |
+|------|----------|
+| `aed` | United Arab Emirates Dirham |
+| `afn` | Afghan Afghani |
+| `all` | Albanian Lek |
+| `amd` | Armenian Dram |
+| `ang` | Netherlands Antillean Guilder |
+| `aoa` | Angolan Kwanza |
+| `ars` | Argentine Peso |
+| `aud` | Australian Dollar |
+| `awg` | Aruban Florin |
+| `azn` | Azerbaijani Manat |
+| `bam` | Bosnia-Herzegovina Convertible Mark |
+| `bbd` | Barbadian Dollar |
+| `bdt` | Bangladeshi Taka |
+| `bgn` | Bulgarian Lev |
+| `bhd` | Bahraini Dinar |
+| `bif` | Burundian Franc |
+| `bmd` | Bermudian Dollar |
+| `bnd` | Brunei Dollar |
+| `bob` | Bolivian Boliviano |
+| `brl` | Brazilian Real |
+| `bsd` | Bahamian Dollar |
+| `btc` | Bitcoin |
+| `btn` | Bhutanese Ngultrum |
+| `bwp` | Botswanan Pula |
+| `byn` | Belarusian Ruble |
+| `bzd` | Belize Dollar |
+| `cad` | Canadian Dollar |
+| `cdf` | Congolese Franc |
+| `chf` | Swiss Franc |
+| `clf` | Chilean Unit of Account (UF) |
+| `clp` | Chilean Peso |
+| `cny` | Chinese Yuan |
+| `cop` | Colombian Peso |
+| `crc` | Costa Rican Colón |
+| `cuc` | Cuban Convertible Peso |
+| `cup` | Cuban Peso |
+| `cve` | Cape Verdean Escudo |
+| `czk` | Czech Republic Koruna |
+| `djf` | Djiboutian Franc |
+| `dkk` | Danish Krone |
+| `dop` | Dominican Peso |
+| `dzd` | Algerian Dinar |
+| `egp` | Egyptian Pound |
+| `ern` | Eritrean Nakfa |
+| `etb` | Ethiopian Birr |
+| `eth` | Ethereum |
+| `eur` | Euro |
+| `fjd` | Fijian Dollar |
+| `fkp` | Falkland Islands Pound |
+| `gbp` | British Pound Sterling |
+| `gel` | Georgian Lari |
+| `ggp` | Guernsey Pound |
+| `ghs` | Ghanaian Cedi |
+| `gip` | Gibraltar Pound |
+| `gmd` | Gambian Dalasi |
+| `gnf` | Guinean Franc |
+| `gtq` | Guatemalan Quetzal |
+| `gyd` | Guyanaese Dollar |
+| `hkd` | Hong Kong Dollar |
+| `hnl` | Honduran Lempira |
+| `hrk` | Croatian Kuna |
+| `htg` | Haitian Gourde |
+| `huf` | Hungarian Forint |
+| `idr` | Indonesian Rupiah |
+| `ils` | Israeli New Sheqel |
+| `imp` | Isle of Man Pound |
+| `inr` | Indian Rupee |
+| `iqd` | Iraqi Dinar |
+| `irr` | Iranian Rial |
+| `isk` | Icelandic Króna |
+| `jep` | Jersey Pound |
+| `jmd` | Jamaican Dollar |
+| `jod` | Jordanian Dinar |
+| `jpy` | Japanese Yen |
+| `kes` | Kenyan Shilling |
+| `kgs` | Kyrgystani Som |
+| `khr` | Cambodian Riel |
+| `kmf` | Comorian Franc |
+| `kpw` | North Korean Won |
+| `krw` | South Korean Won |
+| `kwd` | Kuwaiti Dinar |
+| `kyd` | Cayman Islands Dollar |
+| `kzt` | Kazakhstani Tenge |
+| `lak` | Laotian Kip |
+| `lbp` | Lebanese Pound |
+| `lkr` | Sri Lankan Rupee |
+| `lrd` | Liberian Dollar |
+| `lsl` | Lesotho Loti |
+| `ltl` | Lithuanian Litas |
+| `lvl` | Latvian Lats |
+| `lyd` | Libyan Dinar |
+| `mad` | Moroccan Dirham |
+| `mdl` | Moldovan Leu |
+| `mga` | Malagasy Ariary |
+| `mkd` | Macedonian Denar |
+| `mmk` | Myanma Kyat |
+| `mnt` | Mongolian Tugrik |
+| `mop` | Macanese Pataca |
+| `mro` | Mauritanian Ouguiya |
+| `mur` | Mauritian Rupee |
+| `mvr` | Maldivian Rufiyaa |
+| `mwk` | Malawian Kwacha |
+| `mxn` | Mexican Peso |
+| `myr` | Malaysian Ringgit |
+| `mzn` | Mozambican Metical |
+| `nad` | Namibian Dollar |
+| `ngn` | Nigerian Naira |
+| `nio` | Nicaraguan Córdoba |
+| `nok` | Norwegian Krone |
+| `npr` | Nepalese Rupee |
+| `nzd` | New Zealand Dollar |
+| `omr` | Omani Rial |
+| `pab` | Panamanian Balboa |
+| `pen` | Peruvian Nuevo Sol |
+| `pgk` | Papua New Guinean Kina |
+| `php` | Philippine Peso |
+| `pkr` | Pakistani Rupee |
+| `pln` | Polish Zloty |
+| `pyg` | Paraguayan Guarani |
+| `qar` | Qatari Rial |
+| `ron` | Romanian Leu |
+| `rsd` | Serbian Dinar |
+| `rub` | Russian Ruble |
+| `rwf` | Rwandan Franc |
+| `sar` | Saudi Riyal |
+| `sbd` | Solomon Islands Dollar |
+| `scr` | Seychellois Rupee |
+| `sdg` | Sudanese Pound |
+| `sek` | Swedish Krona |
+| `sgd` | Singapore Dollar |
+| `shp` | Saint Helena Pound |
+| `sll` | Sierra Leonean Leone |
+| `sos` | Somali Shilling |
+| `srd` | Surinamese Dollar |
+| `std` | São Tomé and Príncipe Dobra |
+| `svc` | Salvadoran Colón |
+| `syp` | Syrian Pound |
+| `szl` | Swazi Lilangeni |
+| `thb` | Thai Baht |
+| `tjs` | Tajikistani Somoni |
+| `tmt` | Turkmenistani Manat |
+| `tnd` | Tunisian Dinar |
+| `top` | Tongan Paʻanga |
+| `try` | Turkish Lira |
+| `ttd` | Trinidad and Tobago Dollar |
+| `twd` | New Taiwan Dollar |
+| `tzs` | Tanzanian Shilling |
+| `uah` | Ukrainian Hryvnia |
+| `ugx` | Ugandan Shilling |
+| `usd` | United States Dollar |
+| `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 |
+| `yer` | Yemeni Rial |
+| `zar` | South African Rand |
+| `zmw` | Zambian Kwacha |
+| `zwl` | Zimbabwean Dollar |
+
+## 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:
+
+:::tabs
+@tab JavaScript/Node.js
+```javascript
+// Create a transaction with a specific currency
+const transaction = {
+  date: "2024-01-15",
+  amount: "100.50",
+  currency: "eur",  // Euro
+  payee: "Coffee Shop",
+  category_id: 83
+};
+
+const response = await fetch('https://api.lunchmoney.dev/v2/transactions', {
+  method: 'POST',
+  headers: {
+    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
+    'Content-Type': 'application/json'
+  },
+  body: JSON.stringify(transaction)
+});
+```
+
+@tab Python
+```python
+import requests
+
+# Create a transaction with a specific currency
+transaction = {
+    "date": "2024-01-15",
+    "amount": "100.50",
+    "currency": "eur",  # Euro
+    "payee": "Coffee Shop",
+    "category_id": 83
+}
+
+response = requests.post(
+    'https://api.lunchmoney.dev/v2/transactions',
+    headers={
+        'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
+        'Content-Type': 'application/json'
+    },
+    json=transaction
+)
+```
+
+@tab cURL
+```bash
+curl -X POST 'https://api.lunchmoney.dev/v2/transactions' \
+  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "date": "2024-01-15",
+    "amount": "100.50",
+    "currency": "eur",
+    "payee": "Coffee Shop",
+    "category_id": 83
+  }'
+```
+:::
+
+## 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
+
+The API validates that currency codes match the supported list. If you provide an unsupported currency code, you'll receive a validation error:
+
+```json
+{
+  "message": "Request Validation Failure",
+  "errors": [
+    {
+      "errMsg": "Invalid currency code",
+      "instancePath": "/currency",
+      "schemaPath": "#/properties/currency/enum"
+    }
+  ]
+}
+```
+
+## 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
+> 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

@@ -0,0 +1,104 @@
+# 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.
+
+
+## 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.
+
+:::tabs
+
+@tab 1. Open the Budgets Window
+Click on the green circle in the upper right hand corner in the Lunch Money Web App
+![Green Budgets Icon](/images/green_budget.png)
+
+@tab 2. Create a New Budget
+Click on the "Create a New Budget Account" link and give your new budget a name like "API Test Budget"
+![Create New Budget](/images/new_budget.png)
+
+@tab 3. Add Test Data
+Choose the option to "Set up Demo". This will add categories, accounts, tags and several months worth of transactions to your new budget.
+![Add Demo Data](/images/DemoData.png)
+:::
+
+## Getting an access token
+
+Lunch Money API requests are authenticated using the Bearer Token authentication method. In plain English, this means that you will pass a token associated with your budgeting account to Lunch Money. This is so we know which account to operate on and that the request came from someone who can access that account.
+
+:::tabs
+
+@tab 1. Go to the Developers Page
+
+Navigate to <a href="https://my.lunchmoney.app/developers" target="_blank" rel="noopener noreferrer">the developers page in the Lunch Money web app</a>. Look at the green circle in the upper right hand corner and make sure that it is showing the test account that you just created. If you aren't sure which account is active, you can click on the green circle to bring up the "Switch Accounts" dialog. This will show you the full names of all the accounts associated with your account. Select the test budgeting account you created.
+![Green Budgets Icon](/images/green_budget.png)
+
+@tab 2. Request Access Token
+In the upper right hand corner of the page, give your access token a label and specify what you are using it for. When you're done, hit the "Request Access Token" button.
+![Request Token](/images/RequestAccessToken.png)
+
+@tab 3. Save Access Token
+After you do this, the web page will show you a long alphanumeric string. This is your access token. Hit the copy button and save this token somewhere safe. It is only shown to you when you create it.
+:::
+
+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. 
+
+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.
+
+> [!NOTE]
+> Give your access tokens descriptive names so you can easily identify and revoke them later if needed.
+
+
+## Using your access token
+
+When you start to write code that makes API calls, you will need to include this token in each request using an Authorization header. Here is an example curl request:
+
+```bash
+curl --location 'https://api.lunchmoney.dev/v2/me' \
+--header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>'
+```
+
+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). 
+
+:::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. 
+![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. 
+![TestRequest.png](/images/TestRequest.png)
+:::
+
+This will pop up a dialog box that you can use to send an API request. This is a simple endpoint, so just hit the "Send" button. You should see a response that includes your name and the name of your test budget.
+
+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?
+
+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!
+
+If you still aren't sure how to get started, we have other resources to help.
+
+A great way to find get unstuck is to <a href="https://lunchmoney.app/discord" target="_blank" rel="noopener noreferrer">join the Lunch Money community on Discord</a> and send a question in the <a href="https://discord.com/channels/842337014556262411/1134594318414389258" target="_blank" rel="noopener noreferrer">Developer API Channel</a>.
+
+You can also [email our developer advocate](mailto:jp@lunchmoney.app) to get help as well.
+
+> [!NOTE]
+>These are also great channels to provide feedback! Our v2 API was built based on feedback from our developer community. Your ideas might help us make them even better, so please don't hesitate to reach out.

package/docs/introduction.md

@@ -0,0 +1,63 @@
+# Lunch Money Developer Docs
+
+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
+
+The v2 API is available at:
+
+```
+https://api.lunchmoney.dev/v2
+```
+
+Get your access token from the <a href="https://my.lunchmoney.app/developers" target="_blank" rel="noopener noreferrer">Lunch Money app developers page</a> and include it as a Bearer token in every request:
+
+```http
+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.
+
+## 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.
+
+:::tabs
+
+@tab 1. Select the Mock Server
+Open the <a href="/v2/docs">API Reference</a> and click the **Server** dropdown near the top of the page. Select **`https://mock.lunchmoney.dev/v2`**.
+![Server dropdown with mock server selected](/v2/images/server-dropdown.png)
+
+@tab 2. Enter Any Bearer Token
+Set your Bearer Token to any string of **11 or more characters** — no real token needed. You can enter it in the server panel that appears after selecting the mock server, or inside any endpoint's Authentication section.
+![Bearer token field with a placeholder value entered](/v2/images/bearer.png)
+
+:::
+
+## 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>
+- GitHub: <a href="https://github.com/lunch-money/lunch-money-js-v2" target="_blank" rel="noopener noreferrer">lunch-money/lunch-money-js-v2</a>
+
+Looking for a Python SDK or a client in another language? The <a href="https://github.com/juftin/lunchmoney-clients" target="_blank" rel="noopener noreferrer">lunchmoney-clients</a> project provides a Python SDK and can generate clients for other languages from the OpenAPI spec.
+
+## Migrating from v1
+
+The v2 API is **not backwards compatible** with v1. See the [Migration Guide](/v2/migration-guide) to understand what changed and plan your migration.
+
+The v1 API remains available at `https://api.lunchmoney.dev/v1` and its documentation is available [here](/v2/v1/changelog). New projects should use v2.
+
+## Acknowledgments
+
+If you provided feedback during the API design process — **thank you**. We built this based on what the community asked for.
+
+Join the conversation in the <a href="https://lunchmoney.app/discord" target="_blank" rel="noopener noreferrer">Lunch Money Discord</a> in the **#developer-api** channel.
+
+---
+
+**Useful links:**
+- <a href="/v2/docs">Interactive API Reference</a>
+- [Getting Started Guide](/v2/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)