Prompts - Arize AX Docs

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

A prompt is a versioned LLM prompt template that lives in a space. Each prompt has one or more immutable versions identified by commit hash; labels (e.g. production) point to a specific version. The Get, Update, Delete, ListVersions, CreateVersion, and GetVersionByLabel methods accept either a prompt name or an ID — when a name is passed, the parent Space (name or ID) is also required so the SDK can resolve the name to a unique ID. GetVersion, SetVersionLabels, and DeleteVersionLabel take strict version IDs only.

List Prompts

List returns a paginated list of prompts. When Space is a base64 resource ID, it is sent as the space_id filter (exact match); otherwise it is sent as the space_name filter (case-insensitive substring match). Signature:

func (c *Client) List(ctx context.Context, req ListRequest) (*PromptList, 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/prompts"
)

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

    resp, err := client.Prompts.List(context.Background(), prompts.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 _, p := range resp.Prompts {
        fmt.Printf("%s: %s\n", p.Id, p.Name)
    }
}

Get a Prompt

Get returns a single prompt (with one of its versions), resolving by name or ID. If VersionID or Label is set, the response carries that specific version; otherwise the latest version is returned. VersionID and Label are mutually exclusive. Signature:

func (c *Client) Get(ctx context.Context, req GetRequest) (*PromptWithVersion, 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/prompts"
)

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

    pwv, err := client.Prompts.Get(
        context.Background(),
        prompts.GetRequest{
            Prompt: "your-prompt-name-or-id",
            Space:  "your-space-name-or-id",
            Label:  "production",
        },
    )
    if err != nil {
        var notFound *arize.NotFoundError
        if errors.As(err, &notFound) {
            log.Fatalf("prompt not found: %v", notFound)
        }
        log.Fatal(err)
    }

    fmt.Printf("prompt %s, version %s\n", pwv.Id, pwv.Version.CommitHash)
}

Create a Prompt

Create creates a new prompt with its initial version, resolving the parent space by name or ID. Signature:

func (c *Client) Create(ctx context.Context, req CreateRequest) (*PromptWithVersion, 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/prompts"
)

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

    content := "You are a helpful assistant."
    pwv, err := client.Prompts.Create(
        context.Background(),
        prompts.CreateRequest{
            Space: "your-space-name-or-id",
            Name:  "your-prompt-name",
            Version: prompts.PromptVersionCreate{
                CommitMessage: "initial version",
                Provider:      prompts.LlmProviderOpenAi,
                Messages: []prompts.LLMMessage{
                    {Role: prompts.MessageRoleSystem, Content: &content},
                },
            },
        },
    )
    if err != nil {
        var conflict *arize.ConflictError
        if errors.As(err, &conflict) {
            log.Fatalf("prompt already exists: %v", conflict)
        }
        log.Fatal(err)
    }

    fmt.Printf("created prompt %s\n", pwv.Id)
}

Update a Prompt

Update patches an existing prompt’s metadata, resolving the target by name or ID, and returns the updated prompt. Description is a pointer — nil preserves the existing value, a pointer to an empty string clears the field. Signature:

func (c *Client) Update(ctx context.Context, req UpdateRequest) (*Prompt, 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/prompts"
)

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

    newDescription := "updated description"
    p, err := client.Prompts.Update(
        context.Background(),
        prompts.UpdateRequest{
            Prompt:      "your-prompt-name-or-id",
            Space:       "your-space-name-or-id",
            Description: &newDescription,
        },
    )
    if err != nil {
        var notFound *arize.NotFoundError
        if errors.As(err, &notFound) {
            log.Fatalf("prompt not found: %v", notFound)
        }
        log.Fatal(err)
    }

    fmt.Printf("updated prompt %s\n", p.Id)
}

Delete a Prompt

Delete removes a prompt, 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/prompts"
)

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

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

List Versions

ListVersions returns a paginated list of versions for a prompt, resolving the prompt by name or ID. Signature:

func (c *Client) ListVersions(
    ctx context.Context,
    req ListVersionsRequest,
) (*PromptVersionList, 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/prompts"
)

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

    resp, err := client.Prompts.ListVersions(
        context.Background(),
        prompts.ListVersionsRequest{
            Prompt: "your-prompt-name-or-id",
            Space:  "your-space-name-or-id",
            Limit:  25,
        },
    )
    if err != nil {
        var notFound *arize.NotFoundError
        if errors.As(err, &notFound) {
            log.Fatalf("prompt not found: %v", notFound)
        }
        log.Fatal(err)
    }

    for _, v := range resp.PromptVersions {
        fmt.Printf("%s: %s\n", v.Id, v.CommitMessage)
    }
}

Create a Version

CreateVersion creates a new version for an existing prompt, resolving the prompt by name or ID. Signature:

func (c *Client) CreateVersion(
    ctx context.Context,
    req CreateVersionRequest,
) (*PromptVersion, 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/prompts"
)

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

    content := "You are a concise assistant."
    v, err := client.Prompts.CreateVersion(
        context.Background(),
        prompts.CreateVersionRequest{
            Prompt:        "your-prompt-name-or-id",
            Space:         "your-space-name-or-id",
            CommitMessage: "more concise tone",
            Provider:      prompts.LlmProviderOpenAi,
            Messages: []prompts.LLMMessage{
                {Role: prompts.MessageRoleSystem, Content: &content},
            },
        },
    )
    if err != nil {
        var badRequest *arize.BadRequestError
        if errors.As(err, &badRequest) {
            log.Fatalf("invalid version: %v", badRequest)
        }
        log.Fatal(err)
    }

    fmt.Printf("created version %s\n", v.Id)
}

Get a Version

GetVersion returns a single prompt version by its ID. Version IDs are strict IDs — no name resolution is performed. Signature:

func (c *Client) GetVersion(ctx context.Context, req GetVersionRequest) (*PromptVersion, 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/prompts"
)

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

    v, err := client.Prompts.GetVersion(
        context.Background(),
        prompts.GetVersionRequest{VersionID: "your-version-id"},
    )
    if err != nil {
        var notFound *arize.NotFoundError
        if errors.As(err, &notFound) {
            log.Fatalf("version not found: %v", notFound)
        }
        log.Fatal(err)
    }

    fmt.Printf("version %s: %s\n", v.Id, v.CommitMessage)
}

Get a Version by Label

GetVersionByLabel returns the prompt version pointed to by a label (e.g. "production"), resolving the prompt by name or ID. Signature:

func (c *Client) GetVersionByLabel(
    ctx context.Context,
    req GetVersionByLabelRequest,
) (*PromptVersion, 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/prompts"
)

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

    v, err := client.Prompts.GetVersionByLabel(
        context.Background(),
        prompts.GetVersionByLabelRequest{
            Prompt:    "your-prompt-name-or-id",
            Space:     "your-space-name-or-id",
            LabelName: "production",
        },
    )
    if err != nil {
        var notFound *arize.NotFoundError
        if errors.As(err, &notFound) {
            log.Fatalf("no version with that label: %v", notFound)
        }
        log.Fatal(err)
    }

    fmt.Printf("production points at %s\n", v.Id)
}

Set Version Labels

SetVersionLabels assigns one or more labels to a specific prompt version, replacing all existing labels, and returns the updated label set. Pass an empty slice to remove all labels. Version IDs are strict IDs. Signature:

func (c *Client) SetVersionLabels(
    ctx context.Context,
    req SetVersionLabelsRequest,
) (*PromptVersionLabels, 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/prompts"
)

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

    labels, err := client.Prompts.SetVersionLabels(
        context.Background(),
        prompts.SetVersionLabelsRequest{
            VersionID: "your-version-id",
            Labels:    []string{"production", "stable"},
        },
    )
    if err != nil {
        var badRequest *arize.BadRequestError
        if errors.As(err, &badRequest) {
            log.Fatalf("invalid label set: %v", badRequest)
        }
        log.Fatal(err)
    }

    fmt.Printf("version now has labels: %v\n", labels.Labels)
}

Delete a Version Label

DeleteVersionLabel removes a single label from a specific prompt version. It returns only an error. Version IDs are strict IDs. Signature:

func (c *Client) DeleteVersionLabel(ctx context.Context, req DeleteVersionLabelRequest) 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/prompts"
)

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

    err = client.Prompts.DeleteVersionLabel(
        context.Background(),
        prompts.DeleteVersionLabelRequest{
            VersionID: "your-version-id",
            LabelName: "production",
        },
    )
    if err != nil {
        var notFound *arize.NotFoundError
        if errors.As(err, &notFound) {
            log.Printf("no such label: %v", notFound)
            return
        }
        log.Fatal(err)
    }
}

​List Prompts

​Get a Prompt

​Create a Prompt

​Update a Prompt

​Delete a Prompt

​List Versions

​Create a Version

​Get a Version

​Get a Version by Label

​Set Version Labels

​Delete a Version Label

List Prompts

Get a Prompt

Create a Prompt

Update a Prompt

Delete a Prompt

List Versions

Create a Version

Get a Version

Get a Version by Label

Set Version Labels

Delete a Version Label