> ## 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.

# Categories: the two-level classification hierarchy

> Understand Breadbox's two-level category hierarchy, how categories are assigned, and how to override, manage, and import categories via the API.

Breadbox uses a two-level category hierarchy to classify every transaction. Categories come from your bank provider by default, but you can override them manually or have rules assign them automatically.

## Two-level hierarchy

Every transaction can carry two category fields:

* **`category_primary`** — the top-level group, such as `FOOD_AND_DRINK` or `TRANSPORTATION`
* **`category_detailed`** — a granular subcategory nested under the primary, such as `FOOD_AND_DRINK_GROCERIES` or `TRANSPORTATION_GAS_AND_FUEL`

The detailed category always shares its parent's prefix. For example, all food-related subcategories start with `FOOD_AND_DRINK_`.

## Where categories come from

A transaction's category can be set by three sources, in increasing order of precedence:

1. **Provider-assigned** — Plaid and Teller classify transactions automatically during sync using their own enrichment pipelines. These values populate `category_primary` and `category_detailed` on initial import.
2. **Rule-assigned** — Breadbox's rules engine can override the provider category based on conditions you define. See [Auto-categorize transactions with rules](/transactions/rules).
3. **Manually overridden** — You can set a category directly on any transaction from the dashboard or via the API. Manual overrides take the highest precedence and are protected from being overwritten by rules.

## The `category_override` flag

When you manually set a transaction's category, Breadbox marks it with <Tooltip headline="category_override" tip="Who last set the category: 'none' (rule-applied or unset), 'agent' (AI-set), or 'user' (manually set — protected from automatic changes).">`category_override = 'user'`</Tooltip>. This signals to the rules engine that the transaction has a deliberate human assignment and should not be touched.

<Note>
  Rules that would otherwise reassign the category are skipped for any transaction where `category_override` is not `'none'`. Tags and comments from rules still apply — only `set_category` actions are suppressed.
</Note>

To clear a manual override and return to the provider default, call `DELETE /api/v1/transactions/{id}/category`. This removes the override and re-enables rule-based categorization on the next sync.

## Overriding a category from the dashboard

<Steps>
  <Step title="Open the transaction">
    Navigate to **Transactions** in the dashboard sidebar and click any transaction to open its detail view.
  </Step>

  <Step title="Edit the category">
    Click the category field or the edit icon next to it. A dropdown appears showing all available categories.
  </Step>

  <Step title="Select a category">
    Choose the category you want. The change is saved immediately and `category_override` is set to `'user'`.
  </Step>
</Steps>

You can also override categories in bulk from the transactions list view using the bulk actions menu.

## Managing categories via the API

Breadbox lets you create your own categories, update existing ones, merge duplicates, and delete categories you no longer need. The snippets below are a quick tour — see the full [Categories API](/api/overview) reference for every parameter, response shape, and error code.

<AccordionGroup>
  <Accordion title="List all categories" icon="list">
    ```bash theme={null}
    curl -H "X-API-Key: bb_your_key" \
      http://localhost:8080/api/v1/categories
    ```
  </Accordion>

  <Accordion title="Override a transaction's category" icon="pencil">
    ```bash theme={null}
    curl -X PATCH \
      -H "X-API-Key: bb_your_key" \
      -H "Content-Type: application/json" \
      -d '{"category_id": "cat_abc123"}' \
      http://localhost:8080/api/v1/transactions/txn_xyz/category
    ```
  </Accordion>

  <Accordion title="Reset a category to the provider default" icon="rotate-ccw">
    ```bash theme={null}
    curl -X DELETE \
      -H "X-API-Key: bb_your_key" \
      http://localhost:8080/api/v1/transactions/txn_xyz/category
    ```
  </Accordion>

  <Accordion title="Create a custom category" icon="plus">
    ```bash theme={null}
    curl -X POST \
      -H "X-API-Key: bb_your_key" \
      -H "Content-Type: application/json" \
      -d '{"slug": "income-side-projects", "name": "Side Projects", "primary_slug": "income"}' \
      http://localhost:8080/api/v1/categories
    ```
  </Accordion>

  <Accordion title="Update a category" icon="pencil">
    ```bash theme={null}
    curl -X PUT \
      -H "X-API-Key: bb_your_key" \
      -H "Content-Type: application/json" \
      -d '{"name": "Freelance Income"}' \
      http://localhost:8080/api/v1/categories/cat_abc123
    ```
  </Accordion>

  <Accordion title="Merge a category into another" icon="merge">
    Merging reassigns all transactions from the source category to the target, then deletes the source.

    ```bash theme={null}
    curl -X POST \
      -H "X-API-Key: bb_your_key" \
      -H "Content-Type: application/json" \
      -d '{"target_id": "cat_target123"}' \
      http://localhost:8080/api/v1/categories/cat_source456/merge
    ```
  </Accordion>

  <Accordion title="Delete a category" icon="trash-2">
    ```bash theme={null}
    curl -X DELETE \
      -H "X-API-Key: bb_your_key" \
      http://localhost:8080/api/v1/categories/cat_abc123
    ```
  </Accordion>

  <Accordion title="Batch-categorize multiple transactions" icon="layers">
    Set the category on up to 500 transactions in a single request. Each item pairs a transaction with its target category, so you can assign different categories in one call.

    ```bash theme={null}
    curl -X POST \
      -H "X-API-Key: bb_your_key" \
      -H "Content-Type: application/json" \
      -d '{
        "items": [
          { "transaction_id": "txn_aaa", "category_slug": "food_and_drink_groceries" },
          { "transaction_id": "txn_bbb", "category_slug": "transportation_gas" }
        ]
      }' \
      http://localhost:8080/api/v1/transactions/batch-categorize
    ```
  </Accordion>
</AccordionGroup>

## Importing and exporting categories as TSV

You can export your entire category tree as a tab-separated values file, edit it externally, and re-import it. This is useful for bulk setup or migrating a category structure from another system.

<CodeGroup>
  ```bash Export categories theme={null}
  curl -H "X-API-Key: bb_your_key" \
    http://localhost:8080/api/v1/categories/export \
    -o categories.tsv
  ```

  ```bash Import categories theme={null}
  curl -X POST \
    -H "X-API-Key: bb_your_key" \
    -H "Content-Type: text/tab-separated-values" \
    --data-binary @categories.tsv \
    http://localhost:8080/api/v1/categories/import
  ```
</CodeGroup>

<Tip>
  Export your categories before making large structural changes. The TSV export gives you a backup you can re-import if needed.
</Tip>