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

> List, get, create, update, and delete annotation configs (categorical, continuous, freeform) using the Arize Go SDK.

An annotation config defines the shape of human annotations attached to spans or dataset examples. Each config is one of three types: `categorical` (a fixed set of labels), `continuous` (a numeric score range), or `freeform` (open text). The `Get`, `UpdateCategorical`, `UpdateContinuous`, `UpdateFreeform`, and `Delete` methods accept either a config name or an ID — when a name is passed, the parent `Space` (name or ID) is also required. Each config type has its own dedicated `Create*` and `Update*` method so required fields stay statically typed.

## List Annotation Configs

`List` returns a paginated list of annotation configs. `Space`, when non-empty, accepts a space name or ID and restricts results to that space. `Name`, when non-empty, applies a case-insensitive substring filter on the annotation config name.

**Signature:**

```go theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
func (c *Client) List(ctx context.Context, req ListRequest) (*ListAnnotationConfigs, error)
```

**Usage Example:**

```go theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
package main

import (
    "context"
    "errors"
    "fmt"
    "log"

    "github.com/Arize-ai/client-go-v2/arize"
    "github.com/Arize-ai/client-go-v2/arize/annotationconfigs"
)

func main() {
    client, err := arize.NewClient(arize.Config{APIKey: "your-api-key"})
    if err != nil {
        log.Fatal(err)
    }

    resp, err := client.AnnotationConfigs.List(context.Background(), annotationconfigs.ListRequest{
        Space: "your-space-name-or-id",
        Limit: 25,
    })
    if err != nil {
        var unauthorized *arize.UnauthorizedError
        if errors.As(err, &unauthorized) {
            log.Fatalf("unauthorized: %v", unauthorized)
        }
        log.Fatal(err)
    }

    for _, ac := range resp.AnnotationConfigs {
        if d, err := ac.Discriminator(); err == nil {
            fmt.Printf("annotation config (type=%s)\n", d)
        }
    }
}
```

## Get an Annotation Config

`Get` returns a single annotation config, resolving by name or ID. The returned `AnnotationConfig` is a discriminated union — call `ac.AsCategoricalAnnotationConfig()`, `AsContinuousAnnotationConfig()`, or `AsFreeformAnnotationConfig()` to extract the typed variant after checking the discriminator.

**Signature:**

```go theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
func (c *Client) Get(ctx context.Context, req GetRequest) (*AnnotationConfig, error)
```

**Usage Example:**

```go theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
package main

import (
    "context"
    "errors"
    "fmt"
    "log"

    "github.com/Arize-ai/client-go-v2/arize"
    "github.com/Arize-ai/client-go-v2/arize/annotationconfigs"
)

func main() {
    client, err := arize.NewClient(arize.Config{APIKey: "your-api-key"})
    if err != nil {
        log.Fatal(err)
    }

    ac, err := client.AnnotationConfigs.Get(
        context.Background(),
        annotationconfigs.GetRequest{
            AnnotationConfig: "your-config-name-or-id",
            Space:            "your-space-name-or-id",
        },
    )
    if err != nil {
        var notFound *arize.NotFoundError
        if errors.As(err, &notFound) {
            log.Fatalf("annotation config not found: %v", notFound)
        }
        log.Fatal(err)
    }

    if d, err := ac.Discriminator(); err == nil && d == string(annotationconfigs.AnnotationConfigTypeCategorical) {
        cat, err := ac.AsCategoricalAnnotationConfig()
        if err != nil {
            log.Fatal(err)
        }
        fmt.Printf("categorical %s with %d values\n", cat.Name, len(cat.Values))
    }
}
```

## Create a Categorical Annotation Config

`CreateCategorical` creates a new categorical annotation config (a fixed set of labeled values a scorer can choose from), resolving the parent space by name or ID. `Values` is required; `OptimizationDirection` is optional and defaults to `none` on the server.

**Signature:**

```go theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
func (c *Client) CreateCategorical(
    ctx context.Context,
    req CreateCategoricalRequest,
) (*AnnotationConfig, error)
```

**Usage Example:**

```go theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
package main

import (
    "context"
    "errors"
    "fmt"
    "log"

    "github.com/Arize-ai/client-go-v2/arize"
    "github.com/Arize-ai/client-go-v2/arize/annotationconfigs"
)

func main() {
    client, err := arize.NewClient(arize.Config{APIKey: "your-api-key"})
    if err != nil {
        log.Fatal(err)
    }

    ac, err := client.AnnotationConfigs.CreateCategorical(
        context.Background(),
        annotationconfigs.CreateCategoricalRequest{
            Space: "your-space-name-or-id",
            Name:  "quality",
            Values: []annotationconfigs.CategoricalAnnotationValue{
                {Label: "correct"},
                {Label: "incorrect"},
            },
            OptimizationDirection: annotationconfigs.OptimizationDirectionMaximize,
        },
    )
    if err != nil {
        var conflict *arize.ConflictError
        if errors.As(err, &conflict) {
            log.Fatalf("annotation config already exists: %v", conflict)
        }
        log.Fatal(err)
    }

    if cat, err := ac.AsCategoricalAnnotationConfig(); err == nil {
        fmt.Printf("created categorical annotation config %s\n", cat.Name)
    }
}
```

## Create a Continuous Annotation Config

`CreateContinuous` creates a new continuous annotation config (a numeric score within a fixed range), resolving the parent space by name or ID. `MinimumScore` and `MaximumScore` are required.

**Signature:**

```go theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
func (c *Client) CreateContinuous(
    ctx context.Context,
    req CreateContinuousRequest,
) (*AnnotationConfig, error)
```

**Usage Example:**

```go theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
package main

import (
    "context"
    "errors"
    "fmt"
    "log"

    "github.com/Arize-ai/client-go-v2/arize"
    "github.com/Arize-ai/client-go-v2/arize/annotationconfigs"
)

func main() {
    client, err := arize.NewClient(arize.Config{APIKey: "your-api-key"})
    if err != nil {
        log.Fatal(err)
    }

    ac, err := client.AnnotationConfigs.CreateContinuous(
        context.Background(),
        annotationconfigs.CreateContinuousRequest{
            Space:                 "your-space-name-or-id",
            Name:                  "helpfulness",
            MinimumScore:          0,
            MaximumScore:          1,
            OptimizationDirection: annotationconfigs.OptimizationDirectionMaximize,
        },
    )
    if err != nil {
        var conflict *arize.ConflictError
        if errors.As(err, &conflict) {
            log.Fatalf("annotation config already exists: %v", conflict)
        }
        log.Fatal(err)
    }

    if cont, err := ac.AsContinuousAnnotationConfig(); err == nil {
        fmt.Printf("created continuous annotation config %s\n", cont.Name)
    }
}
```

## Create a Freeform Annotation Config

`CreateFreeform` creates a new freeform annotation config (open-ended text feedback with no predefined scale), resolving the parent space by name or ID. Only `Space` and `Name` are required.

**Signature:**

```go theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
func (c *Client) CreateFreeform(
    ctx context.Context,
    req CreateFreeformRequest,
) (*AnnotationConfig, error)
```

**Usage Example:**

```go theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
package main

import (
    "context"
    "errors"
    "fmt"
    "log"

    "github.com/Arize-ai/client-go-v2/arize"
    "github.com/Arize-ai/client-go-v2/arize/annotationconfigs"
)

func main() {
    client, err := arize.NewClient(arize.Config{APIKey: "your-api-key"})
    if err != nil {
        log.Fatal(err)
    }

    ac, err := client.AnnotationConfigs.CreateFreeform(
        context.Background(),
        annotationconfigs.CreateFreeformRequest{
            Space: "your-space-name-or-id",
            Name:  "comments",
        },
    )
    if err != nil {
        var conflict *arize.ConflictError
        if errors.As(err, &conflict) {
            log.Fatalf("annotation config already exists: %v", conflict)
        }
        log.Fatal(err)
    }

    if free, err := ac.AsFreeformAnnotationConfig(); err == nil {
        fmt.Printf("created freeform annotation config %s\n", free.Name)
    }
}
```

## Update a Categorical Annotation Config

`UpdateCategorical` patches an existing categorical annotation config, resolving by name or ID. All patch fields are optional — leave a field `nil` to preserve its current value. When non-nil, `Values` replaces the full set of allowed labels (2–100 items).

**Signature:**

```go theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
func (c *Client) UpdateCategorical(
    ctx context.Context,
    req UpdateCategoricalRequest,
) (*AnnotationConfig, error)
```

**Usage Example:**

```go theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
package main

import (
    "context"
    "errors"
    "fmt"
    "log"

    "github.com/Arize-ai/client-go-v2/arize"
    "github.com/Arize-ai/client-go-v2/arize/annotationconfigs"
)

func main() {
    client, err := arize.NewClient(arize.Config{APIKey: "your-api-key"})
    if err != nil {
        log.Fatal(err)
    }

    newValues := []annotationconfigs.CategoricalAnnotationValue{
        {Label: "correct"},
        {Label: "partial"},
        {Label: "incorrect"},
    }
    ac, err := client.AnnotationConfigs.UpdateCategorical(
        context.Background(),
        annotationconfigs.UpdateCategoricalRequest{
            AnnotationConfig: "your-config-name-or-id",
            Space:            "your-space-name-or-id",
            Values:           &newValues,
        },
    )
    if err != nil {
        var notFound *arize.NotFoundError
        if errors.As(err, &notFound) {
            log.Fatalf("annotation config not found: %v", notFound)
        }
        log.Fatal(err)
    }

    if cat, err := ac.AsCategoricalAnnotationConfig(); err == nil {
        fmt.Printf("updated categorical annotation config %s (%d values)\n", cat.Name, len(cat.Values))
    }
}
```

## Update a Continuous Annotation Config

`UpdateContinuous` patches an existing continuous annotation config, resolving by name or ID. All patch fields are optional — leave a field `nil` to preserve its current value.

**Signature:**

```go theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
func (c *Client) UpdateContinuous(
    ctx context.Context,
    req UpdateContinuousRequest,
) (*AnnotationConfig, error)
```

**Usage Example:**

```go theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
package main

import (
    "context"
    "errors"
    "fmt"
    "log"

    "github.com/Arize-ai/client-go-v2/arize"
    "github.com/Arize-ai/client-go-v2/arize/annotationconfigs"
)

func main() {
    client, err := arize.NewClient(arize.Config{APIKey: "your-api-key"})
    if err != nil {
        log.Fatal(err)
    }

    newMax := 10.0
    ac, err := client.AnnotationConfigs.UpdateContinuous(
        context.Background(),
        annotationconfigs.UpdateContinuousRequest{
            AnnotationConfig: "your-config-name-or-id",
            Space:            "your-space-name-or-id",
            MaximumScore:     &newMax,
        },
    )
    if err != nil {
        var notFound *arize.NotFoundError
        if errors.As(err, &notFound) {
            log.Fatalf("annotation config not found: %v", notFound)
        }
        log.Fatal(err)
    }

    if cont, err := ac.AsContinuousAnnotationConfig(); err == nil {
        fmt.Printf("updated continuous annotation config %s\n", cont.Name)
    }
}
```

## Update a Freeform Annotation Config

`UpdateFreeform` patches an existing freeform annotation config, resolving by name or ID. Only `Name` may be patched — leave it `nil` to preserve the current value.

**Signature:**

```go theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
func (c *Client) UpdateFreeform(
    ctx context.Context,
    req UpdateFreeformRequest,
) (*AnnotationConfig, error)
```

**Usage Example:**

```go theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
package main

import (
    "context"
    "errors"
    "fmt"
    "log"

    "github.com/Arize-ai/client-go-v2/arize"
    "github.com/Arize-ai/client-go-v2/arize/annotationconfigs"
)

func main() {
    client, err := arize.NewClient(arize.Config{APIKey: "your-api-key"})
    if err != nil {
        log.Fatal(err)
    }

    newName := "renamed-comments"
    ac, err := client.AnnotationConfigs.UpdateFreeform(
        context.Background(),
        annotationconfigs.UpdateFreeformRequest{
            AnnotationConfig: "your-config-name-or-id",
            Space:            "your-space-name-or-id",
            Name:             &newName,
        },
    )
    if err != nil {
        var notFound *arize.NotFoundError
        if errors.As(err, &notFound) {
            log.Fatalf("annotation config not found: %v", notFound)
        }
        log.Fatal(err)
    }

    if free, err := ac.AsFreeformAnnotationConfig(); err == nil {
        fmt.Printf("updated freeform annotation config %s\n", free.Name)
    }
}
```

## Delete an Annotation Config

`Delete` removes an annotation config, resolving by name or ID. It returns only an error.

**Signature:**

```go theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
func (c *Client) Delete(ctx context.Context, req DeleteRequest) error
```

**Usage Example:**

```go theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
package main

import (
    "context"
    "errors"
    "log"

    "github.com/Arize-ai/client-go-v2/arize"
    "github.com/Arize-ai/client-go-v2/arize/annotationconfigs"
)

func main() {
    client, err := arize.NewClient(arize.Config{APIKey: "your-api-key"})
    if err != nil {
        log.Fatal(err)
    }

    err = client.AnnotationConfigs.Delete(
        context.Background(),
        annotationconfigs.DeleteRequest{
            AnnotationConfig: "your-config-name-or-id",
            Space:            "your-space-name-or-id",
        },
    )
    if err != nil {
        var notFound *arize.NotFoundError
        if errors.As(err, &notFound) {
            log.Printf("no annotation config to remove: %v", notFound)
            return
        }
        log.Fatal(err)
    }
}
```