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

# Annotation Configs

> Create custom labels for human feedback and data curation. Manage categorical, continuous, and freeform annotation configs programmatically.

Create custom labels that can be added to represent this human feedback. Annotation configs allow teams and subject matter experts to label data and curate high-quality datasets.

## Key Capabilities

* Create categorical, continuous, and freeform annotation configs within spaces
* List annotation configs with pagination support
* Retrieve annotation configs by name or ID
* Update annotation config fields by type
* Delete annotation configs when no longer needed

## List Annotation Configs

List all annotation configs you have access to, with optional filtering by space or name.

```python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
resp = client.annotation_configs.list(
    space="your-space-name-or-id",  # optional
    name="accuracy",                # optional substring filter
    limit=50,
)

print(resp)
```

For details on pagination, field introspection, and data conversion (to dict/JSON/DataFrame), see [Response Objects](/docs/api-clients/python/version-8/overview#response-objects).

## Create an Annotation Config

Three types are supported, each created with a dedicated method: `create_categorical`, `create_continuous`, and `create_freeform`. Annotation config names must be unique within the target space.

### Categorical

A categorical annotation config with discrete labeled values and optional scores.

```python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
from arize.annotation_configs.types import (
    CategoricalAnnotationValueRequest,
    OptimizationDirection,
)

resp = client.annotation_configs.create_categorical(
    name="accuracy",
    space="your-space-name-or-id",
    values=[
        CategoricalAnnotationValueRequest(label="accurate", score=1),
        CategoricalAnnotationValueRequest(label="inaccurate", score=0),
    ],
    optimization_direction=OptimizationDirection.MAXIMIZE,  # optional
)

print(resp)
```

### Continuous

A continuous annotation config with a numeric score range.

```python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
from arize.annotation_configs.types import OptimizationDirection

resp = client.annotation_configs.create_continuous(
    name="relevance",
    space="your-space-name-or-id",
    minimum_score=0.0,
    maximum_score=1.0,
    optimization_direction=OptimizationDirection.MAXIMIZE,  # optional
)

print(resp)
```

### Freeform

A freeform annotation config for free-text feedback with no structured scoring.

```python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
resp = client.annotation_configs.create_freeform(
    name="reviewer-notes",
    space="your-space-name-or-id",
)

print(resp)
```

## Get an Annotation Config

Retrieve a specific annotation config by name or ID. When using a name, provide `space` to disambiguate.

```python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
resp = client.annotation_configs.get(
    annotation_config="annotation-config-name-or-id",
    space="your-space-name-or-id",  # required when using a name
)

print(resp)
```

## Update an Annotation Config

Update an annotation config by type. Only the fields you pass are changed; omitted fields are left unchanged. The stored config must already be of the matching type.

### Update Categorical

```python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
from arize.annotation_configs.types import (
    CategoricalAnnotationValueRequest,
    OptimizationDirection,
)

resp = client.annotation_configs.update_categorical(
    annotation_config="annotation-config-name-or-id",
    space="your-space-name-or-id",  # required when using a name
    name="accuracy-v2",                                  # optional
    values=[                                             # optional; replaces the full label set
        CategoricalAnnotationValueRequest(label="accurate", score=1),
        CategoricalAnnotationValueRequest(label="partial", score=0.5),
        CategoricalAnnotationValueRequest(label="inaccurate", score=0),
    ],
    optimization_direction=OptimizationDirection.MAXIMIZE,  # optional
)

print(resp)
```

### Update Continuous

```python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
from arize.annotation_configs.types import OptimizationDirection

resp = client.annotation_configs.update_continuous(
    annotation_config="annotation-config-name-or-id",
    space="your-space-name-or-id",  # required when using a name
    name="relevance-v2",              # optional
    minimum_score=0.0,                # optional
    maximum_score=5.0,                # optional
    optimization_direction=OptimizationDirection.MAXIMIZE,  # optional
)

print(resp)
```

### Update Freeform

```python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
resp = client.annotation_configs.update_freeform(
    annotation_config="annotation-config-name-or-id",
    space="your-space-name-or-id",  # required when using a name
    name="reviewer-notes-v2",         # optional
)

print(resp)
```

## Delete an Annotation Config

Delete an annotation config by name or ID. This operation is irreversible. There is no response from this call.

```python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
client.annotation_configs.delete(
    annotation_config="annotation-config-name-or-id",
    space="your-space-name-or-id",  # required when using a name
)

print("Annotation config deleted successfully")
```