Skip to main content
Breadbox does not have a dedicated review-queue table. The “review queue” is a tag view — the list of transactions that carry the needs-review tag. The workflow is built out of general-purpose primitives (tags, rules, annotations), which means you can reshape it to fit how your household actually wants to triage transactions.

​
How the workflow is assembled

Three pieces make up the default experience:
1

A seeded `needs-review` tag

Installed as an ephemeral tag — meaning the tag is expected to come off eventually, and every removal must include a short note that gets recorded on the transaction’s activity timeline.
2

A seeded rule on `on_create`

A system-created rule fires for every newly-synced transaction and applies the needs-review tag. No conditions — it matches everything by default.
3

A filter view in the dashboard

/reviews in the admin UI redirects to /transactions?tags=needs-review. There is no separate “reviews” page; the transactions list is the queue.
All three are configurable. The tag can be recolored or renamed, the rule can be narrowed or disabled, and you can layer your own tags on top for workflows Breadbox doesn’t ship by default.

​
Resolving a review

To take a transaction out of the queue, remove the needs-review tag. Because it is ephemeral, removal requires a note — the note is saved as an annotation so anyone (or any agent) looking at the transaction later can see why the review was closed. In the dashboard, the transaction detail view has a Remove tag action with a note prompt. An MCP-connected agent does the same thing in a single compound write via update_transactions — set the category, remove needs-review with a note, and optionally leave a comment, all in one operation. Leaving the tag in place is the “skip” action — the transaction stays in the queue for next time. There is no separate reject or approve state; the decision is captured by whichever category ends up on the transaction plus the note you leave when the tag comes off.
The REST API exposes PATCH /api/v1/transactions/{id}/category for category changes, but tag mutations currently live behind the admin UI and the MCP update_transactions tool. Day-to-day review work is done in the dashboard or by an agent — not via direct REST calls.

​
Making the workflow your own

The same primitives that power needs-review power any review-style workflow you want. Create a flagged tag for follow-ups, a disputed tag for charges to contest with your bank, a tax-deductible tag for end-of-year collection — each with its own rule conditions and its own lifecycle.
Common customizations:
  • Narrow the auto-tag rule so only transactions that need attention get flagged — for example, only uncategorized rows, only amounts above a threshold, or only accounts you actually reconcile.
  • Add parallel tags for specific workflows (e.g., a high-amount rule that tags anything over $500 in addition to needs-review), so you can filter to the subset you care about first.
  • Disable the auto-tag rule entirely if you don’t want every new transaction on the queue by default.

​
Disabling the auto-tag rule

The seeded rule is named Auto-tag new transactions for review and is owned by the system creator type. Find its ID from Rules in the dashboard (it is listed as system-created), or look it up via the API: 
curl -H "X-API-Key: bb_your_key" \
  http://localhost:8080/api/v1/rules \
  | jq '.rules[] | select(.name == "Auto-tag new transactions for review") | {id, short_id, enabled}'
Then disable it (either id or short_id works): 
curl -X PUT \
  -H "X-API-Key: bb_your_key" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}' \
  http://localhost:8080/api/v1/rules/<rule_id>
System-seeded rules can be disabled but not deleted, so you can always turn the default back on.
Disabling the rule only affects future syncs. Transactions already tagged needs-review stay tagged until you resolve them (or bulk-remove the tag).

​
AI agents in the workflow

Because the queue is just a tag filter, AI agents connected over MCP can participate using the same tools humans would:
  • query_transactions(tags=["needs-review"]) to fetch the backlog
  • count_transactions(tags=["needs-review"]) to check the size before diving in
  • update_transactions with a compound op (category_slug + tags_to_remove with a note + an optional comment) to resolve items in batches
  • Leave the tag in place when an agent isn’t confident — that’s the equivalent of “skipping”
A typical agent loop:
1

Fetch the backlog

count_transactions(tags=["needs-review"]) to size it up, then query_transactions(tags=["needs-review"], fields=core,category, limit=30).
2

Decide per transaction

For each row the agent inspects name, merchant, amount, and any pre-applied category. It applies your review guidelines (configurable in settings) to decide whether to accept the category, change it, or defer.
3

Resolve in batches

update_transactions with up to 50 compound ops — set category if needed, remove needs-review with a short rationale, optionally leave a comment.
4

Submit a report

POST /api/v1/reports with a title and markdown body summarizing the session and surfacing anything that was deferred.

​
Agent reports

Reports are separate from the review workflow itself — they’re how an agent summarizes what it just did. A report is a title + markdown body that lands in the dashboard under Reports with an unread badge until you open it. 
curl -X POST \
  -H "X-API-Key: bb_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Weekly transaction review — April 14–20",
    "body": "Reviewed 47 transactions. Resolved 41. Deferred 6 (still tagged needs-review):\n\n- k7Xm9pQ2: Unusually large charge at an unfamiliar merchant..."
  }' \
  http://localhost:8080/api/v1/reports

# Check unread count from a dashboard widget or automation
curl -H "X-API-Key: bb_your_key" \
  http://localhost:8080/api/v1/reports/unread-count
See the MCP overview for how to connect an AI agent to your Breadbox instance.