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.

Authentication

All API requests require a Bearer token in the Authorization header:

Authorization: Bearer YOUR_ACCESS_TOKEN

Get your access token from the Lunch Money developers page. See the Getting Started guide for a step-by-step walkthrough including how to create a test budget.

Base URL

https://api.lunchmoney.dev/v2

Response Shapes

The v2 API uses consistent HTTP status codes and response bodies across all endpoints.

Successful responses

GET → 200 OK. Response body contains either a single object or an array property named after the endpoint (e.g., { "transactions": [...] }).
POST → 201 Created. Response body contains the complete created object including system-defined properties like id and created_at.
PUT → 200 OK. Response body contains the complete updated object.
DELETE → 204 No Content. No response body.

Error responses

All errors return an appropriate 4XX status code — the v2 API never returns an error inside a 200 OK response.

Code	Meaning
`400`	Bad Request — invalid parameters or request body
`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.

All error responses share a consistent body format:

{
  "message": "Overall error description",
  "errors": [
    { "errMsg": "Specific error about a parameter or field" }
  ]
}

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.

Request validation

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

Object properties follow consistent rules across the entire API:

Properties that belong to the object itself use simple names: id, name, status
Properties that reference related objects include the object type: category_id, tag_ids, manual_account_id
Timestamps end in _at: created_at, updated_at, archived_at
Lists of IDs include the type: tag_ids (not tags)
Child objects of the same type are always in a children property
All id fields are integer type (not number)

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 for a full explanation of how these properties work, including the sign convention and multi-currency support.

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.

In v2, responses are non-hydrated: related objects are returned as IDs only. To get the full details, call the appropriate endpoint with the returned ID.

// v1 — category details embedded in transaction
{ "category_id": 456, "category_name": "Groceries", "is_income": false }

// v2 — ID only; fetch separately when needed
{ "category_id": 456 }
// GET /v2/categories/456 → { "id": 456, "name": "Groceries", ... }

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)

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.

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.

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

The v2 API uses a modified SEMVER scheme:

Major (always 2) — a new major version would only be released for breaking changes
Minor — the number of top-level endpoint groups currently supported (e.g., a version supporting /me, /categories, and /transactions has minor version 3)
Revision — the number of non-breaking updates since the last endpoint group was added

The Version History tracks changes release by release.