Quickstart

1. Create a personal access tokenCopy Anchor Link

In SpendRock, open Account → API tokens (open it now) and choose Create token:

• Name: something that tells you where it's used, like budget-export script.
• Expiry: 30, 90, or 365 days, or never.
• Scopes: Read only for scripts that only look, Full access for scripts that change things, or pick exactly the ones you need. See Authentication & scopes.

The token (it starts with srp_) is shown once. Copy it somewhere safe, like a password manager or your script's secret store. If you lose it, revoke it and create a new one.

2. Make your first requestCopy Anchor Link

Set two shell variables. SR_API is the base URL, https://app.spendrock.com/api/v1.

export SR_API="<the base URL above>"
export SR_TOKEN="srp_…"   # your token

Ask who you are:

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

You get your user, the household you're acting on, and all your households (abbreviated):

{
  "user": { "id": "…", "name": "Jacob Barrieault", "email": "jacob@example.com" },
  "household": { "id": "01J8Z3N4Q5R6S7T8V9W0X1Y2Z3", "name": "Jacob's Budget", "role": "owner" },
  "default_household_id": "01J8Z3N4Q5R6S7T8V9W0X1Y2Z3",
  "households": [ … ]
}

That needs the account:read scope. With a Read only or Full access token it just works.

3. Read this month's budgetCopy Anchor Link

curl -s "$SR_API/months/2026-12" -H "Authorization: Bearer $SR_TOKEN"

The response is the whole month in one call: left_to_budget, every group and item with its planned, spent, and remaining amounts (all in cents), and more. If the month has no budget yet, you get 404 with the code month_not_created.

4. Add an expenseCopy Anchor Link

Transactions need an ID that you generate: a ULID. Sending the same request twice (say, after a timeout) never creates a duplicate. See Idempotency.

curl -s -X POST "$SR_API/transactions" \
  -H "Authorization: Bearer $SR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "01JCXK6Q8W6M5T7V3N2B9R4Y1Z",
    "type": "expense",
    "amount": 5420,
    "date": "2026-12-03",
    "merchant": "Corner Grocery",
    "budget_month": "2026-12",
    "splits": [{ "item_id": "<an item id from step 3>", "amount": 5420 }]
  }'

That needs transactions:write. The response contains the new transaction and the recomputed month, so you can see the item's new remaining amount right away.

Next stepsCopy Anchor Link

• Try any endpoint from the browser: every reference page has a playground. Paste your token into its Authorization field.
• Read about errors and rate limits before you automate anything.