Agent API beta

Categorize Sloth transactions with your own agent.

Use a personal access token, a small CLI, or direct HTTP requests to read uncategorized transactions, ask for partner context, and write category assignments. You stay in control of access, expiry, and revocation.

Read the quickstart Open Sloth Money
sloth-agent 
npm install --global @slothmoney/agent-cli

sloth-agent auth login
sloth-agent auth status

sloth-agent transactions --uncategorized --limit 50
sloth-agent ask-partner --transaction-ref sloth_txn_...
sloth-agent assign --input assignments.json
sloth-agent assign --input assignments.json --apply

Token controlled

Create a personal access token in Settings, copy it once, and revoke it when your agent no longer needs access.

Read before writing

Pull categories and transactions first. Preview assignment JSON before sending a write request.

Your data only

Agent access is scoped to the signed-in user and enabled joint account transactions for that Sloth Money account.

Human context when needed

Agents can create a partner clarification link for a partner-shared or joint transaction. The CLI prints the message and link; it does not send WhatsApp messages.

Quickstart

Connect an agent

Install the public CLI from npm. Review the source on GitHub. Direct HTTP calls use the same API.

  1. 1

    Install the CLI

    Install the package with Node.js 22 or newer. The sloth-agent command works from any directory.

  2. 2

    Create a token

    Open Settings, then Developer access. Choose an expiry and copy the token once.

  3. 3

    Save the token

    Use the hidden login prompt to save it in your operating system's secure credential store.

  4. 4

    Preview, then apply

    Build an assignment file, preview the payload, then add --apply when it is correct. 

npm install --global @slothmoney/agent-cli
sloth-agent auth login
sloth-agent auth status
sloth-agent categories
sloth-agent transactions --uncategorized --limit 50
sloth-agent transactions --q "tesco" --start-date 2026-05-01 --end-date 2026-05-31
sloth-agent assign --input assignments.json
sloth-agent assign --input assignments.json --apply
sloth-agent ask-partner --transaction-ref sloth_txn_...
sloth-agent auth logout

For CI or headless systems, set SLOTH_AGENT_TOKEN in your secret manager. It overrides a stored credential.

auth status makes a live request and updates the token's last-used time. auth logout removes the local copy only. Revoke the token in Developer access.

Prefer direct HTTP?

Every CLI command maps to the same versioned API. Send the token as a bearer header when another tool already handles HTTP. 

curl "https://budget.slothmoney.app/api/agent/v1/categories" \
  -H "Authorization: Bearer $SLOTH_AGENT_TOKEN"

API reference

Four core endpoints

Every request uses Authorization: Bearer with a Sloth personal access token.

GET /api/agent/v1/categories

Returns visible categories and budget line-item options for personal and joint scopes.

GET /api/agent/v1/transactions

Returns booked transactions with an opaque transactionRef. Filter by date range, search text, account, category, or uncategorized state.

POST /api/agent/v1/transaction-explanation-requests

Creates a 72-hour partner clarification link for one booked partner-shared or joint transaction. The response includes a shareable message and link.

POST /api/agent/v1/transaction-assignments

Applies 1 to 100 category assignments. The response may contain mixed successes and failures, so agents should inspect every result.

Assignment shape

Write with transaction refs

Use the transactionRef from the transaction response. It is the stable reference the API needs for assignment writes.

Single category

{
  "assignments": [
    {
      "transactionRef": "sloth_txn_...",
      "categoryId": "groceries",
      "lineItemId": "weekly"
    }
  ]
}

Split category

{
  "assignments": [
    {
      "transactionRef": "sloth_txn_...",
      "categorySplits": [
        { "categoryId": "groceries", "amountPence": 1500 },
        { "categoryId": "shopping", "amountPence": 500 }
      ]
    }
  ]
}

Safety

Keep access tight

The Agent API is built for user-run automation. Treat your token like a password. Never put it in chat, source control, shared logs, or shell history. Revoke it when you are done testing.

Paid access required

Agent endpoints follow the same paid-access rules as the Sloth Money app.

Tokens expire

Choose 7, 30, or 90 days when creating a personal access token in Developer access.

No bank sync

Reads use stored booked transactions. Agent requests do not trigger a bank refresh.

Links expire

Partner clarification links last 72 hours and accept one answer. Agents receive the payload but do not send messages.

Beta surface

Endpoint paths are versioned, but the developer surface may change while agent workflows settle.

Start with Developer access.

Create a token in Sloth Money, connect your agent, and preview the first assignment payload before writing changes.

Open Sloth Money