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 and write category assignments. You stay in control of access, expiry, and revocation.

Read the quickstart Open Sloth Money

sloth-agent

export SLOTH_AGENT_TOKEN="sloth_pat_v1_..."
export SLOTH_AGENT_API_BASE_URL="https://budget.slothmoney.app"

yarn agent transactions --uncategorized --limit 50
yarn agent assign --input assignments.json
yarn 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.

Quickstart

Connect an agent

The CLI is the fastest path for local agents that can run shell commands. Direct HTTP calls use the same API.

1

Create a token

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

Set environment

Store the token where your agent can read it. Do not paste it into prompts or shared logs.
3

Preview, then apply

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

export SLOTH_AGENT_TOKEN="sloth_pat_v1_..."
export SLOTH_AGENT_API_BASE_URL="https://budget.slothmoney.app"

yarn agent categories
yarn agent transactions --uncategorized --limit 50
yarn agent transactions --q "tesco" --start-date 2026-05-01 --end-date 2026-05-31

yarn agent assign --input assignments.json
yarn agent assign --input assignments.json --apply

API reference

Three 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-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 and 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.

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