# SpendRock Docs

> Documentation for SpendRock, a small zero-based budgeting app (web, iOS, and a public JSON API). Every page is also available as Markdown at the same path plus `.md`.

- API base URL: https://app.spendrock.com/api/v1
- OpenAPI spec: https://app.spendrock.com/api/v1/openapi.yaml (also /openapi.json)
- Everything in one file: https://docs.spendrock.com/llms-full.txt

## Help

- [Welcome](https://docs.spendrock.com/index.md): SpendRock is a small zero-based budgeting app for your household.
- [Getting started](https://docs.spendrock.com/getting-started.md): Sign in, plan your first month, and track an expense.

## API

- [API overview](https://docs.spendrock.com/api.md): A JSON API over HTTPS for everything SpendRock does, authenticated with personal access tokens.

### Guides

- [Quickstart](https://docs.spendrock.com/api/quickstart.md): Create a personal access token and make your first API request.
- [Authentication & scopes](https://docs.spendrock.com/api/authentication.md): Personal access tokens, the scopes they carry, and what they can't do.
- [Households](https://docs.spendrock.com/api/households.md): Pick which household a request acts on with the X-SpendRock-Household header.
- [Money & dates](https://docs.spendrock.com/api/money-and-dates.md): Amounts are integer cents; months are YYYY-MM; dates are YYYY-MM-DD.
- [Idempotency](https://docs.spendrock.com/api/idempotency.md): Transaction IDs are generated by the client and double as idempotency keys, so retries never duplicate.
- [Errors](https://docs.spendrock.com/api/errors.md): The error format, HTTP statuses, and every error code.
- [Pagination](https://docs.spendrock.com/api/pagination.md): List transactions page by page with an opaque cursor.
- [Rate limits](https://docs.spendrock.com/api/rate-limits.md): 120 requests per minute per token, with bursts, and headers that tell you where you stand.
- [Versioning & changelog](https://docs.spendrock.com/api/versioning.md): /v1 only changes additively. Here's what that promises, and what changed.

### Reference

- Auth
  - [Exchange a Google ID token for a SpendRock session (AUTH-1, AUTH-2)](https://docs.spendrock.com/api/reference/auth/signInWithGoogle.md): No authentication needed.
  - [Sign Out](https://docs.spendrock.com/api/reference/auth/signOut.md): Any credential; no scope needed.
  - [Start an email + password sign-up (ACCT-1)](https://docs.spendrock.com/api/reference/auth/registerWithPassword.md): Emails a verification link (valid 24h, single use). If the email already belongs to an
  - [Redeem an email verification link and sign in (ACCT-2)](https://docs.spendrock.com/api/reference/auth/verifyEmail.md): The token is the `token` query parameter of the emailed link. A first verification creates
  - [Email a new verification link to an unverified sign-up](https://docs.spendrock.com/api/reference/auth/resendVerification.md): No authentication needed.
  - [Sign in with email + password (ACCT-1)](https://docs.spendrock.com/api/reference/auth/signInWithPassword.md): 401 `bad_credentials` ("Email or password is incorrect.") for any wrong email or password;
  - [Email a password reset link (ACCT-3)](https://docs.spendrock.com/api/reference/auth/requestPasswordReset.md): Sends a link (valid 1h, single use) if the email has an account. Same answer either way.
  - [Set a new password from a reset link (ACCT-3)](https://docs.spendrock.com/api/reference/auth/resetPassword.md): Also marks the email verified (the link proves it) and signs out every session of the
  - [The caller's sign-in methods (ACCT-2, Settings → Sign-in methods)](https://docs.spendrock.com/api/reference/auth/getSignInMethods.md): Required scope: `account:read` (personal access tokens; sessions have every scope).
  - [Add or change the caller's password (ACCT-2)](https://docs.spendrock.com/api/reference/auth/setPassword.md): Changing an existing password needs `current_password` (401 `bad_credentials`). If the
  - [Get Me](https://docs.spendrock.com/api/reference/auth/getMe.md): Required scope: `account:read` (personal access tokens; sessions have every scope).
  - [Personal access tokens (AUTH-5)](https://docs.spendrock.com/api/reference/auth/listTokens.md): Needs a signed-in session: personal access tokens get 403 `session_required`.
  - [Create a personal access token (DEV-1, DEV-2)](https://docs.spendrock.com/api/reference/auth/createToken.md): `scopes` defaults to every scope (full access) when omitted. `expires_in_days` omitted
  - [Delete Token](https://docs.spendrock.com/api/reference/auth/deleteToken.md): Needs a signed-in session: personal access tokens get 403 `session_required`.
- Months
  - [Which months have budgets (for the month picker, NAV-2)](https://docs.spendrock.com/api/reference/months/listMonths.md): Required scope: `budget:read` (personal access tokens; sessions have every scope).
  - [The full budget for a month (one call renders the whole budget screen, PERF-4)](https://docs.spendrock.com/api/reference/months/getMonth.md): Required scope: `budget:read` (personal access tokens; sessions have every scope).
  - [Create the month by copying the most recent earlier budget, or the default template (CREATE-2, CREATE-4, CREATE-5)](https://docs.spendrock.com/api/reference/months/createMonth.md): Required scope: `budget:write` (personal access tokens; sessions have every scope).
  - [Reset Budget (CREATE-6). `replace` untracks every transaction in the month.](https://docs.spendrock.com/api/reference/months/resetMonth.md): Required scope: `budget:write` (personal access tokens; sessions have every scope).
- Groups
  - [Add a group to this month (GROUP-1)](https://docs.spendrock.com/api/reference/groups/createGroup.md): Required scope: `budget:write` (personal access tokens; sessions have every scope).
  - [Reorder this month's groups (GROUP-4). Income is always first; list non-income groups only.](https://docs.spendrock.com/api/reference/groups/setGroupOrder.md): Required scope: `budget:write` (personal access tokens; sessions have every scope).
  - [Delete a group and its items from THIS month only; their transactions become untracked (GROUP-3)](https://docs.spendrock.com/api/reference/groups/deleteGroupFromMonth.md): Required scope: `budget:write` (personal access tokens; sessions have every scope).
  - [Rename or recolor a group. Applies to EVERY month (linked identity, GROUP-2).](https://docs.spendrock.com/api/reference/groups/updateGroup.md): Required scope: `budget:write` (personal access tokens; sessions have every scope).
- Items
  - [Set the order of items within a group; an item listed here that belongs to another group is moved into this one (ITEM-5)](https://docs.spendrock.com/api/reference/items/setItemOrder.md): Required scope: `budget:write` (personal access tokens; sessions have every scope).
  - [Add an item to a group in this month (ITEM-1). Kind follows the group (income vs expense).](https://docs.spendrock.com/api/reference/items/createItem.md): Required scope: `budget:write` (personal access tokens; sessions have every scope).
  - [Change this month's planned amount or note (ITEM-2, ITEM-8)](https://docs.spendrock.com/api/reference/items/updateMonthItem.md): Required scope: `budget:write` (personal access tokens; sessions have every scope).
  - [Delete the item from THIS month only; its transactions in this month become untracked (ITEM-4)](https://docs.spendrock.com/api/reference/items/deleteItemFromMonth.md): Required scope: `budget:write` (personal access tokens; sessions have every scope).
  - ["Make This a Fund" (FUND-1). current_balance becomes the carry-in for this month.](https://docs.spendrock.com/api/reference/items/makeFund.md): Required scope: `budget:write` (personal access tokens; sessions have every scope).
  - [Set the fund's current balance; records a "Balance Updated" adjustment for the difference (FUND-5). Never counts as Spent.](https://docs.spendrock.com/api/reference/items/setFundBalance.md): Required scope: `budget:write` (personal access tokens; sessions have every scope).
  - ["Harvest $X" (HARV-1..4): set this month's Planned = Spent so the remainder goes back to Left to Budget.](https://docs.spendrock.com/api/reference/items/harvestRemainder.md): Only for regular expense items whose Remaining is above $0. `harvested` is the amount moved back
  - [Identity-level changes that apply to EVERY month (ITEM-3, ITEM-7, FUND-6)](https://docs.spendrock.com/api/reference/items/updateItem.md): Required scope: `budget:write` (personal access tokens; sessions have every scope).
  - [Reorder the Favorites section (FAV-1). Independent of each item's order within its group.](https://docs.spendrock.com/api/reference/items/setFavoritesOrder.md): `item_ids` may list all favorites or only some (e.g. the favorites in the month being
- Transactions
  - [The Transactions panel tabs (TXN-8, TXN-2a, TXN-4a)](https://docs.spendrock.com/api/reference/transactions/listTransactions.md): Required scope: `transactions:read` (personal access tokens; sessions have every scope).
  - [Add an expense or income (TXN-1). Idempotent on the client-generated id (SYNC-1).](https://docs.spendrock.com/api/reference/transactions/createTransaction.md): Required scope: `transactions:write` (personal access tokens; sessions have every scope).
  - [Get Transaction](https://docs.spendrock.com/api/reference/transactions/getTransaction.md): Required scope: `transactions:read` (personal access tokens; sessions have every scope).
  - [Edit amount/date/merchant/note/type/splits/budget month, untrack (empty splits), or remove the location (TXN-3, TXN-4, TXN-5)](https://docs.spendrock.com/api/reference/transactions/updateTransaction.md): Required scope: `transactions:write` (personal access tokens; sessions have every scope).
  - [Soft delete, no confirmation; the client offers Undo (TXN-4)](https://docs.spendrock.com/api/reference/transactions/deleteTransaction.md): Required scope: `transactions:write` (personal access tokens; sessions have every scope).
  - [Restore with original tracking; splits whose item no longer exists in that month are dropped (TXN-4a)](https://docs.spendrock.com/api/reference/transactions/restoreTransaction.md): Required scope: `transactions:write` (personal access tokens; sessions have every scope).
- Suggestions
  - [The full merchant → last-used item map, cached on clients (TXN-9, PERF-5)](https://docs.spendrock.com/api/reference/suggestions/listMerchantHints.md): Required scope: `transactions:read` (personal access tokens; sessions have every scope).
- Settings
  - [Get Settings](https://docs.spendrock.com/api/reference/settings/getSettings.md): Required scope: `account:read` (personal access tokens; sessions have every scope).
  - [Update Settings](https://docs.spendrock.com/api/reference/settings/updateSettings.md): Required scope: `account:write` (personal access tokens; sessions have every scope).
  - ["Delete all saved locations" (TXN-13)](https://docs.spendrock.com/api/reference/settings/deleteAllLocations.md): Required scope: `account:write` (personal access tokens; sessions have every scope).
- Households
  - [My households, default first (HH-11). Archived ones only with include_archived (HH-19).](https://docs.spendrock.com/api/reference/households/listHouseholds.md): Required scope: `households:read` (personal access tokens; sessions have every scope).
  - [Create an additional household that I own (HH-11)](https://docs.spendrock.com/api/reference/households/createHousehold.md): Required scope: `households:manage` (personal access tokens; sessions have every scope).
  - [Get Household](https://docs.spendrock.com/api/reference/households/getHousehold.md): Required scope: `households:read` (personal access tokens; sessions have every scope).
  - [Rename (owner only, HH-2)](https://docs.spendrock.com/api/reference/households/renameHousehold.md): Required scope: `households:manage` (personal access tokens; sessions have every scope).
  - [Delete for all members (owner only; never a personal household). A soft delete; members whose default it was fall back to their personal household (HH-18).](https://docs.spendrock.com/api/reference/households/deleteHousehold.md): Required scope: `households:manage` (personal access tokens; sessions have every scope).
  - [Make it my default (HH-10). Not an archived household (`household_archived`).](https://docs.spendrock.com/api/reference/households/setDefaultHousehold.md): Required scope: `households:manage` (personal access tokens; sessions have every scope).
  - [Hide it from my lists (per user; never deletes anything; HH-19). Not my default (`default_household`), not my last non-archived one (`last_household`).](https://docs.spendrock.com/api/reference/households/archiveHousehold.md): Required scope: `households:manage` (personal access tokens; sessions have every scope).
  - [Show it in my lists again (HH-19)](https://docs.spendrock.com/api/reference/households/unarchiveHousehold.md): Required scope: `households:manage` (personal access tokens; sessions have every scope).
  - [Leave (HH-2, HH-3). Owners must transfer first unless alone (a sole owner leaving deletes it); a personal household's owner can't leave it.](https://docs.spendrock.com/api/reference/households/leaveHousehold.md): Required scope: `households:manage` (personal access tokens; sessions have every scope).
  - [Make another member the owner (owner only, HH-2). Not for personal households.](https://docs.spendrock.com/api/reference/households/transferOwnership.md): Required scope: `households:manage` (personal access tokens; sessions have every scope).
  - [List Members](https://docs.spendrock.com/api/reference/households/listMembers.md): Required scope: `households:read` (personal access tokens; sessions have every scope).
  - [Remove a member (owner only, HH-2). They lose access on their next request (HH-16).](https://docs.spendrock.com/api/reference/households/removeMember.md): Required scope: `households:manage` (personal access tokens; sessions have every scope).
- Invites
  - [Pending, unexpired invites with their links (HH-9)](https://docs.spendrock.com/api/reference/invites/listHouseholdInvites.md): Required scope: `households:read` (personal access tokens; sessions have every scope).
  - [Invite by email (any member, HH-4). Expires in 7 days; re-inviting the same email replaces the pending invite (HH-9).](https://docs.spendrock.com/api/reference/invites/createInvite.md): Required scope: `households:manage` (personal access tokens; sessions have every scope).
  - [Revoke (the owner, or whoever sent it; HH-2)](https://docs.spendrock.com/api/reference/invites/revokeInvite.md): Required scope: `households:manage` (personal access tokens; sessions have every scope).
  - [Pending invites addressed to my email (the HH-5 banner)](https://docs.spendrock.com/api/reference/invites/listMyInvites.md): Required scope: `households:read` (personal access tokens; sessions have every scope).
  - [Look up an invite link in any status (HH-6). No sign-in needed; the token isn't echoed.](https://docs.spendrock.com/api/reference/invites/getInvite.md): No authentication needed.
  - [Join (HH-8). My email must match the invite (`invite_email_mismatch`).](https://docs.spendrock.com/api/reference/invites/acceptInvite.md): Required scope: `households:manage` (personal access tokens; sessions have every scope).
  - [Decline Invite](https://docs.spendrock.com/api/reference/invites/declineInvite.md): Required scope: `households:manage` (personal access tokens; sessions have every scope).