Extraction Categories API Overview

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: 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

{
  "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). 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.

For a full walkthrough of the Extractions feature, answer types, output format, and best practices, see the Using Extractions guide.

Overview

Agents

Calls

Executions

Tasks

Batches

Workflows

Workflow Campaigns

Workflow Executions

Inbound

Phone Numbers

Knowledgebases

Dispositions