Create a prompt version

curl --request POST \
  --url https://api.arize.com/v2/prompts/{prompt_id}/versions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "commit_message": "Updated system prompt for better responses",
  "input_variable_format": "f_string",
  "provider": "open_ai",
  "model": "gpt-4",
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": "Hello, {name}!"
    }
  ]
}
'

{
  "id": "pv_001",
  "prompt_id": "prompt_001",
  "commit_hash": "abc123def456",
  "commit_message": "Updated system prompt",
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": "Hello, {name}!"
    }
  ],
  "input_variable_format": "f_string",
  "provider": "open_ai",
  "model": "gpt-4",
  "invocation_params": {
    "temperature": 0.7,
    "max_tokens": 1000
  },
  "provider_params": {},
  "created_at": "2024-01-02T12:00:00Z",
  "created_by_user_id": "user_12345"
}

Prompts

Create a prompt version

Create a new version of an existing prompt.

Payload Requirements

A commit_message is required.
At least one message is required in messages.
Do not include system-managed fields on input: id, commit_hash, created_at, created_by_user_id. Requests that contain these fields will be rejected.
provider is required. input_variable_format defaults to f_string if not provided.

Valid example (create)

{
  "commit_message": "Updated system prompt for better responses",
  "input_variable_format": "f_string",
  "provider": "open_ai",
  "model": "gpt-4",
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": "Hello, {name}!"
    }
  ]
}

Invalid example (missing required commit_message)

{
  "input_variable_format": "f_string",
  "provider": "open_ai",
  "messages": [
    {
      "role": "user",
      "content": "Hello!"
    }
  ]
}

This endpoint is in beta, read more here.

POST

prompts

{prompt_id}

versions

Create a prompt version

curl --request POST \
  --url https://api.arize.com/v2/prompts/{prompt_id}/versions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "commit_message": "Updated system prompt for better responses",
  "input_variable_format": "f_string",
  "provider": "open_ai",
  "model": "gpt-4",
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": "Hello, {name}!"
    }
  ]
}
'

{
  "id": "pv_001",
  "prompt_id": "prompt_001",
  "commit_hash": "abc123def456",
  "commit_message": "Updated system prompt",
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": "Hello, {name}!"
    }
  ],
  "input_variable_format": "f_string",
  "provider": "open_ai",
  "model": "gpt-4",
  "invocation_params": {
    "temperature": 0.7,
    "max_tokens": 1000
  },
  "provider_params": {},
  "created_at": "2024-01-02T12:00:00Z",
  "created_by_user_id": "user_12345"
}

Authorizations

Authorization

string

header

required

Most Arize AI endpoints require authentication. For those endpoints that require authentication, include your API key in the request header using the format

Path Parameters

prompt_id

string

required

The unique prompt identifier (base64) A universally unique identifier (base64-encoded opaque string).

Example:

"RW50aXR5OjEyMzQ1"

Body

application/json

Body containing prompt version creation parameters

commit_message

string

required

Commit message describing this version

provider

enum<string>

required

The LLM provider to use

Available options:

open_ai,

azure_open_ai,

aws_bedrock,

vertex_ai,

anthropic,

custom

messages

object[]

required

The messages that make up the prompt template

Minimum array length: 1

Show child attributes

input_variable_format

enum<string>

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.

Available options:

f_string,

mustache,

none

model

string

The model to use for the call. Optional. If omitted, no default model is set on the version.

invocation_params

object

Parameters for the LLM invocation. Optional. Defaults to empty (no invocation parameters).

Show child attributes

provider_params

object

Provider-specific parameters. Optional. Defaults to empty (no provider-specific parameters).

Show child attributes

Response

A prompt version object

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.

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

object[]

required

The messages that make up the prompt template

Show child attributes

input_variable_format

enum<string>

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.

Available options:

f_string,

mustache,

none

provider

enum<string>

required

The LLM provider to use

Available options:

open_ai,

azure_open_ai,

aws_bedrock,

vertex_ai,

anthropic,

custom

model

string

required

The model to use for the call

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

invocation_params

object

LLM invocation parameters for this version. When absent, no invocation parameters were set on this version.

Show child attributes

provider_params

object

Provider-specific parameters for this version. When absent, no provider-specific parameters were set on this version.

Show child attributes

labels

string[]

Label names currently pointing to this version (e.g., "production", "staging"). Labels are case-sensitive.

List prompt versions Resolve a label to a prompt version

⌘I