> ## Documentation Index
> Fetch the complete documentation index at: https://breadbox-mintlify-7401d007.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Tags

> Open-ended labels you attach to transactions — the primitive Breadbox uses to coordinate review, flagging, and other workflows between humans and agents.

Tags are open-ended labels attached to transactions. They are the primitive Breadbox uses for any workflow that asks "which transactions are in this state?" — the review queue is a tag view, and you can build your own (flagged, disputed, tax-deductible) the same way.

Unlike categories, tags are not hierarchical and a transaction can carry any number of them at once. The endpoints for listing, attaching, and detaching tags live on the [Tags API](/api/overview) reference; filtering transactions by tag is on [Transactions API](/api/overview).

## Anatomy of a tag

| Field          | Description                                                                                                   |
| -------------- | ------------------------------------------------------------------------------------------------------------- |
| `slug`         | Stable URL-safe identifier (e.g., `needs-review`, `tax-deductible`). Used in rule actions and MCP tool calls. |
| `display_name` | Human-readable label shown in the dashboard.                                                                  |
| `description`  | Optional short explanation of what the tag means.                                                             |
| `color`        | Hex color for the dashboard pill.                                                                             |

Each tag also has an 8-character <Tooltip headline="Short ID" tip="8-character base62 alias accepted interchangeably with the full UUID `id` in any API or MCP tool input.">`short_id`</Tooltip> alongside its internal UUID, same as every other entity in Breadbox.

## Tag removal notes

When you remove a tag from a transaction, you can optionally include a short note. If provided, the note is recorded as an annotation on the transaction's activity timeline — useful for workflow flags like <Tooltip headline="needs-review tag" tip="Seeded tag used as the default review queue. A system rule auto-tags every new transaction on sync; removing the tag takes the row out of the queue." cta="Review workflow" href="/transactions/review-workflow">`needs-review`</Tooltip> or `disputed`, where the reason for resolution is worth keeping.

## Seeded tags

Breadbox ships with one tag out of the box:

| Slug           | What it's for                                                                                                                                                  |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `needs-review` | Applied to every newly-synced transaction by a seeded `on_create` rule. Removing it closes a review. See [the review workflow](/transactions/review-workflow). |

Everything else is yours to define. Create new tags from the **Tags** page in the dashboard, or via the admin API.

## How tags get applied

A tag reaches a transaction one of four ways — and the activity timeline records which one:

<Steps>
  <Step title="Manual (user)">
    From the transaction detail view in the dashboard, add or remove a tag directly. Recorded as `added_by_type = user`.
  </Step>

  <Step title="Agent (MCP)">
    An AI agent connected over MCP calls `update_transactions` with `tags_to_add` or `tags_to_remove` (each entry can include an inline `note`). Recorded as `added_by_type = agent`.
  </Step>

  <Step title="Rule action">
    A transaction rule with `add_tag` or `remove_tag` in its actions fires during sync (trigger <Tooltip headline="on_create stage" tip="The rule pipeline stage that fires once for every newly-synced transaction. The seeded `needs-review` rule runs here." cta="Rule pipeline" href="/transactions/rules">`on_create`</Tooltip>) or retroactively (trigger `on_apply`). Recorded as `added_by_type = rule`, with the rule's ID on the annotation so you can trace why the tag landed.
  </Step>

  <Step title="System">
    Reserved for Breadbox itself — seeds, backfills, internal workflows. You won't normally apply system tags; they show up in the timeline when they do.
  </Step>
</Steps>

## Querying by tag

Tag-based filters are available through the **MCP tool** `query_transactions` (use `count_only: true` for a count-only response) and the admin dashboard. The REST API does not currently expose tag filters on `GET /api/v1/transactions` — if you need to query by tag over HTTP, use MCP. See [issue #624](https://github.com/canalesb93/breadbox/issues/624) for the V1 parity plan.

MCP tools accept two filter shapes:

* **`tags`** — all-of semantics. A transaction must carry every listed slug.
* **`any_tag`** — any-of semantics. A transaction must carry at least one.

```text theme={null}
query_transactions(tags=["needs-review"])                      # the review backlog
query_transactions(tags=["needs-review", "high-amount"])       # both tags
query_transactions(any_tag=["flagged", "disputed"])            # either tag
```

In the dashboard, the transactions list page accepts `?tags=needs-review` as a URL parameter and renders the matching rows — this is what powers the `/reviews` redirect.

## Tags in rules

Tags are both a **condition** and an **action** in the [rule DSL](/transactions/rules):

* As a **condition**, rules can match on `tags contains "needs-review"` or `tags not_contains "disputed"` to gate which transactions they affect.
* As an **action**, rules can `add_tag` or `remove_tag` to manage tag state automatically. A rule that adds a tag can be scheduled (trigger `on_create` during sync) or run retroactively against historical data.

This is how you build workflow tags that behave like `needs-review`: define a tag, then write rules that apply or remove it under the conditions you care about.

## Example: a disputed-charges workflow

Suppose you want a dedicated queue for charges you intend to contest with your bank. The ingredients:

<Steps>
  <Step title="Create a `disputed` tag">
    From **Tags** in the dashboard, add a new tag with slug `disputed` and a description like "Charge we're contesting — remove with outcome note when resolved."
  </Step>

  <Step title="Apply it when you see a bad charge">
    Tag the transaction manually from the dashboard, or have an agent tag it by name pattern via `update_transactions`. No rule necessary — you apply it reactively.
  </Step>

  <Step title="Use `?tags=disputed` as your queue">
    Same pattern as review: filter the transactions list to `tags=disputed` and the page becomes your dispute-tracking view. No new UI needed.
  </Step>

  <Step title="Resolve with a note">
    When the bank refunds or rejects the dispute, remove the tag and record the outcome ("Refunded \$42.18 on 2026-04-14"). The note is saved to the activity timeline and you can look back months later and see exactly how each dispute played out.
  </Step>
</Steps>

The review workflow is the same shape — just with a different tag slug.