# Breadbox

## Docs

- [Confirm a transaction match](https://docs.breadbox.sh/api-reference/account-links/confirm-a-transaction-match.md): Promotes an `auto` match to `confirmed`. **Requires `full_access` scope.**
- [Create account link](https://docs.breadbox.sh/api-reference/account-links/create-account-link.md): **Requires `full_access` scope.**
- [Delete account link](https://docs.breadbox.sh/api-reference/account-links/delete-account-link.md): **Requires `full_access` scope.**
- [Get account link](https://docs.breadbox.sh/api-reference/account-links/get-account-link.md)
- [List account links](https://docs.breadbox.sh/api-reference/account-links/list-account-links.md)
- [List transaction matches for a link](https://docs.breadbox.sh/api-reference/account-links/list-transaction-matches-for-a-link.md): Cursor-paginated list of matched transaction pairs across the linked accounts.
- [Manually pair two transactions](https://docs.breadbox.sh/api-reference/account-links/manually-pair-two-transactions.md): Creates a `confirmed` match between two transactions. **Requires `full_access` scope.**
- [Re-run reconciliation for a link](https://docs.breadbox.sh/api-reference/account-links/re-run-reconciliation-for-a-link.md): **Requires `full_access` scope.**
- [Reject a transaction match](https://docs.breadbox.sh/api-reference/account-links/reject-a-transaction-match.md): Marks the match `rejected`. **Requires `full_access` scope.**
- [Update account link](https://docs.breadbox.sh/api-reference/account-links/update-account-link.md): **Requires `full_access` scope.**
- [Get account](https://docs.breadbox.sh/api-reference/accounts/get-account.md)
- [Get account detail](https://docs.breadbox.sh/api-reference/accounts/get-account-detail.md): Returns the standard account fields plus per-currency balances and the most recent 25 transactions.
- [List accounts](https://docs.breadbox.sh/api-reference/accounts/list-accounts.md): Returns every account visible to the API key. Bounded resource — no pagination.
- [Update account](https://docs.breadbox.sh/api-reference/accounts/update-account.md): Partially update mutable fields on a single account. Omit a key to leave the column unchanged. Send an explicit empty string to clear `display_name`.
- [Create agent definition](https://docs.breadbox.sh/api-reference/agents/create-agent-definition.md): Creates a Claude Agent SDK definition. Body includes the usual `name`, `slug`, `prompt`, `model`, `max_turns`, `max_budget_usd`, `tool_scope`, `allowed_tools`, `schedule_cron`, and the iter-30 `trigger_on_sync_complete` flag (fire after every successful sync, in addition to any cron schedule). **Req…
- [Delete an agent definition](https://docs.breadbox.sh/api-reference/agents/delete-an-agent-definition.md): Historical runs preserved (FK SET NULL). **Requires `full_access` scope.**
- [Disable an agent](https://docs.breadbox.sh/api-reference/agents/disable-an-agent.md): Sets enabled=false. **Requires `full_access` scope.**
- [Enable an agent](https://docs.breadbox.sh/api-reference/agents/enable-an-agent.md): Sets enabled=true. **Requires `full_access` scope.**
- [Get agent subsystem settings](https://docs.breadbox.sh/api-reference/agents/get-agent-subsystem-settings.md): Returns agent.* config from `app_config`. Token fields are masked (e.g. `"sk-ant-oat01-XXXXXXXX••••wxyz"`); the full plaintext never leaves the server.
- [Get one agent definition](https://docs.breadbox.sh/api-reference/agents/get-one-agent-definition.md)
- [Get one agent run](https://docs.breadbox.sh/api-reference/agents/get-one-agent-run.md): Resolves by short_id or UUID.
- [List agent definitions](https://docs.breadbox.sh/api-reference/agents/list-agent-definitions.md): Returns all agent definitions with `last_run` inlined per definition.
- [List recent errored agent runs across all agents](https://docs.breadbox.sh/api-reference/agents/list-recent-errored-agent-runs-across-all-agents.md): Returns errored agent_runs from the last `hours` hours (default 24), joined with agent slug + name for deep-linking. Powers the v2 SPA's "Run-failed banner" on /v2/agents. Bare JSON array; most-recent first.
- [List runs across all agents](https://docs.breadbox.sh/api-reference/agents/list-runs-across-all-agents.md): Cross-agent run history. Each row carries `agent_slug` + `agent_name` in addition to the standard run fields, so callers can render an agent column without a second fetch. Powers the v2 SPA's global `/v2/agents/runs` view. Same filters as `/agents/{slug}/runs`, plus the optional `agent=<slug>` narro…
- [List runs for one agent](https://docs.breadbox.sh/api-reference/agents/list-runs-for-one-agent.md): Offset-paginated run history.
- [List the embedded agent prompt-block library](https://docs.breadbox.sh/api-reference/agents/list-the-embedded-agent-prompt-block-library.md): Returns every parsed block under `prompts/agents/*.md` — id, title, one-line description, taxonomic group (`strategy` / `depth` / `integration` / `knowledge`), and full markdown content. Backs the v2 SPA's assembly-bench prompt builder at `/v2/prompts/build`. The block set is fixed at build time; ed…
- [Partial update of an agent definition](https://docs.breadbox.sh/api-reference/agents/partial-update-of-an-agent-definition.md): Omitted fields are unchanged. **Requires `full_access` scope.**
- [Readiness probe for the agent subsystem](https://docs.breadbox.sh/api-reference/agents/readiness-probe-for-the-agent-subsystem.md): Side-effect-free check that returns whether the agent subsystem is ready to fire a run — auth configured + sidecar binary discoverable. Used by the v2 SPA list page to surface onboarding hints inline. Does NOT call Anthropic; for a live round-trip use POST /agents/test instead.
- [Run the agent cleanup pass on demand](https://docs.breadbox.sh/api-reference/agents/run-the-agent-cleanup-pass-on-demand.md): Synchronously runs the same prune pass the 3:15 AM cron does: deletes completed agent_runs older than `agent.run_retention_days` and prunes the matching `*.ndjson` transcripts under `agent.transcript_dir`. Returns the counts. Safe to call repeatedly — a no-op when nothing's eligible. **Requires `ful…
- [Run the agent diagnostic smoke test](https://docs.breadbox.sh/api-reference/agents/run-the-agent-diagnostic-smoke-test.md): Spawns the breadbox-agent sidecar with a tiny "say OK" prompt and returns the result. Bypasses agent_definitions, mints no API key, writes no agent_runs row. Cost-bounded to ~5¢. **Requires `full_access` scope.**
- [Set or clear the operator note on a run](https://docs.breadbox.sh/api-reference/agents/set-or-clear-the-operator-note-on-a-run.md): Body: `{ "note": "..." }`. Empty string clears the field. Capped at 2000 chars. **Requires `full_access` scope.**
- [Stream agent run transcript](https://docs.breadbox.sh/api-reference/agents/stream-agent-run-transcript.md): Returns the NDJSON transcript file. 404 when not yet written.
- [Trigger an immediate agent run](https://docs.breadbox.sh/api-reference/agents/trigger-an-immediate-agent-run.md): Synchronously runs the named agent. Returns the resulting `agent_runs` row. Status may be `success`, `error`, or `timeout`. Optional body accepts `prompt_prefix` (prepends operator context to the saved prompt for this fire only) and `prompt` (replaces the saved prompt entirely for this fire — powers…
- [Update agent subsystem settings](https://docs.breadbox.sh/api-reference/agents/update-agent-subsystem-settings.md): PATCH-style update of agent.* config. Nil fields are unchanged; empty-string for token fields clears the stored encrypted value. Token values are AES-256-GCM encrypted at rest. **Requires `full_access` scope.**
- [List annotations on a transaction](https://docs.breadbox.sh/api-reference/annotations/list-annotations-on-a-transaction.md): Annotations are append-only structured notes left by users or agents.
- [Create API key](https://docs.breadbox.sh/api-reference/api-keys/create-api-key.md): Returns the plaintext key **once** in `key`. Persist it immediately — subsequent reads expose only the prefix. **Requires `full_access` scope.**
- [Identify the calling API key (whoami)](https://docs.breadbox.sh/api-reference/api-keys/identify-the-calling-api-key-whoami.md): Returns the API key record corresponding to the presented credential — name, prefix, scope, actor type/name. The full secret is never re-exposed. Used by `breadbox auth whoami` so agents and humans can confirm which identity the CLI is acting under. Any scope; the data only describes the caller's ow…
- [List API keys](https://docs.breadbox.sh/api-reference/api-keys/list-api-keys.md): Returns metadata only (prefix, scope, last_used_at). The plaintext key is never returned. **Requires `full_access` scope.**
- [Revoke an API key](https://docs.breadbox.sh/api-reference/api-keys/revoke-an-api-key.md): Soft-revokes by setting `revoked_at`. **Requires `full_access` scope.**
- [Initiate the device-code flow](https://docs.breadbox.sh/api-reference/auth/initiate-the-device-code-flow.md): Mint a pending device-code pair. Unauthenticated — the device_code returned in the body is itself the credential the CLI uses to poll. The user_code is the human-facing 8-char approval code (formatted XXXX-XXXX) the operator enters on the verification page.
- [Poll the status of a pending device code](https://docs.breadbox.sh/api-reference/auth/poll-the-status-of-a-pending-device-code.md): Unauthenticated; the device_code is the credential. Returns one of: - `200 {status: "authorization_pending"}` — keep polling - `200 {status: "approved", token: "bb_..."}` — token returned exactly once - `400 {error: {code: "EXPIRED"}}` — past the TTL - `400 {error: {code: "DENIED"}}` — operator refu…
- [Create category](https://docs.breadbox.sh/api-reference/categories/create-category.md): **Requires `full_access` scope.**
- [Delete category](https://docs.breadbox.sh/api-reference/categories/delete-category.md): **Requires `full_access` scope.**
- [Export categories as TSV](https://docs.breadbox.sh/api-reference/categories/export-categories-as-tsv.md): Returns the full category table as `text/tab-separated-values` for backup or migration.
- [Get category](https://docs.breadbox.sh/api-reference/categories/get-category.md)
- [Import categories from TSV](https://docs.breadbox.sh/api-reference/categories/import-categories-from-tsv.md): Bulk-create or upsert categories from a TSV body. **Requires `full_access` scope.**
- [List categories](https://docs.breadbox.sh/api-reference/categories/list-categories.md): Returns the household's categories (2-level hierarchy). Bounded resource.
- [Merge another category into this one](https://docs.breadbox.sh/api-reference/categories/merge-another-category-into-this-one.md): Reassigns transactions, rules, and child categories from `from_category_id` into the path category, then deletes the source. **Requires `full_access` scope.**
- [Update category](https://docs.breadbox.sh/api-reference/categories/update-category.md): **Requires `full_access` scope.**
- [Create comment](https://docs.breadbox.sh/api-reference/comments/create-comment.md): **Requires `full_access` scope.**
- [Delete comment](https://docs.breadbox.sh/api-reference/comments/delete-comment.md): **Requires `full_access` scope.**
- [List comments on a transaction](https://docs.breadbox.sh/api-reference/comments/list-comments-on-a-transaction.md)
- [Update comment](https://docs.breadbox.sh/api-reference/comments/update-comment.md): **Requires `full_access` scope.**
- [Begin reauth flow](https://docs.breadbox.sh/api-reference/connections/begin-reauth-flow.md): Provider-specific reauth handshake. For Plaid this returns a `link_token` in update mode. **Requires `full_access` scope.**
- [Complete reauth flow](https://docs.breadbox.sh/api-reference/connections/complete-reauth-flow.md): Confirms reauth and flips `status='active'`. **Requires `full_access` scope.**
- [Create a connection](https://docs.breadbox.sh/api-reference/connections/create-a-connection.md): Generic, provider-discriminated create. Supersedes `POST /connections/plaid/exchange`, `POST /connections/teller`, and `POST /connections/csv/import`.
- [Create a Teller connection](https://docs.breadbox.sh/api-reference/connections/create-a-teller-connection.md): **Deprecated** — use `POST /api/v1/connections` with `provider:"teller"` instead. This route remains as a thin pass-through to the generic dispatch path.
- [Disable a provider](https://docs.breadbox.sh/api-reference/connections/disable-a-provider.md): Clears every `app_config` row tied to the named provider (Plaid: client_id/secret/env; Teller: app_id/env/cert/key/webhook secret) and re-runs the live provider init so the in-memory map drops the provider. Existing connections stay in the DB and continue to surface in listings, but sync attempts fa…
- [Disconnect (soft-delete) a connection](https://docs.breadbox.sh/api-reference/connections/disconnect-soft-delete-a-connection.md): Sets `status='disconnected'`. Accounts/transactions are preserved with `connection_id` set to NULL. **Requires `full_access` scope.**
- [Exchange a Plaid public_token](https://docs.breadbox.sh/api-reference/connections/exchange-a-plaid-public_token.md): **Deprecated** — use `POST /api/v1/connections` with `provider:"plaid"` instead. This route remains as a thin pass-through to the generic dispatch path.
- [Get a single provider entry](https://docs.breadbox.sh/api-reference/connections/get-a-single-provider-entry.md): Same shape as one entry in `GET /providers`.
- [Get connection](https://docs.breadbox.sh/api-reference/connections/get-connection.md)
- [Get connection status](https://docs.breadbox.sh/api-reference/connections/get-connection-status.md)
- [Import a CSV](https://docs.breadbox.sh/api-reference/connections/import-a-csv.md): **Deprecated** — use `POST /api/v1/connections` with `provider:"csv"` instead. This route remains as a thin pass-through to the generic dispatch path.
- [Issue a Plaid Link token](https://docs.breadbox.sh/api-reference/connections/issue-a-plaid-link-token.md): **Deprecated** — use `POST /api/v1/providers/plaid/link-session` instead. This route remains as a thin pass-through to the generic dispatch path.
- [List configured providers](https://docs.breadbox.sh/api-reference/connections/list-configured-providers.md): Returns the self-describing registry of bank-data providers this server supports, including which are configured, their capabilities, and the shape of credentials they accept on `POST /connections`.
- [List connections](https://docs.breadbox.sh/api-reference/connections/list-connections.md)
- [Mint a hosted-link session](https://docs.breadbox.sh/api-reference/connections/mint-a-hosted-link-session.md): Creates a hosted-link session and returns the URL an end-user should open in their browser to add a new bank connection. The response carries a one-time-only bearer `token` and a fully-qualified `url` (scheme + host + `/link/<token>`). The token is **never** echoed back by `GET /connections/link/{id…
- [Mint a re-auth hosted-link session for a connection](https://docs.breadbox.sh/api-reference/connections/mint-a-re-auth-hosted-link-session-for-a-connection.md): Creates a hosted-link session pinned to one existing bank connection for re-authentication. The user_id, provider, action (`"relink"`), connection_id, and `single_use=true` are all derived from the connection row — the request body has no say.
- [Pause or resume a connection](https://docs.breadbox.sh/api-reference/connections/pause-or-resume-a-connection.md): Toggles automated sync. **Requires `full_access` scope.**
- [Poll a hosted-link session](https://docs.breadbox.sh/api-reference/connections/poll-a-hosted-link-session.md): Returns the current state of a hosted-link session. Accepts either the canonical UUID or the 8-char short_id as `{id}`.
- [Preview a CSV import](https://docs.breadbox.sh/api-reference/connections/preview-a-csv-import.md): Parses a CSV body and returns the inferred column mapping plus a sample of rows. No data is persisted. **Requires `full_access` scope.**
- [Round-trip a provider credentials check](https://docs.breadbox.sh/api-reference/connections/round-trip-a-provider-credentials-check.md): Validates the server-side credentials for the named provider. CSV has no credentials and always returns ok=true. Plaid hits `/institutions/get` with a tiny payload; Teller validates the stored cert/key pair (file path or in-memory PEM) against `crypto/tls`.
- [Start a provider link session](https://docs.breadbox.sh/api-reference/connections/start-a-provider-link-session.md): Generic link-token start. Replaces the deprecated provider-specific link-token routes.
- [Trigger sync on a connection](https://docs.breadbox.sh/api-reference/connections/trigger-sync-on-a-connection.md): Enqueues a manual sync. **Requires `full_access` scope.**
- [Update connection sync interval](https://docs.breadbox.sh/api-reference/connections/update-connection-sync-interval.md): **Requires `full_access` scope.**
- [Liveness probe](https://docs.breadbox.sh/api-reference/health/liveness-probe.md): Returns HTTP 200 with no dependency checks. Suitable for load-balancer health checks.
- [Liveness probe (alias)](https://docs.breadbox.sh/api-reference/health/liveness-probe-alias.md): Identical to `/health`.
- [Readiness probe](https://docs.breadbox.sh/api-reference/health/readiness-probe.md): Verifies database connectivity and that the scheduler is running.
- [Setup readiness report](https://docs.breadbox.sh/api-reference/health/setup-readiness-report.md): Returns a one-shot readiness/setup summary intended for the `breadbox doctor` CLI command. Any API key (read or write) works. Fields are best-effort — a per-row failure stays zero and the report still ships. The endpoint returns 503 only when the database is plainly unreachable.
- [Delete a report](https://docs.breadbox.sh/api-reference/reports/delete-a-report.md): **Requires `full_access` scope.**
- [Get a report](https://docs.breadbox.sh/api-reference/reports/get-a-report.md)
- [List agent reports](https://docs.breadbox.sh/api-reference/reports/list-agent-reports.md): Bounded by recency; not cursor-paginated.
- [Mark all reports as read](https://docs.breadbox.sh/api-reference/reports/mark-all-reports-as-read.md): **Requires `full_access` scope.**
- [Mark report as read](https://docs.breadbox.sh/api-reference/reports/mark-report-as-read.md): **Requires `full_access` scope.**
- [Mark report as unread](https://docs.breadbox.sh/api-reference/reports/mark-report-as-unread.md): **Requires `full_access` scope.**
- [Submit a report](https://docs.breadbox.sh/api-reference/reports/submit-a-report.md): AI agents call this to record summaries or flagged transactions. **Requires `full_access` scope.**
- [Unread report count](https://docs.breadbox.sh/api-reference/reports/unread-report-count.md)
- [Apply a single rule retroactively](https://docs.breadbox.sh/api-reference/rules/apply-a-single-rule-retroactively.md): **Requires `full_access` scope.**
- [Apply all rules retroactively](https://docs.breadbox.sh/api-reference/rules/apply-all-rules-retroactively.md): Replays every enabled rule against the historical transaction set (skipping `category_override = true`). **Requires `full_access` scope.**
- [Batch create rules](https://docs.breadbox.sh/api-reference/rules/batch-create-rules.md): Create many rules in a single transaction. **Requires `full_access` scope.**
- [Create rule](https://docs.breadbox.sh/api-reference/rules/create-rule.md): **Requires `full_access` scope.**
- [Delete rule](https://docs.breadbox.sh/api-reference/rules/delete-rule.md): **Requires `full_access` scope.**
- [Get rule](https://docs.breadbox.sh/api-reference/rules/get-rule.md)
- [List rules](https://docs.breadbox.sh/api-reference/rules/list-rules.md): Cursor-paginated list of transaction rules.
- [Preview rule matches](https://docs.breadbox.sh/api-reference/rules/preview-rule-matches.md): Dry-runs a rule definition against existing transactions and returns the first N matches without persisting. **Requires `full_access` scope.**
- [Rule sync history](https://docs.breadbox.sh/api-reference/rules/rule-sync-history.md): Recent sync-time evaluations of this rule.
- [Update rule](https://docs.breadbox.sh/api-reference/rules/update-rule.md): **Requires `full_access` scope.**
- [Get a single config entry](https://docs.breadbox.sh/api-reference/settings/get-a-single-config-entry.md): Same masking + `?reveal=true` semantics as the list endpoint.
- [Get provider configuration](https://docs.breadbox.sh/api-reference/settings/get-provider-configuration.md): Returns current Plaid + Teller config flags. Secrets are masked.
- [List app_config entries](https://docs.breadbox.sh/api-reference/settings/list-app_config-entries.md): Returns every row in the `app_config` table with the effective source (`env` / `db` / `default`). Secret-flagged values are masked unless `?reveal=true` is set. A denylist of keys (`ENCRYPTION_KEY` and the Teller cert/key PEM rows) is always masked and never writable via this surface — manage them t…
- [Remove a db-sourced config value](https://docs.breadbox.sh/api-reference/settings/remove-a-db-sourced-config-value.md): Drops the `app_config` row. The effective value falls back to env or the compile-in default. The always-denied key list returns `403`.
- [Set a config value](https://docs.breadbox.sh/api-reference/settings/set-a-config-value.md): Writes the named value to the `app_config` table. The always-denied key list (`ENCRYPTION_KEY`, `teller_cert_pem`, `teller_key_pem`) returns `403 FORBIDDEN`.
- [Update Plaid configuration](https://docs.breadbox.sh/api-reference/settings/update-plaid-configuration.md): Persists Plaid credentials in the encrypted `app_config` table. Pass null for any field to clear it. **Requires `full_access` scope.**
- [Update Teller configuration](https://docs.breadbox.sh/api-reference/settings/update-teller-configuration.md): Persists Teller credentials (application ID, certificate, key) in the encrypted `app_config` table. **Requires `full_access` scope.**
- [Get a sync log](https://docs.breadbox.sh/api-reference/sync/get-a-sync-log.md)
- [List sync logs](https://docs.breadbox.sh/api-reference/sync/list-sync-logs.md): Cursor-paginated list of sync runs across all connections.
- [Provider-grouped sync health](https://docs.breadbox.sh/api-reference/sync/provider-grouped-sync-health.md)
- [Sync health overview](https://docs.breadbox.sh/api-reference/sync/sync-health-overview.md): Fleet-wide sync health (counts of `error`, `pending_reauth`, stale connections).
- [Sync statistics](https://docs.breadbox.sh/api-reference/sync/sync-statistics.md): Sync run counts and timing aggregates over a configurable window.
- [Trigger a sync across all active connections](https://docs.breadbox.sh/api-reference/sync/trigger-a-sync-across-all-active-connections.md): **Requires `full_access` scope.**
- [Add a tag to a transaction](https://docs.breadbox.sh/api-reference/tags/add-a-tag-to-a-transaction.md): **Requires `full_access` scope.**
- [Create tag](https://docs.breadbox.sh/api-reference/tags/create-tag.md): **Requires `full_access` scope.**
- [Delete tag](https://docs.breadbox.sh/api-reference/tags/delete-tag.md): **Requires `full_access` scope.**
- [Get tag](https://docs.breadbox.sh/api-reference/tags/get-tag.md)
- [List tags](https://docs.breadbox.sh/api-reference/tags/list-tags.md)
- [Remove a tag from a transaction](https://docs.breadbox.sh/api-reference/tags/remove-a-tag-from-a-transaction.md): **Requires `full_access` scope.**
- [Update tag](https://docs.breadbox.sh/api-reference/tags/update-tag.md): **Requires `full_access` scope.**
- [Batch categorize transactions](https://docs.breadbox.sh/api-reference/transactions/batch-categorize-transactions.md): Apply a category to many transactions in one call. **Requires `full_access` scope.**
- [Bulk recategorize transactions](https://docs.breadbox.sh/api-reference/transactions/bulk-recategorize-transactions.md): Re-run categorization across a filtered set of transactions. Useful after rule changes. **Requires `full_access` scope.**
- [Count transactions](https://docs.breadbox.sh/api-reference/transactions/count-transactions.md): Returns the count of transactions matching the same filter set as `GET /transactions`.
- [Delete transaction](https://docs.breadbox.sh/api-reference/transactions/delete-transaction.md): Soft-deletes the transaction (sets `deleted_at`). **Requires `full_access` scope.**
- [Get transaction](https://docs.breadbox.sh/api-reference/transactions/get-transaction.md)
- [List transactions](https://docs.breadbox.sh/api-reference/transactions/list-transactions.md): Filterable, cursor-paginated transaction query.
- [Merchant summary](https://docs.breadbox.sh/api-reference/transactions/merchant-summary.md): Top merchants by spending, with counts and totals per currency.
- [Reset transaction category](https://docs.breadbox.sh/api-reference/transactions/reset-transaction-category.md): Clears the manual override and re-runs rule attribution. **Requires `full_access` scope.**
- [Restore deleted transaction](https://docs.breadbox.sh/api-reference/transactions/restore-deleted-transaction.md): Clears `deleted_at`. **Requires `full_access` scope.**
- [Set transaction category](https://docs.breadbox.sh/api-reference/transactions/set-transaction-category.md): Sets `category_id` and `category_override = true`. **Requires `full_access` scope.**
- [Transaction summary](https://docs.breadbox.sh/api-reference/transactions/transaction-summary.md): Aggregate totals (income, spending, net) grouped by currency.
- [Update transactions in bulk](https://docs.breadbox.sh/api-reference/transactions/update-transactions-in-bulk.md): Apply a patch (category, tags, attribution, etc.) to a filtered or explicit set of transactions. **Requires `full_access` scope.**
- [Create a login method for a user](https://docs.breadbox.sh/api-reference/users/create-a-login-method-for-a-user.md): **Requires `full_access` scope.**
- [Create user](https://docs.breadbox.sh/api-reference/users/create-user.md): **Requires `full_access` scope.**
- [Delete a login account by its own id (no parent user_id required)](https://docs.breadbox.sh/api-reference/users/delete-a-login-account-by-its-own-id-no-parent-user_id-required.md): **Requires `full_access` scope.**
- [Delete a login method](https://docs.breadbox.sh/api-reference/users/delete-a-login-method.md): **Requires `full_access` scope.**
- [Delete user](https://docs.breadbox.sh/api-reference/users/delete-user.md): **Requires `full_access` scope.**
- [Get user](https://docs.breadbox.sh/api-reference/users/get-user.md)
- [Issue a fresh setup token for a login account](https://docs.breadbox.sh/api-reference/users/issue-a-fresh-setup-token-for-a-login-account.md): Flat alias for `/users/{user_id}/login/{login_id}/regenerate-token`. Response includes the plaintext `setup_token` exactly once. **Requires `full_access` scope.**
- [List a user's login methods](https://docs.breadbox.sh/api-reference/users/list-a-users-login-methods.md): Returns admin login records (email/password, magic-link, etc.) for the target user. **Requires `full_access` scope.**
- [List every login account (flat — no parent user_id)](https://docs.breadbox.sh/api-reference/users/list-every-login-account-flat-—-no-parent-user_id.md): Top-level convenience for the headless CLI. Identical payload to the nested per-user endpoint, but returns the full set across users. **Requires `full_access` scope.** `setup_token` is never echoed here.
- [List users](https://docs.breadbox.sh/api-reference/users/list-users.md)
- [Regenerate a login's API/magic-link token](https://docs.breadbox.sh/api-reference/users/regenerate-a-logins-apimagic-link-token.md): **Requires `full_access` scope.**
- [Update a login method](https://docs.breadbox.sh/api-reference/users/update-a-login-method.md): **Requires `full_access` scope.**
- [Update user](https://docs.breadbox.sh/api-reference/users/update-user.md): **Requires `full_access` scope.**
- [Wipe a user's connections, accounts, and transactions](https://docs.breadbox.sh/api-reference/users/wipe-a-users-connections-accounts-and-transactions.md): Destructive — disconnects every connection owned by this user and cascades through accounts/transactions per the FK policy. **Requires `full_access` scope.**
- [Get server version](https://docs.breadbox.sh/api-reference/version/get-server-version.md): Returns the running server version plus update-availability metadata. No authentication.
- [List recent webhook events](https://docs.breadbox.sh/api-reference/webhooks/list-recent-webhook-events.md): Paginated list of inbound provider webhooks (event_type, status, connection_id, institution name, created_at). Filters: `provider`, `status`, `page`, `limit` (max 200).
- [Re-trigger the sync the webhook would have caused](https://docs.breadbox.sh/api-reference/webhooks/re-trigger-the-sync-the-webhook-would-have-caused.md): The event row's raw payload is hashed-only, so the server can't re-deliver it verbatim — instead, it kicks a manual `Sync` against the connection the event was associated with. Events without a connection return 200 with `triggered: false`.
- [API authentication](https://docs.breadbox.sh/api/authentication.md): How to create and use Breadbox API keys, understand read_only and full_access scopes, pass the X-API-Key header, and handle auth errors.
- [API overview](https://docs.breadbox.sh/api/overview.md): Base URL structure, authentication, JSON response format, error codes, amount sign conventions, and health check endpoints for the Breadbox REST API.
- [API pagination](https://docs.breadbox.sh/api/pagination.md): How Breadbox cursor pagination works, how to pass the cursor parameter, default and max limits, and a complete pagination loop example.
- [Changelog](https://docs.breadbox.sh/changelog.md): What's new in Breadbox — user-facing changes since the V1 docs launch.
- [Agent automation](https://docs.breadbox.sh/cli/agents.md): Drive the Claude Agent SDK subsystem from the CLI — list scheduled agents, trigger immediate runs, and smoke-test the sidecar binary.
- [CLI authentication](https://docs.breadbox.sh/cli/authentication.md): How the breadbox CLI manages credentials — device-code login, paste-mode, local bootstrap, the hosts.toml file, and the BREADBOX_HOST and BREADBOX_TOKEN env vars.
- [Command reference](https://docs.breadbox.sh/cli/commands.md): Every breadbox CLI command grouped by noun — auth, server, accounts, transactions, categories, tags, rules, connections, sync, csv, providers, users, logins, reports, keys, config, backup, webhooks, and agent.
- [Headless deployment](https://docs.breadbox.sh/cli/headless.md): Patterns for driving Breadbox from agent hosts, CI runners, and remote scripts using the lite (breadbox-cli) build — same-host agents, remote agents, scheduled jobs.
- [Install the CLI](https://docs.breadbox.sh/cli/installation.md): Get the breadbox or breadbox-cli binary onto your machine — pre-built releases, building from source, and picking between the full, headless, and lite builds.
- [Output and exit codes](https://docs.breadbox.sh/cli/output.md): How the breadbox CLI formats its output — human tables, JSON, NDJSON, field selection — and the exit codes scripts and agents can branch on.
- [CLI overview](https://docs.breadbox.sh/cli/overview.md): The breadbox command-line tool — what it is, the three build flavors, and where it fits alongside the REST API and MCP server.
- [Create and manage API keys](https://docs.breadbox.sh/configuration/api-keys.md): Generate scoped API keys to authenticate REST API and MCP calls, control access with read-only or full-access scopes, and revoke keys you no longer need.
- [App config and precedence](https://docs.breadbox.sh/configuration/app-config.md): How Breadbox resolves settings — environment variables override the app_config table, which overrides built-in defaults — and the CLI surface for managing DB-sourced values.
- [Back up and restore your Breadbox data](https://docs.breadbox.sh/configuration/backup.md): Back up your PostgreSQL database and ENCRYPTION_KEY, restore from a dump or Docker volume snapshot, and automate daily backups with a cron script.
- [Configure Breadbox with environment variables](https://docs.breadbox.sh/configuration/environment.md): Set environment variables to configure Breadbox, generate your encryption key, and understand how env vars override dashboard settings.
- [Import transactions from CSV](https://docs.breadbox.sh/connections/csv-import.md): Upload a CSV export from any bank, map columns to Breadbox fields, and import transactions for institutions not covered by Plaid or Teller.
- [Connect your bank accounts](https://docs.breadbox.sh/connections/overview.md): Learn how Breadbox connects to your banks via Plaid, Teller, or CSV import, and how to manage connection health from the admin dashboard.
- [Connect banks with Plaid](https://docs.breadbox.sh/connections/plaid.md): Set up your Plaid developer account, enter credentials in the Breadbox setup wizard, and link your first bank account using the Plaid Link flow.
- [Connect banks with Teller](https://docs.breadbox.sh/connections/teller.md): Set up your Teller App ID and mTLS certificates, then link bank accounts using the Teller Connect flow from the Breadbox admin dashboard.
- [Breadbox in a nutshell](https://docs.breadbox.sh/guides/breadbox-in-a-nutshell.md): A two-minute tour of the three primitives that every workflow is built from — Categories, Tags, and Rules — plus the seeded `needs-review` tag that ties them together.
- [Build a custom dashboard with Claude](https://docs.breadbox.sh/guides/custom-dashboard-with-claude.md): Hand Claude the Breadbox API (or MCP) and have it generate a React artifact that renders your transaction data however you want it — a personal spending dashboard in a single prompt.
- [Gmail cross-referencing for bills](https://docs.breadbox.sh/guides/gmail-cross-referencing.md): Use a Gmail MCP alongside Breadbox so an agent can confirm generic billers (PG&E, Comcast, Verizon) by matching the transaction amount to the billing email before categorizing.
- [Multi-agent reviewer flows](https://docs.breadbox.sh/guides/multi-agent-reviewer.md): Two patterns for splitting the review queue across specialist agents — a delegator that re-tags work for downstream agents, and a flat set of specialists that filter by their own tags.
- [On-demand analysis](https://docs.breadbox.sh/guides/on-demand-analysis.md): Ask Claude about your spending — prompt patterns that work, and the two gotchas (currency mixing, attribution) to watch for in the answers.
- [Recurring workflows with Openclaw](https://docs.breadbox.sh/guides/openclaw-recurring-workflows.md): Use Openclaw's autonomous scheduling and sub-agent primitives to run Breadbox transaction triage, anomaly alerts, and session hygiene on a continuous cadence — without manual intervention.
- [Using Breadbox with AI agents](https://docs.breadbox.sh/guides/overview.md): The opinionated shape of how Breadbox is meant to be used day to day: data flows in, one or more agents review it on a cadence, you step in only when something needs a human.
- [Scheduled agents](https://docs.breadbox.sh/guides/scheduled-agents.md): Configure a scheduled Claude Agent SDK run inside Breadbox — define the prompt, set the schedule, attach prompt blocks, and inspect runs and transcripts.
- [Single routine reviewer](https://docs.breadbox.sh/guides/single-routine-reviewer.md): The baseline agent workflow: one agent, one schedule, the `needs-review` tag. Covers the loop, the MCP tools involved, and a system prompt you can paste into your agent.
- [Tracking your subscriptions](https://docs.breadbox.sh/guides/tracking-subscriptions.md): Detect recurring charges by combining `merchant_summary` queries with amount-and-cadence heuristics, tag them `subscription`, and layer a rule that auto-tags known subscriptions at sync time.
- [Understanding rules](https://docs.breadbox.sh/guides/understanding-rules.md): A primer on the Breadbox rule DSL — how to build condition trees, what actions are available, and four worked examples you can adapt.
- [Zelle / Venmo analysis](https://docs.breadbox.sh/guides/zelle-venmo-analysis.md): Instructing an agent to categorize peer-to-peer transfers when the bank description is opaque — cross-referencing timing, amounts, and frequency, and asking humans for help when the signal isn't there.
- [Install Breadbox](https://docs.breadbox.sh/installation.md): The recommended one-liner installs Breadbox on macOS or Linux; alternate paths (Docker Compose, binary, go install, from source) are available for specialist needs.
- [Make Breadbox reachable from the internet](https://docs.breadbox.sh/installation/remote-hosting.md): Give your Breadbox instance a public HTTPS URL so MCP clients and bank webhooks can reach it.
- [What is Breadbox?](https://docs.breadbox.sh/introduction.md): Breadbox syncs your household’s financial data into a PostgreSQL database you control, then exposes it through a built-in MCP server and a REST API.
- [Give AI agents access to your finances with Breadbox MCP](https://docs.breadbox.sh/mcp/overview.md): Breadbox exposes your household financial data to AI agents via the Model Context Protocol, letting Claude query accounts, transactions, and more.
- [Accounts and users MCP reference](https://docs.breadbox.sh/mcp/reference/accounts.md): MCP read tools for listing bank accounts and family members — the ID-discovery tools most agent sessions start with.
- [Category read MCP reference](https://docs.breadbox.sh/mcp/reference/categories.md): MCP read tools for listing and exporting the category taxonomy. Category writes (import) live on a separate page.
- [Category write MCP reference](https://docs.breadbox.sh/mcp/reference/categories-write.md): Import category definitions from TSV. Category reads live on the Categories page.
- [Categorization MCP reference](https://docs.breadbox.sh/mcp/reference/categorization.md): MCP write tools for setting, batching, bulk-applying, resetting, and retroactively re-running categorization.
- [Connections and sync read MCP reference](https://docs.breadbox.sh/mcp/reference/connections-sync.md): MCP read tools for inspecting connection health and account links.
- [Connections and sync write MCP reference](https://docs.breadbox.sh/mcp/reference/connections-write.md): Trigger syncs and manage account links. Connection read tools live on Connections & sync.
- [MCP conventions](https://docs.breadbox.sh/mcp/reference/conventions.md): Amount sign, compact IDs, cursor pagination, session_id/reason requirements, compound ops, and error shape — the cross-cutting rules every Breadbox MCP tool follows.
- [Transaction match MCP reference](https://docs.breadbox.sh/mcp/reference/matches.md): Confirm or reject auto-matched transaction pairs produced by account links.
- [MCP reference overview](https://docs.breadbox.sh/mcp/reference/overview.md): Breadbox MCP transports, authentication, scope-based tool filtering, write-session requirements, and how MCP tools map to the REST API.
- [Report MCP reference](https://docs.breadbox.sh/mcp/reference/reports.md): Submit an agent report to the household dashboard.
- [Rule read MCP reference](https://docs.breadbox.sh/mcp/reference/rules.md): MCP read tools for listing transaction rules and previewing condition matches. Rule writes live on a separate page.
- [Rule write MCP reference](https://docs.breadbox.sh/mcp/reference/rules-write.md): Create, update, delete, and batch-create transaction rules. Apply rules retroactively.
- [Session MCP reference](https://docs.breadbox.sh/mcp/reference/sessions.md): Start an audit session before performing write operations.
- [Tag read MCP reference](https://docs.breadbox.sh/mcp/reference/tags.md): MCP read tool for listing tags. Tag writes live on the Tag writes page; tagging transactions lives on Transaction writes.
- [Tag write MCP reference](https://docs.breadbox.sh/mcp/reference/tags-write.md): Create, update, and delete tags. Attaching tags to transactions lives on Transaction writes.
- [Transaction read MCP reference](https://docs.breadbox.sh/mcp/reference/transactions.md): MCP read tools for querying, counting, summarizing transactions and reading comments, matches, and annotations.
- [Transaction write MCP reference](https://docs.breadbox.sh/mcp/reference/transactions-write.md): Compound writes, comments, and tag add/remove on transactions. Categorization lives on its own page.
- [Set up MCP for Claude and AI agents](https://docs.breadbox.sh/mcp/setup.md): Connect Claude (Desktop, web, mobile), Claude Code, ChatGPT, Codex, Openclaw, Manus, and other MCP-compatible agents to your Breadbox instance.
- [MCP tools for querying financial data](https://docs.breadbox.sh/mcp/tools.md): A human-readable walkthrough of the MCP tools an agent is most likely to use against Breadbox — so you know exactly what surface area you're granting an AI client. See the MCP Reference tab for the full enumeration.
- [Onboard your Breadbox instance](https://docs.breadbox.sh/quickstart.md): After you've installed Breadbox, use this guide to run the first-run wizard, connect your first bank, and hook up an AI agent.
- [Categories: the two-level classification hierarchy](https://docs.breadbox.sh/transactions/categories.md): Understand Breadbox's two-level category hierarchy, how categories are assigned, and how to override, manage, and import categories via the API.
- [How Breadbox syncs, stores, and exposes transactions](https://docs.breadbox.sh/transactions/overview.md): Learn how Breadbox syncs, stores, and represents transactions from your connected bank accounts, including field definitions and amount conventions.
- [Review workflow](https://docs.breadbox.sh/transactions/review-workflow.md): Understand how Breadbox's needs-review tag, seeded rule, and tag-based workflow combine into a configurable review workflow you can extend or turn off.
- [Rules: automate categorization, tagging, and annotations](https://docs.breadbox.sh/transactions/rules.md): Build condition-based rules that categorize, apply tags, and leave annotations on transactions automatically — at sync time or retroactively — using Breadbox's recursive AND/OR/NOT condition engine with a multi-stage pipeline.
- [Tags](https://docs.breadbox.sh/transactions/tags.md): Open-ended labels you attach to transactions — the primitive Breadbox uses to coordinate review, flagging, and other workflows between humans and agents.

## OpenAPI Specs

- [openapi](https://raw.githubusercontent.com/canalesb93/breadbox/main/openapi.yaml)