---
title: "Set labels on a prompt version"
method: PUT
path: "/v2/prompt-versions/{version_id}/labels"
tags: ["Prompts"]
---

# Set labels on a prompt version

`PUT /v2/prompt-versions/{version_id}/labels`

Set (replace) all labels on a prompt version. This is an idempotent
operation. If a label already exists on another version of the same
prompt, it will be moved to this version.

Labels not included in the request will be removed from this version.

<Note>This endpoint is in beta, read more [here](https://arize.com/docs/ax/rest-reference#api-version-stages).</Note>

## Path parameters

- `version_id` string, required — A universally unique identifier (base64-encoded opaque string).

## Request body

- SetPromptVersionLabelsRequest — Labels to set on a prompt version.
  - `labels` string[], required — Array of label names to set on the version. Replaces all existing labels on this version. Pass an empty array to remove all labels from this version. Labels are unique per prompt — a label can only be assigned to one version at a time. If a label in this array is currently assigned to a different version of the same prompt, it will be moved to this version automatically (no error is raised).

## Response `200`

A prompt version object

- PromptVersion — A prompt version represents a specific snapshot of a prompt's configuration. Each version captures the messages, model settings, and parameters at a point in time. Versions are immutable once created and are identified by a commit hash.
  - `id` string, required — The prompt version ID
  - `prompt_id` string, required — The prompt ID this version belongs to
  - `commit_hash` string, required — The commit hash of this version
  - `commit_message` string, required — The commit message describing the changes in this version
  - `messages` LLMMessage[], required — The messages that make up the prompt template
    - `role` 'USER' | 'ASSISTANT' | 'SYSTEM' | 'TOOL', required — The role of the message author
    - `content` string, nullable — The content of the message
    - `tool_call_id` string — The ID of the tool call this message is responding to
    - `tool_calls` ToolCall[] — Tool calls generated by the model
      - `id` string — The ID of the tool call
      - `type` 'FUNCTION', required — The type of tool call
      - `function` ToolCallFunction, required — The function to call
        - `name` string, required — The name of the function
        - `arguments` string, required — The arguments to the function as a JSON string
  - `input_variable_format` 'F_STRING' | 'MUSTACHE' | 'NONE', required — The format for input variables in the prompt messages. Defaults to `F_STRING` if not provided. - `F_STRING`: Single curly braces ({variable_name}) - `MUSTACHE`: Double curly braces ({{variable_name}}) - `NONE`: **Deprecated.** Treated as `F_STRING`. Will be removed in a future version.
  - `provider` 'OPEN_AI' | 'AZURE_OPEN_AI' | 'AWS_BEDROCK' | 'VERTEX_AI' | 'ANTHROPIC' | 'CUSTOM', required — The LLM provider to use
  - `model` string, required — The model to use for the call
  - `invocation_params` InvocationParams — Parameters for the LLM invocation
    - `temperature` number — Sampling temperature (higher = more random)
    - `max_tokens` integer — Maximum number of tokens to generate
    - `max_completion_tokens` integer — Maximum number of completion tokens to generate
    - `top_p` number — Nucleus sampling parameter
    - `frequency_penalty` number — Frequency penalty (-2.0 to 2.0)
    - `presence_penalty` number — Presence penalty (-2.0 to 2.0)
    - `stop` string[] — Stop sequences
    - `response_format` ResponseFormat — Response format configuration
      - `type` 'TEXT' | 'JSON_OBJECT' | 'JSON_SCHEMA' — The response format type
      - `json_schema` JsonSchemaConfig — JSON schema configuration (when type is JSON_SCHEMA)
        - `name` string — The name of the JSON schema
        - `description` string — A description of the JSON schema
        - `schema` object — The JSON schema object
        - `strict` boolean — Whether to enforce strict schema validation. Defaults to `false`.
    - `tool_config` ToolConfig — Tool configuration for the LLM invocation
      - `tools` ToolDefinition[] — List of tool definitions available to the model
      - `tool_choice` unknown
    - `top_k` integer — Top-K sampling parameter. A top-K of 1 means the next selected token is the most probable (greedy decoding).
    - `thinking_level` string — Controls how much reasoning the model performs before responding. Supported by Gemini 3.x models. Accepted values: 'low', 'high'.
    - `thinking_budget` integer — Maximum tokens the model may use for internal reasoning. Supported by Gemini 2.5 models. Range: 0-24576 (Flash/Flash-Lite) or 128-32768 (Pro). Set 0 to disable thinking on Flash models.
    - `reasoning_effort` string — Controls how much reasoning the model performs before responding. Supported by OpenAI o-series and GPT-5 models. o-series: 'low' | 'medium' | 'high'. GPT-5: 'none' | 'low' | 'medium' | 'high' | 'xhigh'.
    - `verbosity` string — Controls the verbosity of model output. Supported by OpenAI GPT-5 series. Accepted values: 'low' | 'medium' | 'high'.
  - `provider_params` ProviderParams — Provider-specific parameters
    - `azure_params` AzureParams — Azure OpenAI specific parameters
      - `azure_deployment_name` string — The Azure deployment name
      - `azure_openai_endpoint` string — The Azure OpenAI endpoint URL
      - `azure_openai_version` string — The Azure OpenAI API version
    - `anthropic_headers` AnthropicHeaders — Anthropic-specific headers
      - `anthropic_beta` string[], nullable — Anthropic beta feature flags
    - `anthropic_version` string — Anthropic API version
    - `bedrock_options` BedrockOptions — AWS Bedrock options
      - `use_converse_endpoint` boolean — Whether to use the AWS Bedrock Converse endpoint. Defaults to `false`.
    - `region` string — Region for the model deployment
  - `created_at` string, date-time, required — When the version was created
  - `created_by_user_id` string, required — The user ID of the user who created this version
  - `labels` string[] — Label names currently pointing to this version (e.g., "production", "staging"). Labels are case-sensitive.

## Other responses

- `400` — Invalid request
- `401` — Authentication is required
- `403` — Insufficient permissions to access this resource
- `404` — Not found
- `422` — Unprocessable entity
- `429` — Rate limit exceeded

---

[API](https://skmtc.net/arize-ai/apis/arize-rest-api.md) · [All operations](https://skmtc.net/arize-ai/apis/arize-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/arize-ai/arize-rest-api/versions/2ce448f1de13/schema)