> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bitfab.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Categories

> Group assertions and scenarios by what they check, and read experiment results one category at a time

## Overview

A **category** is a named grouping for [assertions](https://docs.bitfab.ai/primitives/assertions.md) and [scenarios](https://docs.bitfab.ai/primitives/scenarios.md) in your organization, with a title and a description. Use one for each kind of check you care about, such as "Mandate compliance", "Rebooking", or "Tone with upset customers".

* An assertion belongs to at most one category.
* A scenario can belong to any number.
* Categories belong to the organization, not to one traced function. A function's **Categories** page shows the same categories with counts for that function only.

Categories are for organizing. Nothing about a category is approved or reviewed.

## Why Categorize

* **Experiment results by kind of check.** An [experiment's](https://docs.bitfab.ai/primitives/experiments.md) rollup has one row per category, so you can see that a change fixed rebooking but regressed tone.
* **Sharper generated assertions.** When Bitfab generates assertions, it files each one under the category it fits and records why. Passing `categoryIds` limits generation to those categories.
* **A review queue per topic.** The **Assertions** page filters by category, so one person can review every assertion about one kind of behavior.

## Creating and Editing Categories

Ask your coding agent:

```
Group the assertions on checkout-agent into categories by what they check
Create a category called "Rebooking" for assertions about changing a flight
```

The agent uses `save_category` to create or rename a category and `save_trace_assertions` to file assertions into it. The **New category** button on the **Categories** page shows the prompt to use.

From the SDKs:

```typescript TypeScript theme={null}
const category = await client.categories.save({
  title: "Mandate compliance",
  description: "Checks explicit user instructions",
})
await client.traces.saveAssertions({
  traceId,
  assertions: [{ assertion: "Escalates conflicting calendar requests", category_id: category.id }],
})
```

```python Python theme={null}
category = client.categories.save(
    "Mandate compliance", description="Checks explicit user instructions"
)
client.traces.save_assertions(
    trace_id,
    [{"assertion": "Escalates conflicting calendar requests", "category_id": category["id"]}],
)
```

Pass `category_id: null` (`None` in Python) on a save to clear an assertion's category. Leaving the field out keeps the category it has. To file a trace's scenario under categories, your agent uses `save_trace_categories`, which replaces the trace's whole set of categories.

## Deleting a Category

Deleting a category keeps everything filed under it. Its assertions, their verdicts, and its scenarios stay, filed under one category fewer. Ask your coding agent to delete it, which calls `delete_category`, or call `categories.delete` from an SDK.

## Tools and Methods

| Operation | MCP tool | SDK |
| - | - | - |
| List or read categories | `list_categories`, `get_category` | `categories.list`, `categories.get` |
| Create, rename, or redescribe | `save_category` | `categories.save` |
| File an assertion | `save_trace_assertions` (`category_id`) | `category_id` on assertion saves |
| File a trace's scenario | `save_trace_categories` | Not available |
| Delete | `delete_category` | `categories.delete` |

See the [TypeScript](https://docs.bitfab.ai/reference/typescript.md#categories) reference for the full types.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.