update_transactions — a compound write that covers category, tags, and a comment in one atomic op per row. Single-action tools exist for simpler cases.
All tools on this page are Write scope and require session_id + reason. See Categorization for category-only writes.
update_transactions
Compound write for up to 50 transactions at once. Each operation can set a category (category_slug), add tags (tags_to_add), remove tags (tags_to_remove), and attach a comment — all atomically per transaction. This is the preferred tool for closing review work (set category + remove needs-review + explain) in one call.
Every change lands as a single linked annotation per operation. Prefer this over composing categorize_transaction + add_transaction_tag + remove_transaction_tag + add_transaction_comment, which would write four separate annotations.
Compound op semantics
What “compound” means here. Each element in the
operations array is a bundle of mutations targeting one transaction. Within a single operation:- The category, tag additions, tag removals, and comment are applied atomically — either all land or none do.
- The annotations written for those changes are linked so the activity timeline reads as one event, not four.
- Tag
notefields are preserved on bothtag_addedandtag_removedannotations.
on_error behavior
continue(default) — each operation runs in its own DB transaction. A failure on row 17 doesn’t roll back rows 1–16. The response returns per-rowstatusso you can retry the failed ones.abort— the whole batch runs in one DB transaction. The first error rolls back every operation and the response includesaborted: true.
Parameters
Array of per-transaction operations. Max 50. See the operation shape below.
continue or abort.Operation shape
UUID or short ID.
Category slug to set. Sets
category_override=true. Omit to leave the category unchanged.List of
{slug, note?} entries. Auto-creates persistent tags if the slug is unknown.List of
{slug, note?} entries. note is recommended for workflow tags like needs-review.Free-form comment written as an annotation. Max 10000 chars. Prefer inline over a separate
add_transaction_comment call.Example input
Example output
add_transaction_comment
Adds a free-standing comment to a transaction — narrative that isn’t tied to a specific category or tag change. Flagging unusual charges, noting shared expenses, cross-references.When the comment is rationale for an edit, use
update_transactions instead. Passing the rationale inline (comment, or note on a tag op) writes one linked annotation; add_transaction_comment writes a separate, free-standing one — so the timeline would duplicate the context.Parameters
UUID or short ID.
Comment text. Markdown supported. Max 10000 chars.
Example input
Example output
add_transaction_tag
Attach one tag to one transaction. Auto-creates the tag as persistent if the slug isn’t registered yet. Idempotent: returnsalready_present: true if the tag was already attached.
Parameters
Slug to add. Regex:
^[a-z0-9][a-z0-9\-:]*[a-z0-9]$.Optional rationale recorded on the
tag_added annotation.Example input
Example output
remove_transaction_tag
Remove one tag from one transaction. Anote is recommended (it lands on the tag_removed annotation) but not required. Idempotent: returns already_absent: true if the tag wasn’t attached.
Parameters
Optional rationale recorded on the annotation.