Households

A household owns a budget. You can belong to several: your own personal household (created the first time you sign in) plus any you've been invited to or created. Your token belongs to you, not to a household.

Choosing the householdCopy Anchor Link

Budget and transaction calls act on one household:

• the one named by the X-SpendRock-Household header, if you send it, or
• your default household otherwise.

# your default household
curl -s "$SR_API/months/2026-12" -H "Authorization: Bearer $SR_TOKEN"

# a specific household
curl -s "$SR_API/months/2026-12" \
  -H "Authorization: Bearer $SR_TOKEN" \
  -H "X-SpendRock-Household: 01J8Z3N4Q5R6S7T8V9W0X1Y2Z3"

GET /me tells you which household the request acted on (household), your default (default_household_id), and every household you belong to (households).

If you aren't a current member of the household you name, the request fails with 403 and the code not_a_member. Membership is checked on every request, so someone removed from a household loses access immediately.

Finding household IDsCopy Anchor Link

curl -s "$SR_API/households" -H "Authorization: Bearer $SR_TOKEN"

This lists your households, default first, with your role (owner or member) and whether each is your personal household. Archived households are left out unless you pass include_archived=true. (Needs households:read.)

Managing householdsCopy Anchor Link

With households:manage a token can do what you can do under Settings → Households: create households, rename them (owner only), set your default, archive and unarchive, leave, transfer ownership (owner only), remove members (owner only), and send, revoke, accept, or decline invites. The rules are the app's rules. For example:

• you can't leave or delete your only household (last_household)
• your personal household can't be deleted (personal_household)
• an owner must transfer ownership before leaving (owner_must_transfer)
• only the owner can do owner things (not_owner)

See Errors for every code.