Skip to main content
Tools for overriding a transaction’s category or applying categorization rules after the fact. All of these tools set category_override=true on affected transactions, which protects them from being changed by future rule runs or syncs. To restore a transaction to automatic categorization, use reset_transaction_category.
Prefer compound ops for review-driven categorization. When you’re closing a review (set category + remove needs-review + leave a note) reach for update_transactions instead. It writes one linked annotation per transaction covering the whole edit, where categorize_transaction only writes the category set.
All tools on this page are Write scope and require session_id + reason.

​
categorize_transaction

Manually overrides one transaction’s category. Pass transaction_id plus either category_id or category_slug — slug is resolved automatically. Mirrors: PATCH /api/v1/transactions/{id}/category

​
Parameters

​
transaction_id
string
required
Transaction UUID or short ID.
​
category_slug
string
Category slug (e.g. food_and_drink_groceries). Alternative to category_id.
​
category_id
string
Category UUID or short ID. Takes precedence if both are supplied.
​
session_id
string
required
From create_session.
​
reason
string
required
Brief rationale.

​
Example input

{
  "session_id": "s9Xm2pQk",
  "reason": "correcting miscategorized grocery run",
  "transaction_id": "k7Xm9pQ2",
  "category_slug": "food_and_drink_groceries"
}

​
Example output

{ "text": "Transaction k7Xm9pQ2 categorized successfully." }

​
batch_categorize_transactions

Categorize multiple transactions at once. Each item is a {transaction_id, category_slug} pair. Max 500 items per request. Sets category_override=true on every affected transaction. Mirrors: POST /api/v1/transactions/batch-categorize

​
Parameters

​
items
array of objects
required
Array of {transaction_id, category_slug} pairs. Max 500.
​
session_id
string
required
​
reason
string
required

​
Example input

{
  "session_id": "s9Xm2pQk",
  "reason": "assigning coffee runs flagged during review",
  "items": [
    { "transaction_id": "k7Xm9pQ2", "category_slug": "food_and_drink_coffee" },
    { "transaction_id": "k8Yn0qR3", "category_slug": "food_and_drink_coffee" },
    { "transaction_id": "k9Zo1rS4", "category_slug": "food_and_drink_coffee" }
  ]
}

​
Example output

{
  "succeeded": 3,
  "failed": 0,
  "errors": []
}

​
bulk_recategorize

Moves every transaction matching from_category (plus any other filters) to to_category. Requires to_category and at least one filter as a safety requirement. Sets category_override=true because this is an explicit action. Typical use: “move everything currently in general_merchandise for March to groceries”. Mirrors: POST /api/v1/transactions/bulk-recategorize

​
Parameters

​
to_category
string
required
Destination category slug.
​
from_category
string
Only transactions currently in this category are matched.
​
start_date
string (YYYY-MM-DD)
​
end_date
string (YYYY-MM-DD)
​
account_id
string
​
user_id
string
​
min_amount
number
​
max_amount
number
​
pending
boolean
​
search
string
​
name_contains
string
Filter transactions whose name contains this string.
​
session_id
string
required
​
reason
string
required
The legacy parameter names target_category_slug (for to_category) and category_slug (for from_category) are still accepted but deprecated. Prefer the new names.

​
Example input

{
  "session_id": "s9Xm2pQk",
  "reason": "NETFLIX charges were misfiled under general",
  "from_category": "general_merchandise",
  "to_category": "entertainment_streaming_services",
  "search": "NETFLIX",
  "start_date": "2026-01-01",
  "end_date": "2026-04-01"
}

​
Example output

{
  "matched_count": 14,
  "updated_count": 14
}

​
reset_transaction_category

Removes a manual category override from one transaction and re-resolves its category from the automatic mapping + rule pipeline. Use this to undo a categorize_transaction action. Mirrors: DELETE /api/v1/transactions/{id}/category

​
Parameters

​
transaction_id
string
required
​
session_id
string
required
​
reason
string
required

​
Example input

{
  "session_id": "s9Xm2pQk",
  "reason": "undoing accidental override",
  "transaction_id": "k7Xm9pQ2"
}

​
Example output

{ "text": "Transaction k7Xm9pQ2 category reset to automatic." }

​
apply_rules

Applies rules retroactively to existing transactions. Pass rule_id to run one rule in isolation, or omit to run the full active-rule pipeline in priority-ASC order. Materializes set_category, add_tag, and remove_tag actions; add_comment is sync-only and does not fire here. Hit counts increment per condition match, matching sync-time semantics.
Use sparingly. This is for initial setup and explicit back-fills — not routine reviews. During normal work, create the rule and let it match future syncs naturally. Running the full pipeline across thousands of historical transactions can take time.

​
Parameters

​
rule_id
string
UUID or short ID of a specific rule to apply. Omit to apply every active rule.
​
session_id
string
required
​
reason
string
required

​
Example input (single rule)

{
  "session_id": "s9Xm2pQk",
  "reason": "backfilling new Starbucks rule to existing transactions",
  "rule_id": "r9Xm2pQr"
}

​
Example output (single rule)

{
  "rule_id": "r9Xm2pQr",
  "affected_count": 47
}

​
Example input (all rules)

{
  "session_id": "s9Xm2pQk",
  "reason": "initial setup — apply every rule to historical data"
}

​
Example output (all rules)

{
  "rules_applied": {
    "r9Xm2pQr": 47,
    "rAYn0qR3": 128,
    "rBZo1rS4": 12
  },
  "total_affected": 187
}