Annotation Configs - Arize AX Docs

The annotationconfigs client methods are currently in ALPHA. The API may change without notice. A one-time warning is emitted on first use.

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:

func (c *Client) List(ctx context.Context, req ListRequest) (*AnnotationConfigList, error)

Usage Example:

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:

func (c *Client) Get(ctx context.Context, req GetRequest) (*AnnotationConfig, error)

Usage Example:

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:

func (c *Client) CreateCategorical(
    ctx context.Context,
    req CreateCategoricalRequest,
) (*AnnotationConfig, error)

Usage Example:

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:

func (c *Client) CreateContinuous(
    ctx context.Context,
    req CreateContinuousRequest,
) (*AnnotationConfig, error)

Usage Example:

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:

func (c *Client) CreateFreeform(
    ctx context.Context,
    req CreateFreeformRequest,
) (*AnnotationConfig, error)

Usage Example:

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:

func (c *Client) UpdateCategorical(
    ctx context.Context,
    req UpdateCategoricalRequest,
) (*AnnotationConfig, error)

Usage Example:

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:

func (c *Client) UpdateContinuous(
    ctx context.Context,
    req UpdateContinuousRequest,
) (*AnnotationConfig, error)

Usage Example:

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:

func (c *Client) UpdateFreeform(
    ctx context.Context,
    req UpdateFreeformRequest,
) (*AnnotationConfig, error)

Usage Example:

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:

func (c *Client) Delete(ctx context.Context, req DeleteRequest) error

Usage Example:

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)
    }
}

​List Annotation Configs

​Get an Annotation Config

​Create a Categorical Annotation Config

​Create a Continuous Annotation Config

​Create a Freeform Annotation Config

​Update a Categorical Annotation Config

​Update a Continuous Annotation Config

​Update a Freeform Annotation Config

​Delete an Annotation Config

List Annotation Configs

Get an Annotation Config

Create a Categorical Annotation Config

Create a Continuous Annotation Config

Create a Freeform Annotation Config

Update a Categorical Annotation Config

Update a Continuous Annotation Config

Update a Freeform Annotation Config

Delete an Annotation Config