Agent API beta

Manage budgets and categorize transactions with your own agent.

Use a personal access token, a small CLI, or direct HTTP requests to inspect accounts, investments, and budgets, update planned amounts, manage which linked accounts fund your goals, manage goals, forecast scenarios, and budget categories, read booked and pending transactions, reconcile partner payments and balances, set payment notification rules, ask for partner context, and write category assignments. You stay in control of access, expiry, and revocation.

An assignment can change an owned transaction’s sharing, categorisation, or both.

Read the quickstart Open Sloth Money

sloth-agent

npm install --global @slothmoney/agent-cli

sloth-agent auth login
sloth-agent auth status

sloth-agent accounts
sloth-agent investments
sloth-agent budget --scope personal
sloth-agent budget status --scope personal
sloth-agent budget status --scope personal --period 2026-07
sloth-agent budget move --scope personal \
  --from-category-id activities --to-category-id groceries \
  --amount 52.95 --apply
sloth-agent accounts update --account-ref sloth_account_v1_... \
  --institution-name "Hargreaves Lansdown" \
  --account-name "Stocks & Shares ISA" \
  --ownership individual --balance-amount 12500.75 \
  --account-type investments --goal-funding-account true --apply
sloth-agent accounts update --account-ref sloth_account_v1_... \
  --account-name "House deposit" --apply
sloth-agent accounts update --account-ref sloth_account_v1_... \
  --use-provider-name --apply
sloth-agent accounts remove --account-ref sloth_account_v1_...
sloth-agent accounts remove --account-ref sloth_account_v1_... --apply
sloth-agent goals
sloth-agent goals create --name "Emergency fund" \
  --target-amount 12000 --target-month 2027-06 --type keep \
  --account-ref sloth_account_v1_... --apply
sloth-agent scenarios create --month 2026-09 \
  --name "Deposit £100 into the shopping pot each month?" \
  --account-ref sloth_account_v1_... --recurring-amount 100
sloth-agent portfolio --view household
sloth-agent accounts update --account-ref sloth_account_v1_... --partner-visibility holdings --apply
sloth-agent transactions --assignment-scope personal --uncategorized --limit 50
sloth-agent transactions --include-pending
sloth-agent partner status
sloth-agent assign --input assignments.json
sloth-agent assign --input assignments.json --apply

Token controlled

New tokens are view-only by default. Turn on Allow changes only when your agent needs to share or categorise transactions, manage categories and line items, move assigned budget money, update planned budgets, manage accounts, set payment notification rules, scan a contract for its renewal date, request explanations, or manage goals and forecast scenarios.

Read before writing

Pull accounts, investments, budgets, goals, scenarios, categories, and transactions first. Account, budget, goal, category, line-item, scenario, assignment, and notification-rule writes are previews until you add --apply. Assignment, budget, and notification-rule previews validate files locally without contacting Sloth Money.

Your data only

Agent access is scoped to the signed-in user. Account reads show personal accounts and enabled shared joint accounts. Partner personal accounts are excluded.

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

Install the CLI

Install CLI 0.23.0 or newer with Node.js 22 or newer. The sloth-agent command works from any directory.
2

Create a token

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

Save the token

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

Read before writing

Inspect known accounts and categories, then check personal and joint categorisation separately. Copy the exact transaction, category, and line-item IDs into an assignment file.
5

Preview locally

Check the file without contacting Sloth Money or writing anything.
6

Apply and check

--apply applies the file. Inspect every result, then read the transaction again.

npm install --global @slothmoney/agent-cli
sloth-agent auth login
sloth-agent auth status
sloth-agent accounts

sloth-agent goals
sloth-agent goals create --name "Emergency fund" --target-amount 12000 --target-month 2027-06 --type keep --account-ref PASTE_THE_EXACT_ACCOUNT_REF_HERE
sloth-agent goals create --name "Emergency fund" --target-amount 12000 --target-month 2027-06 --type keep --account-ref PASTE_THE_EXACT_ACCOUNT_REF_HERE --apply
sloth-agent goals update --goal-id GOAL_ID --type spend
sloth-agent goals update --goal-id GOAL_ID --type spend --apply
sloth-agent goals update --goal-id GOAL_ID --account-ref PASTE_THE_EXACT_ACCOUNT_REF_HERE
sloth-agent goals update --goal-id GOAL_ID --account-ref PASTE_THE_EXACT_ACCOUNT_REF_HERE --apply
sloth-agent goals update --goal-id GOAL_ID --priority 2
sloth-agent goals update --goal-id GOAL_ID --priority 2 --apply
sloth-agent goals mark-spent --goal-id GOAL_ID
sloth-agent goals mark-spent --goal-id GOAL_ID --apply
sloth-agent goals restore --goal-id GOAL_ID
sloth-agent goals restore --goal-id GOAL_ID --apply
sloth-agent goals delete --goal-id GOAL_ID
sloth-agent goals delete --goal-id GOAL_ID --apply

Goal creates require a positive target amount, an explicit Keep or Spend type, and one personal Goal-funding account. Goal results include goalType and nullable spentAt. Keep goals cannot be marked spent. Restore a spent goal before changing its type.

Goal priority is one-based, so 1 is highest. Moving one goal shifts the intervening goals automatically. Without --apply, goal creation authenticates and asks Sloth to calculate forecastMonthKey without saving the Goal. Applying reruns the same planner before saving.

targetMonthKey is your optional desired month. forecastMonthKey is Sloth’s calculated month. Only the active scenario is calculated. A null forecastMonthKey means Sloth did not find a month within the projection boundary; check projectionThroughMonthKey for the final month tested.

sloth-agent scenarios
sloth-agent scenarios create --month 2026-09 --name "Deposit £100 into the shopping pot each month?" --account-ref PASTE_THE_EXACT_ACCOUNT_REF_HERE --recurring-amount 100
sloth-agent scenarios create --month 2026-09 --name "Add a £50 bonus?" --account-ref PASTE_THE_EXACT_ACCOUNT_REF_HERE --one-off-amount 50 --apply
sloth-agent scenarios update --month 2026-09 --option-id yes --account-ref PASTE_THE_EXACT_ACCOUNT_REF_HERE --recurring-amount 125
sloth-agent scenarios update --month 2026-09 --option-id yes --account-ref PASTE_THE_EXACT_ACCOUNT_REF_HERE --clear-recurring --apply
sloth-agent scenarios activate --month 2026-09 --option-id no --apply
sloth-agent scenarios delete --month 2026-09 --apply

A scenario is a month-anchored choice in the Goal forecast. Creating one adds No and Yes options and activates Yes. A recurring contribution continues until a later active scenario changes it. A one-off contribution applies only in that month. Scenarios change the forecast. They do not move money.

Scenario previews use view-only access and perform zero writes. They return the proposed scenario and recalculated Goals. Add --apply only after reviewing that result. On update, --recurring-amount 0 stops the earlier amount, while --clear-recurring inherits the earlier amount. Contribution changes use the active option when --option-id is omitted.

sloth-agent budget --scope personal --period 2026-08
sloth-agent budget status --scope personal
sloth-agent budget status --scope personal --period 2026-07
sloth-agent budget update --scope personal --period 2026-08 --input budget.json
sloth-agent budget update --scope personal --period 2026-08 --input budget.json --apply
sloth-agent budget move --scope personal --from-category-id activities --to-category-id groceries --amount 52.95
sloth-agent budget move --scope personal --from-category-id activities --to-category-id groceries --amount 52.95 --apply

Budget status is read-only. Omit --period for the current Sloth budget period, or pass YYYY-MM for a historical period. Each activity row has nonnegative moneyInPence and moneyOutPence, plus their difference as netPence.

Current status uses Sloth's normal transaction refresh policy. Historical budget status is cache-only and returns refresh as null. Income, Transfer, and explicit None are normal activity rows. A transaction with no category appears under activity.uncategorized. budget is null when no trustworthy plan exists, but activity still returns.

When an eligible current-period refresh completes, Sloth adds the latest configured backing-account check to your Budget balance audit. A same-day cached read does not add another checkpoint.

A budget update file contains 1 to 100 unique allocations. Each one identifies an existing category and line item and sets its whole-number plannedPence.

{
  "allocations": [
    {
      "categoryId": "groceries",
      "lineItemId": "weekly",
      "plannedPence": 45000
    }
  ]
}

Budget previews validate the file locally without loading a token or contacting Sloth Money. Applying starts from the full selected-period budget and patches the listed amounts. Saving X overwrites X and every explicit future plan. A later save from Y overwrites Y and everything after it. Earlier and historical periods stay unchanged.

budget move transfers current assigned money between categories. Use to-assign as either the source or destination to include To Assign. The decimal digits are converted exactly to positive safe-integer pence. A preview does not load a token or contact Sloth Money.

Applying records the movement and updates both balances in one operation. It does not change planned amounts or future budget plans. The source can become negative, so automated workflows should choose donors from an available-balance policy.

sloth-agent categories
sloth-agent categories create --name "Holidays" --icon-key plane --type Wants
sloth-agent categories create --name "Holidays" --icon-key plane --type Wants --apply
sloth-agent categories rename --category-id CATEGORY_ID --name "Travel fund" --apply
sloth-agent line-items create --scope personal --category-id CATEGORY_ID --name "Flights" --apply
sloth-agent line-items rename --scope personal --category-id CATEGORY_ID --line-item-id LINE_ITEM_ID --name "Travel" --apply
sloth-agent transactions --assignment-scope personal --uncategorized --limit 50
sloth-agent transactions --assignment-scope joint --uncategorized --limit 50
sloth-agent transactions --include-pending
sloth-agent partner status

Review pending and partner payments

--include-pending reuses the transaction command's normal refresh; it does not force another refresh. Booked rows stay under transactions. Pending rows appear in a separate pending block with writable: false and writeBlockReason: pending, so they cannot be categorised until they book. Sloth Money keeps the latest complete pending observation so the same result remains available to a later daily review without another bank refresh. A current empty list means no matching pending rows were observed. An unavailable snapshot does not prove there are none.

partner status is read-only. It returns the current settlement direction and amount plus recent recorded partner payments, which lets an agent reconcile an incoming payment without guessing from the bank counterparty alone. It does not refresh bank accounts or change partner records.

Copy the exact transactionRef for the transaction and the matching categoryId and lineItemId from these outputs into assignments.json. Choose the most specific suitable line item. If none fits, use that category's Other line item. Historical assignments without a line item are not a recommendation to omit one.

{
  "assignments": [
    {
      "transactionRef": "PASTE_THE_EXACT_TRANSACTION_REF_HERE",
      "assignmentScope": "personal",
      "categoryId": "PASTE_A_CATEGORY_ID_HERE",
      "lineItemId": "PASTE_A_LINE_ITEM_ID_HERE"
    }
  ]
}

These are placeholders. Do not submit the example values.

Preview the file

sloth-agent assign --input assignments.json

Without --apply, the CLI checks that the file is valid and returns the payload it would send. It does not contact Sloth Money, verify the transactionRef or category values, or write anything. A successful preview does not guarantee that applying the assignment will succeed.

Apply the assignment

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

Applying 1 to 100 assignments creates a durable operation and returns a receipt promptly. The CLI polls the authenticated status endpoint for you. If the command is interrupted, rerun the same command with the same input file to recover the operation. The command stays sloth-agent assign --input assignments.json --apply and its final output stays succeeded and failed. Completed item results stay in the same order as the input file. Inspect every result.

Each transactionRef can appear only once in a file. Duplicate refs reject the whole submission before anything is written.

Check the result

Check the result in the same assignment scope that you changed. Successful assignments update the original transaction. See the category in Sloth Money → Transactions, or re-run the original transaction query without --uncategorized. The transaction should also disappear from the matching uncategorized query. Confirm that an existing assignment in the other scope was not changed. Assignments do not create a separate list.

sloth-agent transactions --assignment-scope personal --limit 50

Filter one account

sloth-agent accounts
sloth-agent transactions --account-ref PASTE_THE_EXACT_ACCOUNT_REF_HERE --limit 50

Every transaction result includes the same accountRef used by sloth-agent accounts. Copy the exact opaque value into --account-ref to keep later pages and reads on that account. accountRef is the public account filter for CLI and HTTP transaction reads.

Watch a payment

Rules watch future payments that match an existing transaction. They do not create transactions or recurring predictions.

{
  "amountChange": {
    "enabled": true,
    "comparison": "increase",
    "baselinePence": 3184
  },
  "renewalReminder": {
    "enabled": true,
    "renewalDate": "2027-07-30",
    "leadDays": 30
  },
  "delivery": { "email": true }
}

baselinePence is the comparison amount. renewalDate uses YYYY-MM-DD, and leadDays accepts an integer from 1 to 365. In-app delivery is always on. Set delivery.email to add email delivery. Returned rules include the computed remindOn date.

Save this as rule.json. Copy the exact transactionRef from sloth-agent transactions, then preview and apply the rule:

sloth-agent rules list
sloth-agent rules get --transaction-ref PASTE_THE_EXACT_TRANSACTION_REF_HERE
sloth-agent rules set --transaction-ref PASTE_THE_EXACT_TRANSACTION_REF_HERE --input rule.json
sloth-agent rules set --transaction-ref PASTE_THE_EXACT_TRANSACTION_REF_HERE --input rule.json --apply
sloth-agent rules delete --transaction-ref PASTE_THE_EXACT_TRANSACTION_REF_HERE
sloth-agent rules delete --transaction-ref PASTE_THE_EXACT_TRANSACTION_REF_HERE --apply

Without --apply, rules set validates the file locally without loading a token or contacting Sloth Money.

sloth-agent rules scan-contract --contract contract.pdf
sloth-agent rules scan-contract --contract contract.pdf --apply

A contract must be a PDF no larger than 6 MB. Without --apply, it stays on your device. With --apply, Sloth sends it for one-time extraction. Scanning returns a renewalDate and confidence. It does not save a rule. renewalDate is null when Sloth cannot find a date in the PDF. The PDF is discarded after extraction and is not stored.

Attach receipt items

sloth-agent receipts extract --image /path/to/receipt.jpg > receipt-draft.json
sloth-agent receipts attach --transaction-ref PASTE_THE_EXACT_TRANSACTION_REF_HERE --input receipt.json
sloth-agent receipts attach --transaction-ref PASTE_THE_EXACT_TRANSACTION_REF_HERE --input receipt.json --apply
sloth-agent receipts get --transaction-ref PASTE_THE_EXACT_TRANSACTION_REF_HERE
sloth-agent receipts remove --transaction-ref PASTE_THE_EXACT_TRANSACTION_REF_HERE --revision 1 --apply

Extraction accepts one JPEG, PNG, or WebP image up to 8 MB and returns a draft. Sloth does not save the image or the draft. Review every receipt item, then keep only schemaVersion, currency, and receiptItems in the attach file. Each receipt item contains only an id, label, and signed amount in pence. Use a positive amount for a purchase or charge and a negative amount for a discount. Leave out subtotals, payment, change, and VAT already included in the item prices so they are not counted twice.

Attach previews are local and do not load a token or contact Sloth Money until you add --apply. Confirmed receipt items are evidence only. They do not change the transaction's category, sharing, partner balance, or budget treatment. Use the saved revision when replacing or removing evidence so an older edit cannot overwrite a newer one.

Share and categorise

sloth-agent transactions --shared=false --q "sainsbury" --limit 20

{
  "assignments": [
    {
      "transactionRef": "PASTE_THE_EXACT_TRANSACTION_REF_HERE",
      "sharing": {
        "isShared": true,
        "shareRatio": 0.6,
        "userExclusiveAmountPence": 500,
        "partnerExclusiveAmountPence": 0
      },
      "assignmentScope": "joint",
      "categoryId": "groceries"
    }
  ]
}

sharing.isShared is required. The optional shareRatio is your share, from 0 to 1. Exclusive amounts use userExclusiveAmountPence and partnerExclusiveAmountPence as nonnegative integer pence. Preview stays local and does not load a token. Apply with --apply, then read the saved result with --shared=true.

A first share uses your saved couple ratio, falling back to 0.5, and zero exclusive amounts when split fields are omitted. On an existing share, omitted split fields keep their saved values. A combined category uses Joint when you have no exclusive amount and Personal when you do, unless you set assignmentScope explicitly.

Send { "isShared": false } without split fields to unshare. Sloth keeps the Joint category dormant for a later re-share. Only your booked personal-account transactions can be changed. Partner-owned and native joint-account transactions remain read-only. Foreign-currency sharing remains available for settlement but is not included in the Joint budget.

Other commands

sloth-agent transactions --assignment-scope joint --line-item-id LINE_ITEM_ID
sloth-agent transactions --assignment-scope joint --uncategorized
sloth-agent ask-partner --transaction-ref PASTE_THE_EXACT_TRANSACTION_REF_HERE
sloth-agent auth logout

The transaction reference shown above is also a placeholder. Copy the exact value from sloth-agent transactions output.

For CI or headless systems, set SLOTH_AGENT_TOKEN in your secret manager. It overrides a stored credential. auth logout removes only the local copy; 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/accounts" \
  -H "Authorization: Bearer $SLOTH_AGENT_TOKEN"

API reference

Sixteen API resources

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

GET · PATCH · DELETE /api/agent/v1/accounts

Returns the existing personal accounts and enabled shared joint accounts visible to the signed-in user. Partner personal accounts are excluded. Each row has an opaque accountRef, effective account and institution labels, accountType, ownership, source, native balance and currency when known, lastBalanceUpdatedAt, and connectionState. isGoalFundingAccount shows whether Goals and active scenario contributions may use the account. partnerVisibility is private, balance, or holdings for the current partner pair.

Account reads are cache-only and do not contact a bank or refresh balances. asOf is the response time, not a balance timestamp. Balances are never converted or combined, and missing values are null. Provider account IDs, account numbers, sort codes, and IBANs are not returned.

/api/agent/v1/accounts/:accountRef accepts strict partial updates. Manual accounts can change institution, name, currency, and ownership. Balance-only accounts can also change balance, Savings/Investments type, and Goal-funding eligibility. Connected accounts also support a private Sloth name. Send accountName as a string to set it, or null to return to the latest provider name. Manual accounts still require a non-empty name. The CLI options are --account-name, --use-provider-name, --goal-funding-account and --partner-visibility.

DELETE archives an owned manual account without deleting its transaction, import, balance, or categorisation records. There is no restore command. Shared, disconnected, or inaccessible accounts return Account not found. The CLI previews PATCH and DELETE locally until you add --apply.

GET · POST · PATCH · DELETE /api/agent/v1/scenarios

Lists month-anchored scenarios, their options, active option, and account contributions. POST creates the common No/Yes choice and activates Yes. Update and delete requests use /api/agent/v1/scenarios/:monthKey. Select an existing option with /api/agent/v1/scenarios/:monthKey/activate.

POST /api/agent/v1/scenarios/preview accepts a strict create, update, activate, or delete action. It works with view-only access, performs zero writes, and returns the proposed scenario plus recalculated Goals. Applied requests require Allow changes. Scenario contributions affect forecasts only and never transfer money.

POST /api/agent/v1/receipts/extract

Accepts one raw JPEG, PNG, or WebP image up to 8 MB and returns a transient draft with a currency, warnings, and up to 200 receipt items. Each item has an id, label, and signed amount in pence. Purchases and charges are positive; discounts are negative. The image and draft are not persisted by Sloth Money.

GET · PUT · DELETE /api/agent/v1/receipts/confirmed

Reads, replaces, or removes the confirmed structured receipt evidence for one booked transaction. PUT accepts the opaque transactionRef, an optional expectedRevision, and the reviewed receipt. DELETE requires the current revision. The saved total is the simple sum of every signed receipt-item amount.

Receipt evidence is separate from categorisation and sharing. The owner can manage it. A connected partner can read it only when the parent transaction is shared; either member of a true joint account can manage it.

GET /api/agent/v1/budget-status

Returns booked activity for the current or a historical personal or joint budget period. Pass an optional periodKey in YYYY-MM format. The key names the month containing the period's start boundary, so the end date can fall in the following month. The response includes stored or legacy-fallback period dates, one currency, refresh state, activity, and a nullable budget.

Activity includes Income, Transfer, explicit None, and observed categories. Each row reports moneyInPence, moneyOutPence, and netPence. Truly uncategorized activity stays separate. Historical reads do not refresh or borrow a later budget plan.

POST /api/agent/v1/budget-movements

Moves a positive integer amountPence between two planned categories or To Assign. The request accepts personal or joint scope and defaults to the current budget period.

The balance changes and movement history are atomic. The response returns the resulting To Assign and affected category balances. Historical periods cannot be changed.

GET · PATCH /api/agent/v1/budgets

Reads one personal or joint budget period. The response includes periodStatus, currency, the effective plan, stored funding when available, categories, line items, and planned pence. Historical reads require their frozen snapshot. The API does not calculate spent or available balances from transactions.

PATCH accepts 1 to 100 existing category and line-item pairs with plannedPence. It builds a complete selected-period budget, then overwrites that period and every explicit future plan. A later update starts a new overwrite boundary. Historical periods cannot be changed.

GET /api/agent/v1/investments

Returns caller-owned linked investment accounts with Coinbase, Trading 212, and other SnapTrade holdings nested beneath each account. Filter with accountRef or sloth-agent investments --account-ref. Manual holdings, activities, and partner-owned accounts are excluded.

Investment reads are cache-only and do not contact SnapTrade. An investment account total and its nested holdings describe the same portfolio, so do not add them together. Do not add values in different currencies without an explicit conversion. Symbols can be missing, and non-zero cash appears as a cash holding.

GET /api/agent/v1/portfolio

Returns savings and investments from the mine, partner, or household planning view. Partner accounts appear only when their owner shared a balance or linked holdings. Household totals use the viewer's budget currency and exclude other currencies without converting them.

Use sloth-agent portfolio --view household. The CLI waits up to 45 seconds for eligible linked balances to refresh. Sharing does not change ownership, transaction access, Goal funding, or who can move money. Partner transactions, activities, fees, notes, provider identifiers, and Goal assignments are not returned.

A completed balance refresh updates the Budget balance audit for configured backing accounts. A same-day cached read does not add another checkpoint.

GET · POST · PATCH · DELETE /api/agent/v1/goals

Lists Goals or creates one. Creates require a positive target amount, goalType set to keep or spend, and a personal fundingAccountRef. Results include the effective priority, private funding-account label and reference, forecastMonthKey, and forecastBasis. Update and delete requests use /api/agent/v1/goals/:goalId. A priority PATCH uses a one-based position and shifts the intervening Goals automatically. A Spend Goal can be marked spent or restored with isSpent. Keep Goals cannot be marked spent, and a spent Goal must be restored before its type changes.

POST /api/agent/v1/goals/preview accepts the same strict input as create, works with view-only access, and performs no writes. Preview and create calculate from the active scenario with the same server planner. Goals compete only with earlier Goals assigned to the same account. Desired dates do not change the calculated forecast.

GET · POST · PATCH /api/agent/v1/categories

Returns visible categories and budget line-item options for personal and joint scopes. POST creates a custom category. PATCH requests use /api/agent/v1/categories/:categoryId and rename user-created categories; built-in categories are immutable.

A category is the broader parent. A line item is a child within one category. Names such as Other may repeat: Bills → Other and Subscriptions → Other are different choices. Use the map matching the transaction scope, and keep categoryId and lineItemId together.

POST · PATCH /api/agent/v1/line-items

Creates a zero-value line item in a personal or joint budget. Rename requests use /api/agent/v1/line-items/:lineItemId. Both require the parent categoryId and scope. Changes update the current period and explicit future plans; historical snapshots remain unchanged.

GET /api/agent/v1/transactions

Returns booked transactions with opaque transactionRef and accountRef values. Filter by date range, search text, account, category, line item, uncategorized state, or sharing state.

Filter one account with the opaque accountRef from the accounts response.

Use --shared and --line-item-id in the CLI or lineItemId over HTTP. When combined with categoryId, both IDs must match the same assignment or split.

Personal and joint category assignments are separate. A personal assignment uses the transaction's top-level categoryId, lineItemId, and categorySplits. A joint-budget assignment uses the corresponding fields under jointBudgetContribution.

A transaction can be uncategorised personally while its joint-budget contribution is already categorised. To assess its categorisation, inspect both locations. Use assignmentScope=joint to select the joint fields on eligible shared personal-account transactions.

The first transaction read each UTC day may refresh linked bank data. The response includes structured refresh status and still returns readable cached transactions if refresh work continues or fails.

A quota_exceeded reason means the UTC-day provider refresh allowance is exhausted. Cached booked transactions remain available.

A checkpoint_failed reason means provider work completed, but the Budget balance-audit checkpoint failed. Cached booked transactions remain available, and a same-day read retries only that checkpoint.

A completed transaction refresh updates the Budget balance audit for configured backing accounts. A same-day cached read does not add another checkpoint.

Set includePending=true to include the current normalized pending snapshot from the normal refresh flow. Sloth Money replaces this bounded snapshot after each fully successful refresh, including when no pending rows remain. Pending rows are explicitly non-writable. The response distinguishes current from unavailable; it never treats an unavailable snapshot as an empty one.

GET /api/agent/v1/partner-status

Returns read-only partner connection state, the current settlement balance, and paginated sent or received payment activity. Balance and payment amounts use integer pence. Payment references and cursors are opaque. The endpoint does not refresh bank accounts or write partner data.

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 · GET /api/agent/v1/transaction-assignments

Applying 1 to 100 assignments creates a durable operation and returns a receipt promptly. The direct POST returns a 202 receipt. POST requires an Idempotency-Key. Retrying the same submission with that key does not create a second operation. The receipt has an operationId; a pending, processing, or completed status; itemCount, completedCount, and failedCount; expiresAt; and pollAfterMs.

Read progress from the authenticated /api/agent/v1/transaction-assignments/:operationId endpoint. A completed operation includes one atomic succeeded or failed result per input item, in input order. Each completed item has a succeeded or failed status. Failed results include transactionRef and error; succeeded results include the saved assignment fields. A successful sharing result includes the persisted split and resulting Joint contribution.

Sloth Money keeps the minimum assignment instructions, ownership and progress state, and ordered results needed for recovery. The operation record expires after seven days and is then deleted.

GET · PUT · DELETE /api/agent/v1/notification-rules

Lists saved transaction notification rules. Read, replace, or remove one rule through /api/agent/v1/notification-rules/for-transaction using the exact transactionRef returned by the transactions endpoint. A rule can watch for an amount increase, any amount change, a renewal date, or both. In-app delivery is server-owned and always enabled; write requests only choose delivery.email. Returned rules include the computed remindOn date.

Contract extraction uses /api/agent/v1/notification-rules/extract-renewal. The response contains the renewal date and confidence only. renewalDate is null when Sloth cannot find a date. The PDF is discarded after extraction and is not stored.

Assignment shape

Write with transaction refs

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

These are placeholders. Replace each example value with the exact transactionRef and category IDs returned for your account.

Joint category and line item

{
  "assignments": [
    {
      "transactionRef": "PASTE_THE_EXACT_TRANSACTION_REF_HERE",
      "assignmentScope": "joint",
      "categoryId": "PASTE_A_CATEGORY_ID_HERE",
      "lineItemId": "PASTE_A_LINE_ITEM_ID_HERE"
    }
  ]
}

Split category

{
  "assignments": [
    {
      "transactionRef": "PASTE_THE_EXACT_TRANSACTION_REF_HERE",
      "assignmentScope": "personal",
      "categorySplits": [
        { "categoryId": "PASTE_FIRST_CATEGORY_ID_HERE", "amountPence": 1500 },
        { "categoryId": "PASTE_SECOND_CATEGORY_ID_HERE", "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.

Free beta included

Agent API access is included with full Sloth Money access. Join during the free beta and keep it free forever.

Tokens expire

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

Choose less access

View-only tokens can read accounts, investment holdings, transactions, categories, budgets, and goals. Permissions cannot be edited later - revoke and reissue a token if its job changes.

Check freshness

Account reads never trigger bank refreshes. Transaction reads may refresh linked bank data once each UTC day and report the result.

A completed eligible refresh updates your Budget balance audit. A same-day cached read does not add another audit checkpoint.

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 goal or assignment changes before applying them.

Open Sloth Money

Manage budgets and categorize transactions with your own agent.

Token controlled

Read before writing

Your data only

Human context when needed

Connect an agent

Install the CLI

Create a token

Save the token

Read before writing

Preview locally

Apply and check

Review pending and partner payments

Preview the file

Apply the assignment

Check the result

Filter one account

Watch a payment

Attach receipt items

Share and categorise

Other commands

Prefer direct HTTP?

Sixteen API resources

Write with transaction refs

Joint category and line item

Split category

Keep access tight

Free beta included

Tokens expire

Choose less access

Check freshness

Links expire

Beta surface

Start with Developer access.