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

# Extraction Categories API Overview

> Create and manage extraction categories — named sets of dispositions evaluated together in a single LLM pass after every call.

## What are Extraction Categories?

**Extractions** is the Bolna feature that automatically captures structured data from call transcripts after every call. A **category** is a named set of **dispositions** evaluated together in a single LLM pass — one category means one LLM call per conversation. Each disposition is a single question inside its category.

```
Agent
└── Extractions (feature)
    └── Category  (one LLM pass, owns the model)
        └── Disposition  (a single question)
```

The category owns the `model` used for its pass: every disposition in the category is evaluated by the category's model in one call. A category belongs to the agent it was created for, and that agent runs every disposition the category holds.

## Endpoints

```
GET    /agent/{agent_id}/extraction-categories   List an agent's categories with their dispositions
POST   /agent/{agent_id}/extraction-categories   Create a category and attach it to the agent
PATCH  /extraction-categories/{category_id}      Rename a category or change its model
DELETE /extraction-categories/{category_id}      Delete a category and all of its dispositions
```

Dispositions are created and placed into categories through the [Dispositions API](/docs/api-reference/dispositions/overview): pass `category_id` (preferred) or a `category` name on create or update — at most one of the two per payload. A `category` name that does not match one of the agent's categories creates a fresh category.

## Category Object

```json theme={"system"}
{
  "id": "9b2e8f10-4c7d-4e2a-9f31-6a8d5c1b0e42",
  "name": "Lead Quality",
  "model": "gpt-4.1-mini",
  "agent_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2026-03-01T10:00:00Z",
  "updated_at": "2026-03-15T14:30:00Z"
}
```

| Field        | Type   | Description                                                 |
| ------------ | ------ | ----------------------------------------------------------- |
| `id`         | UUID   | Unique identifier                                           |
| `name`       | string | Category name, unique among the agent's attached categories |
| `model`      | string | LLM used for the category's extraction pass                 |
| `agent_id`   | UUID   | The agent this category is attached to                      |
| `created_at` | string | ISO 8601 timestamp when the category was created            |
| `updated_at` | string | ISO 8601 timestamp of the last update                       |

## Supported Models

A category's `model` must be one of:

* `gpt-4.1-mini`
* `gpt-4.1-nano`
* `gpt-4o-mini`
* `gpt-5-mini`
* `gpt-5-nano`
* `gpt-5.4-mini`
* `gpt-5.6-luna`
* `gemini-3.5-flash`
* `gemini-3.5-flash-lite`

Any other value is rejected with a `422` error. A category created implicitly by a `category` name on a disposition takes that disposition's `model`, falling back to `gpt-4.1-mini`.

## Lifecycle Rules

* **Move a disposition between categories**: update the disposition with the new `category_id` (see [Update Disposition](/docs/api-reference/dispositions/update)). There is no separate move endpoint.
* **Renaming a category** rewrites the `category` label on all of its dispositions in the same transaction, so extraction results stay grouped consistently.
* **Deleting a category deletes its dispositions.** The category owns them. Historical call execution results are not affected.
* **Empty categories are removed automatically**: when a move or delete removes a category's last disposition, the category itself is deleted.
* **Category names are per agent.** Two agents can each have a category named `Sales`; these are independent categories.
* **An update must change something.** `PATCH` accepts `name`, `model`, or both, but an empty body is rejected with a `422` error.

<Note>
  For a full walkthrough of the Extractions feature, answer types, output format, and best practices, see the [Using Extractions](/docs/prompting/using-extractions) guide.
</Note>