SpendRock Docs
Items

Identity-level changes that apply to EVERY month (ITEM-3, ITEM-7, FUND-6)

Required scope: `budget:write` (personal access tokens; sessions have every scope).

PATCH
/items/{itemId}

Required scope: budget:write (personal access tokens; sessions have every scope).

Authorization

bearerAuth
AuthorizationBearer <token>

Authorization: Bearer <token>: a mobile session token, or a personal access token (srp_…) created in Account → API tokens (DEV-1).

Personal access tokens:

  • Act as their user. The household comes from X-SpendRock-Household, else the user's default.
  • Carry scopes (DEV-2), and each operation's description names the one it needs: budget:read / budget:write (months, groups, items, funds, favorites, harvest), transactions:read / transactions:write (transactions, merchant suggestions), households:read / households:manage (households, members, invites), account:read / account:write (me, settings). A write scope includes its read scope. A call outside the token's scopes gets 403 insufficient_scope, with the needed scope in details.required_scope.
  • Can't manage tokens or passwords (403 session_required).
  • May expire (401 unauthenticated afterwards).
  • Are rate-limited (DEV-3): 120 requests/minute per token with bursts up to 120. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (seconds until the bucket is full again); over the limit the answer is 429 rate_limited with Retry-After (seconds). Limits are kept per server instance, so they're approximate.

Sessions (web cookie or mobile bearer) have every scope and aren't limited this way. Cross-origin browser calls (CORS, for the API docs playground) must use a bearer token; cookies are never accepted cross-origin.

In: header

Path Parameters

itemId*string

ULID.

Match^[0-9A-HJKMNP-TV-Z]{26}$

Header Parameters

X-SpendRock-Household?string

The household to act on (HH-12). Defaults to the user's default household. 403 not_a_member if the caller isn't a current member (HH-16).

Match^[0-9A-HJKMNP-TV-Z]{26}$

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/items/01J8Z3N4Q5R6S7T8V9W0X1Y2Z3" \  -H "Content-Type: application/json" \  -d '{}'
{  "id": "01J8Z3N4Q5R6S7T8V9W0X1Y2Z3",  "name": "string",  "kind": "income",  "is_fund": true,  "favorite": true,  "fund_target": 0}

"Harvest $X" (HARV-1..4): set this month's Planned = Spent so the remainder goes back to Left to Budget. POST

Only for regular expense items whose Remaining is above $0. `harvested` is the amount moved back to Left to Budget. Undo by sending `previous_planned` to `PATCH /months/{month}/items/{itemId}`. 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. PUT

`item_ids` may list all favorites or only some (e.g. the favorites in the month being viewed). The listed favorites are placed, in the given order, into the positions they held between them in the household's current Favorites order; favorites that are not listed keep their positions. For example, with Favorites `[A, B, C, D]`, sending `[D, B]` gives `[A, D, C, B]`. Every id must be a current favorite, listed once; otherwise the request fails with `invalid`. Required scope: `budget:write` (personal access tokens; sessions have every scope).