Skip to main content
Every tool in the reference follows the same handful of conventions. Reading this page once saves repeating them forty times.

​
Amounts

Breadbox uses the Plaid sign convention. It applies everywhere — REST, MCP, and the admin UI.
  • Positive amount — money leaving the account (debits, purchases, fees, payments out).
  • Negative amount — money entering the account (credits, deposits, refunds, transfers in).
A grocery charge of 42.50appearsas‘42.50‘.Adirectdepositof42.50 appears as `42.50`. A direct deposit of 2,500 appears as -2500.00. Every amount field ships with an iso_currency_code sibling ("USD", "EUR", etc.). Agents summing amounts must filter to one currency first — the server does not convert between them.

​
Compact IDs

Entity IDs returned by MCP tools are 8-character base62 strings: 
k7Xm9pQ2
Wm5kTrU9
Behind the scenes every row has both a full UUID and a short ID. The MCP response pipeline walks the JSON, replaces every id with the sibling short_id value, and drops the short_id field to save tokens. The REST API returns both unchanged. Tool inputs accept either form. transaction_id: "k7Xm9pQ2" and transaction_id: "a1b2c3d4-..." resolve to the same row.

​
Dates and date ranges

  • All dates are YYYY-MM-DD strings. No timezones — dates align with how the institution posted the transaction.
  • Where a tool takes start_date and end_date, start_date is inclusive and end_date is exclusive. January 2025 in full is start_date=2025-01-01&end_date=2025-02-01.
  • Some tools have sensible defaults — transaction_summary defaults to the last 30 days; merchant_summary defaults to the last 90 days. See the tool’s reference page.

​
Cursor pagination

Tools that return lists (query_transactions, list_transaction_rules) use opaque cursor pagination: 
{
  "data": [ ... ],
  "next_cursor": "eyJkYXRlIjoiMjAyNS0wMS0yNSIsImlkIjoiV201a1RyVTkifQ",
  "has_more": true
}
When has_more is true, pass the returned next_cursor on the next call to get the next page. When it’s false, next_cursor is null and there’s nothing more to fetch. Cursors are bound to the query shape — changing filters mid-pagination will produce meaningless results. Start a new query if you need to change filters.

​
Sessions

Sessions are automatic — Breadbox creates and binds one to every transport connection. There is no create_session tool and no session_id or reason field in any tool’s input schema. The MCP admin dashboard shows call history grouped by session. To add an audit label to an individual call, pass an optional reason string in the _meta block alongside the tool arguments: 
{
  "transaction_id": "k7Xm9pQ2",
  "category_slug": "food_and_drink_groceries",
  "_meta": { "reason": "categorizing clearly valid grocery charge" }
}
_meta.reason is optional and informational only — the server never rejects a call for omitting it.

​
Compound operations

update_transactions is Breadbox’s preferred write primitive. One call carries up to 50 per-transaction operations, and each operation is a bundle: set a category, add tags, remove tags, and attach a comment — all in one atomic database transaction per row. Every change lands as a single linked annotation in the activity timeline. Each operation in the batch is atomic — category, tags, and comment land together or not at all. Compound ops:
  • Write one linked annotation per transaction (covering the whole edit, not one per change).
  • Round-trip once for up to 50 transactions.
  • Give you per-row success/failure accounting in the response.
The tool details are on Transaction writes.
If you’re only doing one thing to one transaction — and the change is a category set with no accompanying tag or comment — passing a single-element operations array to update_transactions is still the right call. It writes one linked annotation, one round-trip.

​
Error shape

Tool errors come back as an MCP call result with isError: true and a text content block carrying JSON: 
{ "error": "operation failed: transaction k7Xm9pQ2 not found" }
The handler never panics and never throws — every error path returns this envelope. There is no structured error code the way REST returns {"error": {"code": "..."}}; MCP clients match on the message string or the presence of isError.

​
Amount filters and sign

Filters like min_amount and max_amount follow the same sign convention as the stored amounts.
  • Find debits over $100: min_amount=100.
  • Find credits only: max_amount=-0.01.
  • Find everything between 10and10 and 500 debits: min_amount=10&max_amount=500.
Zero is a valid filter value — the underlying fields are pointer types, so min_amount=0 actually filters, rather than being treated as “unset”.

​
Search modes

Tools that accept search also accept search_mode:
  • contains (default) — plain substring match. star matches Starbucks.
  • words — all words must appear, word-boundary aware. century link matches CenturyLink.
  • fuzzy — trigram similarity, tolerates typos. starbuks matches Starbucks.
Comma-separated values in search are ORed. search=starbucks,dunkin matches either. exclude_search uses the same syntax to filter results out.

​
Tag filters

query_transactions and count_transactions accept two tag filters:
  • tags — array, AND semantics. All tags must be present.
  • any_tag — array, OR semantics. At least one tag must match.
The review queue is just tags=["needs-review"].

​
Fields aliases

query_transactions accepts a fields parameter to prune the response:
  • minimal — name, amount, date
  • core — id, date, amount, name, iso_currency_code
  • category — category, category_primary_raw, category_detailed_raw
  • timestamps — created_at, updated_at, datetime, authorized_datetime
id is always included. Comma-separate aliases and custom field names: fields=core,category.

​
Limits

  • List tools default to limit=50, max 500.
  • update_transactions caps at 50 operations per call.
  • batch_create_rules caps at 100 items.
Exceeding a cap returns an error; the server does not silently truncate.
Last modified on June 4, 2026